libwebsockets
Lightweight C library for HTML5 websockets
lws-jpeg.h
Go to the documentation of this file.
1 /*
2  * lws jpeg
3  *
4  * Copyright (C) 2019 - 2022 Andy Green <andy@warmcat.com>
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  *
24  * Based on public domain original with notice -->
25  *
26  * picojpeg.c v1.1 - Public domain, Rich Geldreich <richgel99@gmail.com>
27  * Nov. 27, 2010 - Initial release
28  * Feb. 9, 2013 - Added H1V2/H2V1 support, cleaned up macros, signed shift fixes
29  * Also integrated and tested changes from Chris Phoenix <cphoenix@gmail.com>.
30  *
31  * This version is rewritten for lws, changing the whole approach to decode on
32  * demand to issue a line of output at a time, statefully. This version is
33  * licensed MIT to match the rest of lws.
34  */
35 
36 typedef struct lws_jpeg lws_jpeg_t;
37 
38 /**
39  * lws_jpeg_new() - Create new JPEG decode object
40  *
41  * Returns a new jpeg decoding object, which should be destroyed with
42  * lws_jpeg_free() when done with, or NULL if OOM.
43  */
44 LWS_VISIBLE LWS_EXTERN lws_jpeg_t *
46 
47 /**
48  * lws_jpeg_free() - Destroy a JPEG decode object
49  *
50  * \param j: Pointer to the decode object to destroy and set to NULL
51  *
52  * This also frees any sub-allocations in the object.
53  */
54 LWS_VISIBLE LWS_EXTERN void
56 
57 /**
58  * lws_jpeg_emit_next_line() - deocde the next line
59  *
60  * \param j: the decode object
61  * \param ppix: pointer to a pointer set to the line's decoded pixel data
62  * \param buf: pointer to a const uint8_t array of jpeg input
63  * \param size: pointer to the count of bytes available at *buf
64  * \param hold_at_metadata: true if we should not advance to decode
65  *
66  * Make jpeg input available to the decoder so it can issue the next line's
67  * worth of pixels. If the call consumed any input, *buf and *size are
68  * adjusted accordingly.
69  *
70  * The decoder is stateful so it is not sensitive to the chunk size for the
71  * input.
72  *
73  * If \p hold_at_metadata is set, then the decoder will only go as far as
74  * picking out the metadata like image dimensions, but not start the decode,
75  * which requires the >30KB heap allocation. This lets you put off for as long
76  * as possible committing to the decode allocation... this only helps overall
77  * if you have flow controlled the incoming PNG data.
78  *
79  * Return will be one of LWS_SRET_WANT_INPUT is the decoder is stalled waiting
80  * for more input to be provided, LWS_SRET_WANT_OUTPUT is the decoder stopped
81  * because it had produced a whole line of output pixels (which can be found
82  * starting at *ppix), LWS_SRET_OK is it completed and LWS_SRET_FATAL or larger
83  * if the decode failed.
84  *
85  * The output at *ppix is either 3-byte per pixel RGB, or 1-byte grayscale, you
86  * can query lws_jpeg_get_components() to find out how many bytes per pixel.
87  */
88 LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
89 lws_jpeg_emit_next_line(lws_jpeg_t *j, const uint8_t **ppix,
90  const uint8_t **buf, size_t *size, char hold_at_metadata);
91 
92 LWS_VISIBLE LWS_EXTERN unsigned int
94 LWS_VISIBLE LWS_EXTERN unsigned int
96 LWS_VISIBLE LWS_EXTERN unsigned int
98 LWS_VISIBLE LWS_EXTERN unsigned int
100 LWS_VISIBLE LWS_EXTERN unsigned int
102 LWS_VISIBLE LWS_EXTERN unsigned int