libwebsockets
Lightweight C library for HTML5 websockets
lws-upng.h
Go to the documentation of this file.
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 
34 typedef 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 
50 struct inflator_ctx;
51 typedef 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  */
59 LWS_VISIBLE LWS_EXTERN lws_upng_t *
60 lws_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  */
69 LWS_VISIBLE LWS_EXTERN void
70 lws_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  */
100 LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
101 lws_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 
105 LWS_VISIBLE LWS_EXTERN unsigned int
106 lws_upng_get_width(const lws_upng_t *upng);
107 LWS_VISIBLE LWS_EXTERN unsigned int
108 lws_upng_get_height(const lws_upng_t *upng);
109 LWS_VISIBLE LWS_EXTERN unsigned int
110 lws_upng_get_bpp(const lws_upng_t *upng);
111 LWS_VISIBLE LWS_EXTERN unsigned int
112 lws_upng_get_bitdepth(const lws_upng_t *upng);
113 LWS_VISIBLE LWS_EXTERN unsigned int
114 lws_upng_get_components(const lws_upng_t *upng);
115 LWS_VISIBLE LWS_EXTERN unsigned int
116 lws_upng_get_pixelsize(const lws_upng_t *upng);
117 LWS_VISIBLE LWS_EXTERN lws_upng_format_t
118 lws_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  */
130 LWS_VISIBLE LWS_EXTERN struct inflator_ctx *
131 lws_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  */
149 LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
150 lws_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  */
159 LWS_VISIBLE LWS_EXTERN void
160 lws_upng_inflator_destroy(struct inflator_ctx **inf);