Semantics

• Chunk data is stored in spng_ctx.

• All spng_get_*() functions return 0 on success and non-zero error, SPNG_ECHUNKAVAIL if the PNG does not contain that chunk or was not previously set.

• A successful spng_set_*() call will replace any previously set value or list, it does not combine chunk data from the file or multiple spng_set_*() calls.

The following apply to decoder contexts:

• When calling spng_get_*() or spng_set_*() functions all chunks up to the first IDAT are read, validated then stored with the exception of spng_get_ihdr(), which only reads the header.
• When calling spng_get_*() after the image has been decoded all chunks up to the IEND marker are read.
• spng_set_*() functions replace stored chunk data for that type.
• Chunk data stored with spng_set_*() functions are never replaced with input file chunk data i.e. if you set something it will stay that way.

API

spng_get_ihdr()

int spng_get_ihdr(spng_ctx *ctx, struct spng_ihdr *ihdr)

Get image header

spng_get_plte()

int spng_get_plte(spng_ctx *ctx, struct spng_plte *plte)

Get image palette

spng_get_trns()

int spng_get_trns(spng_ctx *ctx, struct spng_trns *trns)

Get image transparency

spng_get_chrm()

int spng_get_chrm(spng_ctx *ctx, struct spng_chrm *chrm)

Get primary chromacities and white point as floating point numbers

spng_get_chrm_int()

int spng_get_chrm_int(spng_ctx *ctx, struct spng_chrm_int *chrm_int)

Get primary chromacities and white point in PNG’s internal representation

spng_get_gama()

int spng_get_gama(spng_ctx *ctx, double *gamma)

Get image gamma

spng_get_gama_int()

int spng_get_gama_int(spng_ctx *ctx, uint32_t *gamma)

Get image gamma in PNG’s internal representation

spng_get_iccp()

int spng_get_iccp(spng_ctx *ctx, struct spng_iccp *iccp)

Get ICC profile

Note

ICC profiles are not validated.

spng_get_sbit()

int spng_get_sbit(spng_ctx *ctx, struct spng_sbit *sbit)

Get significant bits

spng_get_srgb()

int spng_get_srgb(spng_ctx *ctx, uint8_t *rendering_intent)

Get rendering intent

spng_get_text()

int spng_get_text(spng_ctx *ctx, struct spng_text *text, uint32_t *n_text)

Copies text information to text.

n_text should be greater than or equal to the number of stored text chunks.

If text is NULL and n_text is non-NULL then n_text is set to the number of stored text chunks.

Strings may be zero-length (single '\0' character) with the exception of text.keyword, all strings are guaranteed to be non-NULL.

Note

Due to the structure of PNG files it is recommended to call this function after spng_decode_image() to retrieve all text chunks.

Warning

Text data is freed when calling spng_ctx_free().

spng_get_bkgd()

int spng_get_bkgd(spng_ctx *ctx, struct spng_bkgd *bkgd)

Get image background color

spng_get_hist()

int spng_get_hist(spng_ctx *ctx, struct spng_hist *hist)

Get image histogram

spng_get_phys()

int spng_get_phys(spng_ctx *ctx, struct spng_phys *phys)

Get physical pixel dimensions

spng_get_splt()

int spng_get_splt(spng_ctx *ctx, struct spng_splt *splt, uint32_t *n_splt)

Copies suggested palettes to splt.

n_splt should be greater than or equal to the number of stored sPLT chunks.

If splt is NULL and n_splt is non-NULL then n_splt is set to the number of stored sPLT chunks.

Warning

Suggested palettes are freed when calling spng_ctx_free().

spng_get_time()

int spng_get_time(spng_ctx *ctx, struct spng_time *time)

Get modification time

Note

Due to the structure of PNG files it is recommended to call this function after spng_decode_image().

spng_get_unknown_chunks()

int spng_get_unknown_chunks(spng_ctx *ctx, struct spng_unknown_chunk *chunks, uint32_t *n_chunks)

Copies unknown chunk information to chunks.

n_chunks should be greater than or equal to the number of stored unknown chunks.

If chunks is NULL and n_chunks is non-NULL then n_chunks is set to the number of stored chunks.

Note

To retrieve all unknown chunks call this functions after spng_decode_image().

Warning

Chunk data is freed when calling spng_ctx_free().

spng_get_offs()

int spng_get_offs(spng_ctx *ctx, struct spng_offs *offs)

Get image offset

spng_get_exif()

int spng_get_exif(spng_ctx *ctx, struct spng_exif *exif)

Get EXIF data

Note

Due to the structure of PNG files it is recommended to call this function after spng_decode_image().

Warning

exif.data is freed when calling spng_ctx_free().

spng_set_ihdr()

int spng_set_ihdr(spng_ctx *ctx, struct spng_ihdr *ihdr)

Set image header

spng_set_plte()

int spng_set_plte(spng_ctx *ctx, struct spng_plte *plte)

Set image palette

spng_set_trns()

int spng_set_trns(spng_ctx *ctx, struct spng_trns *trns)

Set transparency

spng_set_chrm()

int spng_set_chrm(spng_ctx *ctx, struct spng_chrm *chrm)

Set primary chromacities and white point as floating point numbers

spng_set_chrm_int()

int spng_set_chrm_int(spng_ctx *ctx, struct spng_chrm_int *chrm_int)

Set primary chromacities and white point in PNG’s internal representation

spng_set_gama()

int spng_set_gama(spng_ctx *ctx, double gamma)

Set image gamma

spng_set_gama_int()

int spng_set_gama_int(spng_ctx *ctx, uint32_t gamma)

Set image gamma in PNG’s internal representation

spng_set_iccp()

int spng_set_iccp(spng_ctx *ctx, struct spng_iccp *iccp)

Set ICC profile

spng_iccp.profile_name must only contain printable Latin-1 characters and spaces. Leading, trailing, and consecutive spaces are not permitted.

Note

ICC profiles are not validated.

spng_set_sbit()

int spng_set_sbit(spng_ctx *ctx, struct spng_sbit *sbit)

Set significant bits

spng_set_srgb()

int spng_set_srgb(spng_ctx *ctx, uint8_t rendering_intent)

Set rendering intent

spng_set_text()

int spng_set_text(spng_ctx *ctx, struct spng_text *text, uint32_t n_text)

Set text data

text should point to an spng_text array of n_text elements.

spng_text.text must only contain Latin-1 characters. Newlines must be a single linefeed character (decimal 10).

spng_text.translated_keyword must not contain linebreaks.

spng_text.compression_method must be zero.

spng_set_bkgd()

int spng_set_bkgd(spng_ctx *ctx, struct spng_bkgd *bkgd)

Set image background color

spng_set_hist()

int spng_set_hist(spng_ctx *ctx, struct spng_hist *hist)

Set image histogram

spng_set_phys()

int spng_set_phys(spng_ctx *ctx, struct spng_phys *phys)

Set physical pixel dimensions

spng_set_splt()

int spng_set_splt(spng_ctx *ctx, struct spng_splt *splt, uint32_t n_splt)

Set suggested palette(s).

splt should point to an spng_splt array of n_splt elements.

Note

splt should be a valid reference for the lifetime of the context.

spng_set_time()

int spng_set_time(spng_ctx *ctx, struct spng_time *time)

Set modification time

spng_set_unknown_chunks()

int spng_set_unknown_chunks(spng_ctx *ctx, struct spng_unknown_chunk *chunks, uint32_t n_chunks)

Set unknown chunk data.

Note

chunks should be a valid reference for the lifetime of the context.

spng_set_offs()

int spng_set_offs(spng_ctx *ctx, struct spng_offs *offs)

Set image offset

spng_set_exif()

int spng_set_exif(spng_ctx *ctx, struct spng_exif *exif)

Set EXIF data