1/*
2 * uPNG -- derived from LodePNG version 20100808
3 *
4 * Copyright (c) 2005-2010 Lode Vandevenne
5 * Copyright (c) 2010 Sean Middleditch
6 * Copyright (c) 2021-2022 Andy Green <andy@warmcat.com>
7 *
8 * This software is provided 'as-is', without any express or implied
9 * warranty. In no event will the authors be held liable for any damages
10 * arising from the use of this software.
11
12 * Permission is granted to anyone to use this software for any purpose,
13 * including commercial applications, and to alter it and redistribute it
14 * freely, subject to the following restrictions:
15 *
16 * 1. The origin of this software must not be misrepresented; you must not
17 * claim that you wrote the original software. If you use this software
18 * in a product, an acknowledgment in the product documentation would be
19 * appreciated but is not required.
20 *
21 * 2. Altered source versions must be plainly marked as such, and must not be
22 * misrepresented as being the original software.
23 *
24 * 3. This notice may not be removed or altered from any source
25 * distribution.
26 *
27 * The above notice is the ZLIB license, libpng also uses it.
28 *
29 * This version is based on upng project's fork of lodepng and rewritten for
30 * lws, changing the whole approach to decode on demand to issue a line of
31 * output at a time, statefully.
32 */
33
34typedef enum lws_upng_format_t {
35 LWS_UPNG_BADFORMAT,
36 LWS_UPNG_RGB8,
37 LWS_UPNG_RGB16,
38 LWS_UPNG_RGBA8,
39 LWS_UPNG_RGBA16,
40 LWS_UPNG_LUMINANCE1,
41 LWS_UPNG_LUMINANCE2,
42 LWS_UPNG_LUMINANCE4,
43 LWS_UPNG_LUMINANCE8,
44 LWS_UPNG_LUMINANCE_ALPHA1,
45 LWS_UPNG_LUMINANCE_ALPHA2,
46 LWS_UPNG_LUMINANCE_ALPHA4,
47 LWS_UPNG_LUMINANCE_ALPHA8
48} lws_upng_format_t;
49
50struct inflator_ctx;
51typedef struct lws_upng_t lws_upng_t;
52
53/**
54 * lws_upng_new() - Create new UPNG decode object
55 *
56 * Returns a new PNG decoding object, which should be destroyed with
57 * lws_upng_free() when done with, or NULL if OOM.
58 */
59LWS_VISIBLE LWS_EXTERN lws_upng_t *
60lws_upng_new(void);
61
62/**
63 * lws_upng_free() - Destroy a PNG decode object
64 *
65 * \param upng: Pointer to the decode object to destroy and set to NULL
66 *
67 * This also frees any sub-allocations in the object.
68 */
69LWS_VISIBLE LWS_EXTERN void
70lws_upng_free(lws_upng_t **upng);
71
72/**
73 * lws_upng_emit_next_line() - deocde the next line
74 *
75 * \param upng: the decode object
76 * \param ppix: pointer to a pointer set to the line's decoded pixel data
77 * \param buf: pointer to a const uint8_t array of PNG input
78 * \param size: pointer to the count of bytes available at *buf
79 * \param hold_at_metadata: true if we should not advance to decode
80 *
81 * Make PNG input available to the decoder so it can issue the next line's
82 * worth of pixels. If the call consumed any input, *buf and *size are
83 * adjusted accordingly.
84 *
85 * The decoder is stateful so it is not sensitive to the chunk size for the
86 * input.
87 *
88 * If \p hold_at_metadata is set, then the decoder will only go as far as
89 * picking out the metadata like image dimensions, but not start the decode,
90 * which requires the >30KB heap allocation. This lets you put off for as long
91 * as possible committing to the decode allocation... this only helps overall
92 * if you have flow controlled the incoming PNG data.
93 *
94 * Return will be one of LWS_SRET_WANT_INPUT is the decoder is stalled waiting
95 * for more input to be provided, LWS_SRET_WANT_OUTPUT is the decoder stopped
96 * because it had produced a whole line of output pixels (which can be found
97 * starting at *ppix), LWS_SRET_OK is it completed and LWS_SRET_FATAL or larger
98 * if the decode failed.
99 */
100LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
101lws_upng_emit_next_line(lws_upng_t *upng, const uint8_t **ppix,
102 const uint8_t **buf, size_t *size,
103 char hold_at_metadata);
104
105LWS_VISIBLE LWS_EXTERN unsigned int
106lws_upng_get_width(const lws_upng_t *upng);
107LWS_VISIBLE LWS_EXTERN unsigned int
108lws_upng_get_height(const lws_upng_t *upng);
109LWS_VISIBLE LWS_EXTERN unsigned int
110lws_upng_get_bpp(const lws_upng_t *upng);
111LWS_VISIBLE LWS_EXTERN unsigned int
112lws_upng_get_bitdepth(const lws_upng_t *upng);
113LWS_VISIBLE LWS_EXTERN unsigned int
114lws_upng_get_components(const lws_upng_t *upng);
115LWS_VISIBLE LWS_EXTERN unsigned int
116lws_upng_get_pixelsize(const lws_upng_t *upng);
117LWS_VISIBLE LWS_EXTERN lws_upng_format_t
118lws_upng_get_format(const lws_upng_t *upng);
119
120/**
121 * lws_upng_inflator_create() - create a gzip inflator context
122 *
123 * \param outring: pointer set to the output ringbuffer on exit
124 * \param outringlen: size of the output ringbuffer set on exit
125 * \param opl: pointer to set to point to ctx outpos_linear
126 * \param cl: pointer to set to point to ctx consumed_linear
127 *
128 * Creates an opaque gzip inflator object.
129 */
130LWS_VISIBLE LWS_EXTERN struct inflator_ctx *
131lws_upng_inflator_create(const uint8_t **outring, size_t *outringlen,
132 size_t **opl, size_t **cl);
133
134/**
135 * lws_upng_inflate_data() - inflate compressed data statefully
136 *
137 * \param inf: inflator context created with lws_upng_inflator_create()
138 * \param buf: NULL to continue consumption of existing input, or new input
139 * \param len: ignored if \p buf is NULL, else amount of new input at \p buf
140 *
141 * Tries to progress the inflation. If output is available, \p *opl will be
142 * further along than before it was called. \p *cl should be set to \p opl
143 * to consume the available output data.
144 *
145 * Output is into a ringfuffer, typically sized at 32KB. \p opl and \p cl
146 * are "linear", that is extend beyond the ringbuffer. They should be modulo
147 * outringlen (given when the inflator was created) when accessing outring.
148 */
149LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
150lws_upng_inflate_data(struct inflator_ctx *inf, const void *buf, size_t len);
151
152/**
153 * lws_upng_inflator_destroy() - destroys the inflation context and ringbuffer
154 *
155 * \p inf: pointer to pointer to inflation context
156 *
157 * Frees the inflation context and its allocations, and sets \p *inf to NULL.
158 */
159LWS_VISIBLE LWS_EXTERN void
160lws_upng_inflator_destroy(struct inflator_ctx **inf);
161