Module-private declarations shared by the two PNG decoder units. More...

#include <stddef.h>
#include <stdint.h>
#include "jof_internal.h"
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for jof_png_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_png_state_t
	Whole streaming PNG decode state (module-static instance). More...

Enumerations
enum	ra8_png_const_t : uint32_t { k_ra8_png_sig_bytes = 8U , k_ra8_png_chunk_hdr = 8U , k_ra8_png_crc_bytes = 4U , k_ra8_png_ihdr_len = 13U , k_ra8_png_max_chunks = 4096U , k_ra8_png_max_len = 0x7FFFFFFFU , k_ra8_png_ring_bytes = 65536U , k_ra8_png_inbuf_bytes = 4096U , k_ra8_png_plte_max = 768U , k_ra8_png_trns_max = 256U , k_ra8_png_skip_chunk = 256U , k_ra8_png_type_ihdr = 0x49484452U , k_ra8_png_type_plte = 0x504C5445U , k_ra8_png_type_idat = 0x49444154U , k_ra8_png_type_iend = 0x49454E44U , k_ra8_png_type_trns = 0x74524E53U }
	PNG structural sizes and caps (PNG sec 5 "Datastream structure"). More...
enum	ra8_png_signature_t : uint8_t { k_ra8_png_sig_high = 0x89U , k_ra8_png_sig_cr = 0x0DU , k_ra8_png_sig_lf = 0x0AU , k_ra8_png_sig_sub = 0x1AU }
	Fixed non-ASCII bytes in the PNG signature. More...
enum	ra8_png_field_t : uint8_t { k_ra8_png_ihdr_ofs_depth = 8U , k_ra8_png_ihdr_ofs_color = 9U , k_ra8_png_ihdr_ofs_compress = 10U , k_ra8_png_ihdr_ofs_filter = 11U , k_ra8_png_ihdr_ofs_interlace = 12U , k_ra8_png_depth_8 = 8U , k_ra8_png_color_gray = 0U , k_ra8_png_color_rgb = 2U , k_ra8_png_color_pal = 3U , k_ra8_png_color_ga = 4U , k_ra8_png_color_rgba = 6U , k_ra8_png_filter_none = 0U , k_ra8_png_filter_sub = 1U , k_ra8_png_filter_up = 2U , k_ra8_png_filter_avg = 3U , k_ra8_png_filter_paeth = 4U , k_ra8_png_ch_1 = 1U , k_ra8_png_ch_2 = 2U , k_ra8_png_ch_3 = 3U , k_ra8_png_ch_4 = 4U , k_ra8_png_be_sh24 = 24U , k_ra8_png_be_sh16 = 16U , k_ra8_png_be_sh8 = 8U , k_ra8_png_opaque = 255U }
	IHDR field offsets and legal values (PNG sec 11.2.2 "IHDR"). More...

Functions
ra8_err_t	priv_jof_png_pull_exact (ra8_png_state_t st, uint8_t buf, uint32_t len)
	Pull exactly `len` bytes; EOF mid-read is a protocol error.
ra8_err_t	priv_jof_png_skip (ra8_png_state_t *st, uint32_t len)
	Discard exactly `len` source bytes (unknown / ancillary chunks).
ra8_err_t	priv_jof_png_chunk_hdr (ra8_png_state_t st, uint32_t out_len, uint32_t *out_type)
	Read one 8-byte chunk header (length + type, both big-endian).
ra8_err_t	priv_jof_png_prologue (ra8_png_state_t *st, uint16_t max_w, uint16_t max_h)
	Verify the 8-byte signature, then parse + validate the IHDR.
ra8_err_t	priv_jof_png_pre_idat (ra8_png_state_t *st, uint32_t len, uint32_t type)
	Dispatch one pre-IDAT chunk (PLTE / tRNS / ancillary / stray IEND).
ra8_err_t	priv_jof_png_finish (ra8_png_state_t *st)
	Walk the post-IDAT chunks until IEND (ancillary chunks skipped).

Detailed Description

Module-private declarations shared by the two PNG decoder units.

Tag: [Ring 4 / Domain] {World: NS}

The streaming PNG decoder is split to stay under the maintainability line cap:

jof_png_chunk.c – byte source helpers plus the chunk layer: signature/IHDR prologue, PLTE/tRNS parsing, ancillary skipping and the post-IDAT walk to IEND.
jof_png.c – the pixel layer: geometry binding, the tinfl inflate loop, scanline unfiltering/translation and the public priv_jof_png_rows() entry.

This header carries the shared decode-state type, the structural constants, and the chunk-layer prototypes the pixel layer drives.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file jof_png_internal.h.

Enumeration Type Documentation

◆ ra8_png_const_t

enum ra8_png_const_t : uint32_t

PNG structural sizes and caps (PNG sec 5 "Datastream structure").

Enumerator
k_ra8_png_sig_bytes	Signature length.
k_ra8_png_chunk_hdr	Chunk length + type fields.
k_ra8_png_crc_bytes	Trailing chunk CRC field.
k_ra8_png_ihdr_len	IHDR payload length.
k_ra8_png_max_chunks	Chunk-walk budget (hostile cap).
k_ra8_png_max_len	Max legal chunk length.
k_ra8_png_ring_bytes	Inflate ring (power of 2).
k_ra8_png_inbuf_bytes	Compressed-input chunk buffer.
k_ra8_png_plte_max	Max PLTE payload (256 * 3).
k_ra8_png_trns_max	Max palette tRNS payload.
k_ra8_png_skip_chunk	Discard-buffer granularity.
k_ra8_png_type_ihdr	"IHDR" big-endian.
k_ra8_png_type_plte	"PLTE" big-endian.
k_ra8_png_type_idat	"IDAT" big-endian.
k_ra8_png_type_iend	"IEND" big-endian.
k_ra8_png_type_trns	"tRNS" big-endian.

Definition at line 42 of file jof_png_internal.h.

◆ ra8_png_field_t

enum ra8_png_field_t : uint8_t

IHDR field offsets and legal values (PNG sec 11.2.2 "IHDR").

Enumerator
k_ra8_png_ihdr_ofs_depth	Bit-depth byte offset.
k_ra8_png_ihdr_ofs_color	Colour-type byte offset.
k_ra8_png_ihdr_ofs_compress	Compression-method offset.
k_ra8_png_ihdr_ofs_filter	Filter-method offset.
k_ra8_png_ihdr_ofs_interlace	Interlace-method offset.
k_ra8_png_depth_8	Only supported bit depth.
k_ra8_png_color_gray	Grayscale.
k_ra8_png_color_rgb	Truecolour.
k_ra8_png_color_pal	Indexed-colour.
k_ra8_png_color_ga	Grayscale + alpha.
k_ra8_png_color_rgba	Truecolour + alpha.
k_ra8_png_filter_none	Row filter: none.
k_ra8_png_filter_sub	Row filter: sub.
k_ra8_png_filter_up	Row filter: up.
k_ra8_png_filter_avg	Row filter: average.
k_ra8_png_filter_paeth	Row filter: Paeth.
k_ra8_png_ch_1	1 byte per pixel.
k_ra8_png_ch_2	2 bytes per pixel.
k_ra8_png_ch_3	3 bytes per pixel.
k_ra8_png_ch_4	4 bytes per pixel.
k_ra8_png_be_sh24	Big-endian assembly shifts.
k_ra8_png_be_sh16	Big-endian assembly shifts.
k_ra8_png_be_sh8	Big-endian assembly shifts.
k_ra8_png_opaque	Fully-opaque alpha value.

Definition at line 73 of file jof_png_internal.h.

◆ ra8_png_signature_t

enum ra8_png_signature_t : uint8_t

Fixed non-ASCII bytes in the PNG signature.

Enumerator
k_ra8_png_sig_high	High-bit signature byte.
k_ra8_png_sig_cr	Carriage return byte.
k_ra8_png_sig_lf	Line feed byte.
k_ra8_png_sig_sub	DOS EOF byte.

Definition at line 62 of file jof_png_internal.h.

Function Documentation

◆ priv_jof_png_chunk_hdr()

ra8_err_t priv_jof_png_chunk_hdr	(	ra8_png_state_t *	st,
		uint32_t *	out_len,
		uint32_t *	out_type )

Read one 8-byte chunk header (length + type, both big-endian).

Assembles the fields and enforces the spec length cap.

Parameters

[in,out]	st	Decoder state (source position advances).
[out]	out_len	Receives the payload length.
[out]	out_type	Receives the chunk type value.

Returns: Result code.

Return values

k_ra8_ok	Header read; length within the spec cap.
k_ra8_err_protocol_error	Truncated header or oversize length.
other	Propagated from the pull callback.

Precondition: The source is positioned at a chunk boundary.; Both outputs are writable.

Postcondition: On success the source sits at the chunk payload.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Assembles the big-endian length and type fields and enforces the spec length cap.

Parameters

[in,out]	st	Decoder state (source position advances).
[out]	out_len	Receives the payload length.
[out]	out_type	Receives the chunk type value.

Returns: Result code.

Return values

k_ra8_ok	Header read; length within the spec cap.
k_ra8_err_protocol_error	Truncated header or oversize length.
other	Propagated from the pull callback.

Precondition: The source is positioned at a chunk boundary.; Both outputs are writable.

Postcondition: On success the source sits at the chunk payload.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 113 of file jof_png_chunk.c.

References k_ra8_err_protocol_error, k_ra8_ok, k_ra8_png_be_sh16, k_ra8_png_be_sh24, k_ra8_png_be_sh8, k_ra8_png_chunk_hdr, k_ra8_png_max_len, priv_jof_png_pull_exact(), and RA8_PRIV.

Referenced by internal_png_parse_ihdr(), internal_png_refill_input(), internal_png_walk_chunks(), and priv_jof_png_finish().

◆ priv_jof_png_finish()

ra8_err_t priv_jof_png_finish ( ra8_png_state_t * st )

Walk the post-IDAT chunks until IEND (ancillary chunks skipped).

When the zlib stream ended inside the last IDAT (no pending chunk parked by the refill path), that IDAT's trailing CRC is still unread: consume it, then resume the chunk walk.

Parameters

[in,out] st Decoder state (pending chunk consumed first).

Returns: Result code.

Return values

k_ra8_ok	IEND reached.
k_ra8_err_protocol_error	Chunk budget exhausted / truncation / a stray IDAT after the stream ended.
other	Propagated from the pull callback.

Precondition: The inflate phase finished (rows_done == h).; st->idat_rem == 0.

Postcondition: On success the datastream is fully consumed through IEND.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 426 of file jof_png_chunk.c.

References k_ra8_err_protocol_error, k_ra8_ok, k_ra8_png_crc_bytes, k_ra8_png_max_chunks, k_ra8_png_type_idat, k_ra8_png_type_iend, ra8_png_state_t::pending_len, ra8_png_state_t::pending_type, ra8_png_state_t::pending_valid, priv_jof_png_chunk_hdr(), priv_jof_png_skip(), and RA8_PRIV.

Referenced by internal_png_run_idat().

◆ priv_jof_png_pre_idat()

ra8_err_t priv_jof_png_pre_idat	(	ra8_png_state_t *	st,
		uint32_t	len,
		uint32_t	type )

Dispatch one pre-IDAT chunk (PLTE / tRNS / ancillary / stray IEND).

PLTE and tRNS bind the palette tables; unknown chunks skip.

Parameters

[in,out]	st	Decoder state.
[in]	len	Chunk payload length.
[in]	type	Chunk type value.

Returns: Result code.

Return values

k_ra8_ok	Chunk consumed; keep walking.
k_ra8_err_protocol_error	IEND arrived before any IDAT.
other	Propagated from the chunk parsers.

Precondition: The IHDR has been parsed.; len came from a validated chunk header.

Postcondition: On success the source sits at the next chunk boundary.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Parameters

[in,out]	st	Decoder state.
[in]	len	Chunk payload length.
[in]	type	Chunk type value.

Returns: Result code.

Return values

k_ra8_ok	Chunk consumed; keep walking.
k_ra8_err_protocol_error	IEND arrived before any IDAT.
other	Propagated from the chunk parsers.

Precondition: The IHDR has been parsed.; len came from a validated chunk header.

Postcondition: On success the source sits at the next chunk boundary.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 394 of file jof_png_chunk.c.

References internal_png_parse_plte(), internal_png_parse_trns(), k_ra8_err_protocol_error, k_ra8_png_crc_bytes, k_ra8_png_type_iend, k_ra8_png_type_plte, k_ra8_png_type_trns, priv_jof_png_skip(), and RA8_PRIV.

Referenced by internal_png_walk_chunks().

◆ priv_jof_png_prologue()

ra8_err_t priv_jof_png_prologue	(	ra8_png_state_t *	st,
		uint16_t	max_w,
		uint16_t	max_h )

Verify the 8-byte signature, then parse + validate the IHDR.

Fail-closed prologue for the untrusted stream.

Parameters

[in,out]	st	Decoder state (geometry fields written).
[in]	max_w	Fail-closed width cap.
[in]	max_h	Fail-closed height cap.

Returns: Result code.

Return values

k_ra8_ok	Prologue accepted; chunk walk may start.
k_ra8_err_protocol_error	Bad signature / IHDR structure.
other	Propagated from the IHDR validation.

Precondition: The source is positioned at byte 0 of the PNG stream.; st holds the bound callbacks.

Postcondition: On success the source sits at the first post-IHDR chunk.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Parameters

[in,out]	st	Decoder state (geometry fields written).
[in]	max_w	Fail-closed width cap.
[in]	max_h	Fail-closed height cap.

Returns: Result code.

Return values

k_ra8_ok	Prologue accepted; chunk walk may start.
k_ra8_err_protocol_error	Bad signature / IHDR structure.
other	Propagated from the IHDR validation.

Precondition: The source is positioned at byte 0 of the PNG stream.; st holds the bound callbacks.

Postcondition: On success the source sits at the first post-IHDR chunk.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 357 of file jof_png_chunk.c.

References internal_png_parse_ihdr(), k_ra8_err_protocol_error, k_ra8_ok, k_ra8_png_sig_bytes, k_ra8_png_sig_cr, k_ra8_png_sig_high, k_ra8_png_sig_lf, k_ra8_png_sig_sub, memcmp(), priv_jof_png_pull_exact(), and RA8_PRIV.

Referenced by internal_png_walk_chunks().

◆ priv_jof_png_pull_exact()

ra8_err_t priv_jof_png_pull_exact	(	ra8_png_state_t *	st,
		uint8_t *	buf,
		uint32_t	len )

Pull exactly len bytes; EOF mid-read is a protocol error.

Bounded by len (each non-EOF pull delivers >= 1 byte).

Parameters

[in,out]	st	Decoder state (source position advances).
[out]	buf	Destination buffer.
[in]	len	Bytes required.

Returns: Result code.

Return values

k_ra8_ok	Exactly `len` bytes delivered.
k_ra8_err_protocol_error	The source ended early.
other	Propagated from the pull callback.

Precondition: buf holds len writable bytes.; st->pull is bound.

Postcondition: On success the source advanced by len bytes.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Bounded by len (each non-EOF pull delivers >= 1 byte).

Parameters

[in,out]	st	Decoder state (source position advances).
[out]	buf	Destination buffer.
[in]	len	Bytes required.

Returns: Result code.

Return values

k_ra8_ok	Exactly `len` bytes delivered.
k_ra8_err_protocol_error	The source ended early.
other	Propagated from the pull callback.

Precondition: buf holds len writable bytes.; st->pull is bound.

Postcondition: On success the source advanced by len bytes.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 47 of file jof_png_chunk.c.

References k_ra8_err_protocol_error, k_ra8_ok, ra8_png_state_t::pull, ra8_png_state_t::pull_ctx, and RA8_PRIV.

Referenced by internal_png_parse_ihdr(), internal_png_parse_plte(), internal_png_parse_trns(), internal_png_refill_input(), priv_jof_png_chunk_hdr(), priv_jof_png_prologue(), and priv_jof_png_skip().

◆ priv_jof_png_skip()

ra8_err_t priv_jof_png_skip	(	ra8_png_state_t *	st,
		uint32_t	len )

Discard exactly len source bytes (unknown / ancillary chunks).

Bounded by len over a fixed-size stack scratch.

Parameters

[in,out]	st	Decoder state (source position advances).
[in]	len	Bytes to discard.

Returns: Result code.

Return values

k_ra8_ok	Bytes discarded.
k_ra8_err_protocol_error	The source ended early.
other	Propagated from the pull callback.

Precondition: st->pull is bound.; len came from a validated chunk-length field.

Postcondition: On success the source advanced by len bytes.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Bounded by len over a fixed-size stack scratch.

Parameters

[in,out]	st	Decoder state (source position advances).
[in]	len	Bytes to discard.

Returns: Result code.

Return values

k_ra8_ok	Bytes discarded.
k_ra8_err_protocol_error	The source ended early.
other	Propagated from the pull callback.

Precondition: st->pull is bound.; len came from a validated chunk-length field.

Postcondition: On success the source advanced by len bytes.; On error the decode aborts.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 80 of file jof_png_chunk.c.

References k_ra8_ok, k_ra8_png_skip_chunk, priv_jof_png_pull_exact(), and RA8_PRIV.

Referenced by internal_png_parse_ihdr(), internal_png_parse_plte(), internal_png_parse_trns(), internal_png_refill_input(), priv_jof_png_finish(), and priv_jof_png_pre_idat().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_png_const_t

◆ ra8_png_field_t

◆ ra8_png_signature_t

Function Documentation

◆ priv_jof_png_chunk_hdr()

◆ priv_jof_png_finish()

◆ priv_jof_png_pre_idat()

◆ priv_jof_png_prologue()

◆ priv_jof_png_pull_exact()

◆ priv_jof_png_skip()