Skip to content

Commit 95e2f07

Browse files
randy408randy408
committed
docs: add encode api, updates [skip-ci]
added encode api docs moved some things from decode.md to context.md and vice versa
1 parent fc661a8 commit 95e2f07

4 files changed

Lines changed: 314 additions & 64 deletions

File tree

‎docs/api.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
* [Error handling](errors.md)
44
* [Versioning](version.md)
5-
* [Context](context.md)
6-
* [Retrieving and setting chunks](chunk.md)
7-
* [Decode](decode.md)
5+
* [Common](context.md)
6+
* [Getting and setting chunk data](chunk.md)
7+
* [Decoder API](decode.md)
8+
* [Encoder API](encode.md)

‎docs/context.md‎

Lines changed: 136 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,24 +16,108 @@ typedef struct spng_ctx spng_ctx;
1616
```c
1717
enum spng_ctx_flags
1818
{
19-
SPNG_CTX_IGNORE_ADLER32 = 1 /* ignore checksum in DEFLATE streams */
19+
SPNG_CTX_IGNORE_ADLER32 = 1, /* Ignore checksum in DEFLATE streams */
20+
SPNG_CTX_ENCODER = 2 /* Create an encoder context */
2021
};
2122
```
2223

23-
# spng_crc_action
24+
# spng_read_fn
25+
```c
26+
typedef int spng_read_fn(spng_ctx *ctx, void *user, void *dest, size_t length)
27+
```
28+
29+
Type definition for callback passed to `spng_set_png_stream()` for decoders.
30+
31+
A read callback function should copy `length` bytes to `dest` and return 0 or
32+
`SPNG_IO_EOF`/`SPNG_IO_ERROR` on error.
33+
34+
35+
# spng_write_fn
36+
```c
37+
typedef int spng_write_fn(spng_ctx *ctx, void *user, void *src, size_t length)
38+
```
39+
40+
Type definition for callback passed to `spng_set_png_stream()` for encoders.
41+
42+
The write callback should process `length` bytes and return 0 or `SPNG_IO_ERROR` on error.
43+
44+
45+
# spng_format
46+
```c
47+
enum spng_format
48+
{
49+
SPNG_FMT_RGBA8 = 1,
50+
SPNG_FMT_RGBA16 = 2,
51+
SPNG_FMT_RGB8 = 4,
52+
53+
SPNG_FMT_GA8 = 16,
54+
SPNG_FMT_GA16 = 32,
55+
SPNG_FMT_G8 = 64,
56+
57+
/* No conversion or scaling */
58+
SPNG_FMT_PNG = 256, /* host-endian */
59+
SPNG_FMT_RAW = 512 /* big-endian */
60+
};
61+
```
62+
63+
The channels are always in [byte-order](https://en.wikipedia.org/wiki/RGBA_color_model#RGBA8888) representation.
64+
65+
# spng_filter
66+
```c
67+
enum spng_filter
68+
{
69+
SPNG_FILTER_NONE = 0,
70+
SPNG_FILTER_SUB = 1,
71+
SPNG_FILTER_UP = 2,
72+
SPNG_FILTER_AVERAGE = 3,
73+
SPNG_FILTER_PAETH = 4
74+
};
75+
```
2476

77+
# spng_row_info
2578
```c
26-
enum spng_crc_action
79+
struct spng_row_info
2780
{
28-
/* Default for critical chunks */
29-
SPNG_CRC_ERROR = 0,
81+
uint32_t scanline_idx;
82+
uint32_t row_num;
83+
int pass;
84+
uint8_t filter;
85+
};
86+
```
87+
88+
Contains row and scanline information, used for progressive decoding and encoding.
89+
90+
# spng_option
91+
```c
92+
enum spng_option
93+
{
94+
SPNG_KEEP_UNKNOWN_CHUNKS = 1,
3095

31-
/* Discard chunk, invalid for critical chunks,
32-
since v0.6.2: default for ancillary chunks */
33-
SPNG_CRC_DISCARD = 1,
96+
SPNG_IMG_COMPRESSION_LEVEL,
97+
SPNG_IMG_WINDOW_BITS,
98+
SPNG_IMG_MEM_LEVEL,
99+
SPNG_IMG_COMPRESSION_STRATEGY,
34100

35-
/* Ignore and don't calculate checksum */
36-
SPNG_CRC_USE = 2
101+
SPNG_TEXT_COMPRESSION_LEVEL,
102+
SPNG_TEXT_WINDOW_BITS,
103+
SPNG_TEXT_MEM_LEVEL,
104+
SPNG_TEXT_COMPRESSION_STRATEGY,
105+
106+
SPNG_FILTER_CHOICE,
107+
};
108+
```
109+
110+
# spng_filter_choice
111+
```c
112+
enum spng_filter_choice
113+
{
114+
SPNG_DISABLE_FILTERING = 0,
115+
SPNG_FILTER_CHOICE_NONE = 8,
116+
SPNG_FILTER_CHOICE_SUB = 16,
117+
SPNG_FILTER_CHOICE_UP = 32,
118+
SPNG_FILTER_CHOICE_AVG = 64,
119+
SPNG_FILTER_CHOICE_PAETH = 128,
120+
SPNG_FILTER_CHOICE_ALL = (8|16|32|64|128)
37121
};
38122
```
39123

@@ -62,6 +146,27 @@ void spng_ctx_free(spng_ctx *ctx)
62146
63147
Releases context resources.
64148
149+
# spng_set_png_stream()
150+
```c
151+
int spng_set_png_stream(spng_ctx *ctx, spng_rw_fn *rw_func, void *user)
152+
```
153+
154+
Set input PNG stream or output PNG stream, depending on context type.
155+
156+
This can only be done once per context.
157+
158+
!!! info
159+
PNG's are read up to the file end marker, this is identical behavior to libpng.
160+
161+
# spng_set_png_file()
162+
```c
163+
int spng_set_png_file(spng_ctx *ctx, FILE *file)
164+
```
165+
166+
Set input PNG file or output PNG file, depending on context type.
167+
168+
This can only be done once per context.
169+
65170
# spng_set_image_limits()
66171
```c
67172
int spng_set_image_limits(spng_ctx *ctx, uint32_t width, uint32_t height)
@@ -78,13 +183,6 @@ Get image width and height limits.
78183
79184
`width` and `height` must be non-NULL.
80185
81-
# spng_set_crc_action()
82-
```c
83-
int spng_set_crc_action(spng_ctx *ctx, int critical, int ancillary)
84-
```
85-
86-
Set how chunk CRC errors should be handled for critical and ancillary chunks.
87-
88186
# spng_set_chunk_limits()
89187
```c
90188
int spng_set_chunk_limits(spng_ctx *ctx, size_t chunk_size, size_t cache_limit)
@@ -105,3 +203,24 @@ int spng_get_chunk_limits(spng_ctx *ctx, size_t *chunk_size, size_t *cache_limit
105203
```
106204
107205
Get chunk size and chunk cache limits.
206+
207+
# spng_get_row_info()
208+
```c
209+
int spng_get_row_info(spng_ctx *ctx, struct spng_row_info *row_info)
210+
```
211+
212+
Copies the current, to-be-decoded (or to-be-encoded) row's information to `row_info`.
213+
214+
# spng_set_option()
215+
```c
216+
int spng_set_option(spng_ctx *ctx, enum spng_option option, int value)
217+
```
218+
219+
Set `option` to the specified `value`.
220+
221+
# spng_get_option()
222+
```c
223+
int spng_get_option(spng_ctx *ctx, enum spng_option option, int *value)
224+
```
225+
226+
Get the value for the specified `option`.

‎docs/decode.md‎

Lines changed: 18 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,22 @@
11
# Data types
22

3+
# spng_crc_action
34
```c
4-
typedef int spng_read_fn(spng_ctx *ctx, void *user, void *dest, size_t length)
5-
```
6-
7-
Type definition for callback passed to `spng_set_png_stream()`.
8-
9-
A read callback function should copy `length` bytes to `dest` and return 0 or
10-
`SPNG_IO_EOF`/`SPNG_IO_ERROR` on error.
11-
12-
# spng_format
13-
14-
```c
15-
enum spng_format
5+
enum spng_crc_action
166
{
17-
SPNG_FMT_RGBA8 = 1,
18-
SPNG_FMT_RGBA16 = 2,
19-
SPNG_FMT_RGB8 = 4,
7+
/* Default for critical chunks */
8+
SPNG_CRC_ERROR = 0,
209

21-
SPNG_FMT_GA8 = 16,
22-
SPNG_FMT_GA16 = 32,
23-
SPNG_FMT_G8 = 64,
10+
/* Discard chunk, invalid for critical chunks,
11+
since v0.6.2: default for ancillary chunks */
12+
SPNG_CRC_DISCARD = 1,
2413

25-
/* No conversion or scaling */
26-
SPNG_FMT_PNG = 256, /* host-endian */
27-
SPNG_FMT_RAW = 512 /* big-endian */
14+
/* Ignore and don't calculate checksum */
15+
SPNG_CRC_USE = 2
2816
};
2917
```
3018

31-
The channels are always in [byte-order](https://en.wikipedia.org/wiki/RGBA_color_model#RGBA8888) representation.
32-
3319
# spng_decode_flags
34-
3520
```c
3621
enum spng_decode_flags
3722
{
@@ -166,29 +151,21 @@ This function combines the functionality of libpng's `png_set_chunk_cache_max()`
166151

167152
# API
168153

154+
See also: [spng_set_png_stream()](context.md#spng_set_png_stream), [spng_set_png_file()](context.md#spng_set_png_file).
155+
169156
# spng_set_png_buffer()
170157
```c
171158
int spng_set_png_buffer(spng_ctx *ctx, void *buf, size_t size)
172159
```
173160
174161
Set input PNG buffer, this can only be done once per context.
175162
176-
# spng_set_png_stream()
163+
# spng_set_crc_action()
177164
```c
178-
int spng_set_png_stream(spng_ctx *ctx, spng_read_fn *read_fn, void *user)
165+
int spng_set_crc_action(spng_ctx *ctx, int critical, int ancillary)
179166
```
180167

181-
Set input PNG stream, this can only be done once per context.
182-
183-
!!! info
184-
PNG's are read up to the file end marker, this is identical behavior to libpng.
185-
186-
# spng_set_png_file()
187-
```c
188-
int spng_set_png_file(spng_ctx *ctx, FILE *file)
189-
```
190-
191-
Set input PNG file, this can only be done once per context.
168+
Set how chunk CRC errors should be handled for critical and ancillary chunks.
192169

193170
# spng_decoded_image_size()
194171
```c
@@ -205,7 +182,7 @@ int spng_decode_image(spng_ctx *ctx, void *out, size_t len, int fmt, int flags)
205182
```
206183

207184
Decodes the PNG file and writes the image to `out`,
208-
the image is converted from any PNG format to the destination format `fmt`.
185+
the image is converted from the PNG format to the destination format `fmt`.
209186

210187
Interlaced images are deinterlaced, 16-bit images are converted to host-endian.
211188

@@ -249,14 +226,11 @@ This function requires the decoder to be initialized by calling
249226

250227
The width of the row is the decoded image size divided by `ihdr.height`.
251228

229+
For interlaced images rows are accessed multiple times and non-sequentially,
230+
use [spng_get_row_info()](context.md#spng_get_row_info) to get the current row number.
231+
252232
For the last row and subsequent calls the return value is `SPNG_EOI`.
253233

254234
If the image is not interlaced this function's behavior is identical to
255235
`spng_decode_scanline()`.
256236

257-
# spng_get_row_info()
258-
```c
259-
int spng_get_row_info(spng_ctx *ctx, struct spng_row_info *row_info)
260-
```
261-
262-
Copies the current, to-be-decoded row's information to `row_info`.

0 commit comments

Comments
 (0)