Retrieving and setting chunks

Semantics

  • Chunk data is stored in spng_ctx.
  • When calling spng_get_*() or spng_set_*() functions all ancillary chunks up to the first IDAT are read, validated then stored.
  • 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.

Data types

struct spng_ihdr

Image header information

enum spng_color_type
{
    SPNG_COLOR_GRAYSCALE = 0,
    SPNG_COLOR_TRUECOLOR = 2,
    SPNG_COLOR_INDEXED = 3,
    SPNG_COLOR_GRAYSCALE_ALPHA = 4,
    SPNG_COLOR_TRUECOLOR_ALPHA = 6
};

struct spng_ihdr
{
    uint32_t width;
    uint32_t height;
    uint8_t bit_depth;
    uint8_t color_type;
    uint8_t compression_method;
    uint8_t filter_method;
    uint8_t interlace_method;
};
struct spng_plte

Image palette

struct spng_plte_entry
{
    uint8_t red;
    uint8_t green;
    uint8_t blue;

    uint8_t alpha; /* reserved for internal use */
};

struct spng_plte
{
    uint32_t n_entries;
    struct spng_plte_entry entries[256];
};
struct spng_trns

Transparency

struct spng_trns
{
    uint16_t gray;

    uint16_t red;
    uint16_t green;
    uint16_t blue;

    uint32_t n_type3_entries;
    uint8_t type3_alpha[256];
};
struct spng_chrm

Image chromacities and white point

struct spng_chrm
{
    double white_point_x;
    double white_point_y;
    double red_x;
    double red_y;
    double green_x;
    double green_y;
    double blue_x;
    double blue_y;
};
struct spng_chrm_int

Image chromacities and white point in PNG’s internal representation

struct spng_chrm_int
{
    uint32_t white_point_x;
    uint32_t white_point_y;
    uint32_t red_x;
    uint32_t red_y;
    uint32_t green_x;
    uint32_t green_y;
    uint32_t blue_x;
    uint32_t blue_y;
};
struct spng_iccp

Image ICC color profile

struct spng_iccp
{
    char profile_name[80];
    size_t profile_len;
    char *profile;
};
struct spng_sbit

Significant sample bits

struct spng_sbit
{
    uint8_t grayscale_bits;
    uint8_t red_bits;
    uint8_t green_bits;
    uint8_t blue_bits;
    uint8_t alpha_bits;
};
struct spng_text

Text information

enum spng_text_type
{
    SPNG_TEXT = 1,
    SPNG_ZTXT = 2,
    SPNG_ITXT = 3
};

struct spng_text
{
    char keyword[80];
    int type;

    size_t length;
    char *text;

    uint8_t compression_flag; /* iTXt only */
    uint8_t compression_method; /* iTXt, ztXt only */
    char *language_tag; /* iTXt only */
    char *translated_keyword; /* iTXt only */
};
struct spng_bkgd

Image background color

struct spng_bkgd
{
    uint16_t gray; /* only for gray/gray alpha */

    uint16_t red;
    uint16_t green;
    uint16_t blue;

    uint16_t plte_index; /* only for indexed color */
};
struct spng_hist

Image histogram

struct spng_hist
{
    uint16_t frequency[256];
};
struct spng_phys

Physical pixel dimensions

struct spng_phys
{
    uint32_t ppu_x, ppu_y;
    uint8_t unit_specifier;
};
struct spng_splt

Suggested palettes

struct spng_splt_entry
{
    uint16_t red;
    uint16_t green;
    uint16_t blue;
    uint16_t alpha;
    uint16_t frequency;
};

struct spng_splt
{
    char name[80];
    uint8_t sample_depth;
    uint32_t n_entries;
    struct spng_splt_entry *entries;
};
struct spng_time

Image modification time

struct spng_time
{
    uint16_t year;
    uint8_t month;
    uint8_t day;
    uint8_t hour;
    uint8_t minute;
    uint8_t second;
};
struct spng_offs

Image offset

struct spng_offs
{
   int32_t x, y;
   uint8_t unit_specifier;
};
struct spng_exif

EXIF information

struct spng_exif
{
   size_t length;
   char *data;
};

API

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

Get image header

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

Get image palette

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

Get image transparency

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

Get primary chromacities and white point as floating point numbers

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

int spng_get_gama(spng_ctx *ctx, double *gamma)

Get image gamma

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

Get ICC profile

Note

ICC profiles are not validated.

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

Get significant bits

int spng_get_srgb(spng_ctx *ctx, uint8_t *rendering_intent)

Get rendering intent

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.

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().

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

Get image background color

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

Get image histogram

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

Get phyiscal pixel dimensions

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().

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().

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

Get image offset

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().

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

Set image header

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

Set image palette

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

Set transparency

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

Set primary chromacities and white point as floating point numbers

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

int spng_set_gama(spng_ctx *ctx, double gamma)

Set image gamma

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.

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

Set significant bits

int spng_set_srgb(spng_ctx *ctx, uint8_t rendering_intent)

Set rendering intent

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.

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

Set image background color

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

Set image histogram

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

Set phyiscal pixel dimensions

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.

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

Set modification time

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

Set image offset

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

Set EXIF data