Contexts

The context handle spng_ctx is an opaque datatype that holds all information, there is no separate info struct.

Create a new context with spng_ctx_new() or spng_ctx_new2() to set a custom memory allocator.

Contexts are decoders by default, to create an encoder use SPNG_CTX_ENCODER as context flag.

spng_ctx_free() frees all context data.

Error handling

All functions return zero on success and non-zero on error, decoding or encoding errors will invalidate the context and most subequent function calls will return SPNG_EBADSTATE to signal this.

See also: Decoder error handling

Limits

!!! note cache_max refers to an overall memory usage limit in spng.

Image information and chunk data

!!! info Image dimensions and other basic properties can be retrieved with spng_get_ihdr().

!!! note Most chunk data is copied except for arbitrary length chunks (eXIf, text, sPLT, unknown chunks).

Chunk lists are not copied, the reference must stay valid for the lifetime of the context.

To retrieve chunk lists for text, sPLT and unknown chunks the user must allocate buffers for them after querying the list size,
unlike with libpng the internal list pointers are not accessible.

Decode

Set source PNG

!!! note Push-style decoding is not supported in this release.

Decoder configuration

CRC action constants

!!! note Errors are only signalled through return values, spng never calls abort().

Image formats and transforms

Currently the library only works with source and destination formats, there are no transforms which change the output format based on the source PNG's format or other metadata like the tRNS chunk.

Migrating from the traditional libpng API is straightforward if the desired output format is clearly defined, nonetheless some transforms (such as Adding transparency) can be implemented on top of the existing API.

All spng_format's are explicit and host-endian (except for SPNG_FMT_PNG and SPNG_FMT_RAW), PNG formats are converted to the destination spng_format when decoding or converted from the spng_format to the destination PNG format when encoding. When the destination format has an alpha channel and the source doesn't the alpha samples are implicitly set to the fully opaque, maximum value. The alpha channel is always straight alpha, premultiplied alpha is not supported.

!!! note Some source/destination combinations are not supported, check supported format, flags combinations for decoding and encoding.

SPNG_FMT_PNG represents the PNG's format specified in the header (IHDR chunk) in host-endian (ie. little-endian on x86), it is the equivalent of only calling png_set_swap() on little-endian when decoding or encoding. When decoding the output will always be host-endian, when encoding it is assumed the source image is host-endian.

SPNG_FMT_RAW is the same as SPNG_FMT_PNG but in big-endian, it is the same as not doing any transformations when decoding or encoding with libpng. The PNG standard only supports encoding of 16-bit images in big-endian, when used as the source format the library will assume the source image is big-endian. When decoding 16-bit images the output will always be big-endian.

Some decode flags may affect the final image but never the size or the layout of the samples within the pixels.

Adding transparency

This can be achieved by specifiying an output format with an alpha channel such as SPNG_FMT_RGBA8 and the SPNG_DECODE_TRNS decode flag.

ret = spng_decode_image(ctx, out, len, SPNG_FMT_RGBA8, SPNG_DECODE_TRNS);

Note that using SPNG_DECODE_TRNS does not result in an error if the image does not have a tRNS chunk or is not applicable for the PNG format/output format combination, in those cases the flag is ignored.

The png_set_tRNS_to_alpha() function applies a tranforms which adds an alpha channel of the same bit depth if a tRNS chunk is present. It also implicitly converts indexed color images to 8-bit RGB, 1/2/4-bit grayscale images to 8-bit grayscale and also adds an alpha channel if there is a tRNS chunk.

This transform can be implemented by choosing the equivalent output format and using SPNG_DECODE_TRNS to apply transparency:

int fmt = SPNG_FMT_PNG;
int decode_flags = SPNG_DECODE_TRNS;

if(ihdr.color_type == SPNG_COLOR_TYPE_INDEXED) fmt = SPNG_FMT_RGB8;
else if(ihdr.color_type == SPNG_COLOR_TYPE_GRAYSCALE && ihdr.bit_depth < 8) fmt = SPNG_FMT_G8;

struct spng_trns trns = {0};
int have_trns = !spng_get_trns(ctx, &trns);

if(have_trns)
{
    if(ihdr.color_type == SPNG_COLOR_TYPE_TRUECOLOR)
    {
        if(ihdr.bit_depth == 16) fmt = SPNG_FMT_RGBA16;
        else fmt = SPNG_FMT_RGBA8;
    }
    else if(ihdr.color_type == SPNG_COLOR_TYPE_GRAYSCALE)
    {
        if(ihdr.bit_depth == 16) fmt = SPNG_FMT_GA16;
        else fmt = SPNG_FMT_GA8;
    }
    else if(ihdr.color_type == SPNG_COLOR_TYPE_INDEXED)
    {
        fmt = SPNG_FMT_RGBA8;
    }
}

Decoding images

See also: Progressive image decoding

!!! note Row pointers (array of pointers) are not used.

Encode

Set destination PNG

Encoder configuration

Encoding images

See also: Progressive image encoding

!!! note Row pointers (array of pointers) are not used.

Common

Chunk location constants

Color type constants

Filter constants

Filter values

Filter values defined by the standard.

Filter choices

Filter choice flags for spng_set_option() when used with SPNG_FILTER_CHOICE.

Miscellaneous functions