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
36typedef 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 */
44LWS_VISIBLE LWS_EXTERN lws_jpeg_t *
45lws_jpeg_new(void);
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 */
54LWS_VISIBLE LWS_EXTERN void
55lws_jpeg_free(lws_jpeg_t **j);
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 */
88LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
89lws_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
92LWS_VISIBLE LWS_EXTERN unsigned int
93lws_jpeg_get_width(const lws_jpeg_t *j);
94LWS_VISIBLE LWS_EXTERN unsigned int
95lws_jpeg_get_height(const lws_jpeg_t *j);
96LWS_VISIBLE LWS_EXTERN unsigned int
97lws_jpeg_get_bpp(const lws_jpeg_t *j);
98LWS_VISIBLE LWS_EXTERN unsigned int
99lws_jpeg_get_bitdepth(const lws_jpeg_t *j);
100LWS_VISIBLE LWS_EXTERN unsigned int
101lws_jpeg_get_components(const lws_jpeg_t *j);
102LWS_VISIBLE LWS_EXTERN unsigned int
103lws_jpeg_get_pixelsize(const lws_jpeg_t *j);
104
105