Skip to main content
The PNG decoder library provides hardware-accelerated PNG image decoding capabilities on the PlayStation 3. It supports various color spaces, interlaced images, and decoding modes with SPU acceleration.

​
Overview

The pngdec library allows you to decode PNG images from files or memory buffers. It supports PNG features including transparency, interlacing, multiple color spaces, and various bit depths.
Before using pngdec functions, you must load the SYSMODULE_PNGDEC system module using sysModuleLoad().

​
Error Codes

CodeValueDescription
PNGDEC_ERROR_OK0x00Operation successful
PNGDEC_ERROR_HEADER0x80611201Invalid PNG header
PNGDEC_ERROR_STREAM_FORMAT0x80611202Invalid stream format
PNGDEC_ERROR_ARG0x80611203Invalid argument
PNGDEC_ERROR_SEQ0x80611204Invalid sequence
PNGDEC_ERROR_BUSY0x80611205Decoder is busy
PNGDEC_ERROR_FATAL0x80611206Fatal error
PNGDEC_ERROR_OPEN_FILE0x80611207Failed to open file
PNGDEC_ERROR_SPU_UNSUPPORT0x80611208SPU acceleration unsupported
PNGDEC_ERROR_SPU_ERROR0x80611209SPU error
PNGDEC_ERROR_CB_PARAM0x8061120aInvalid callback parameter

​
Color Spaces

​
pngColorSpace
enum
Supported color space formats for PNG decoding.
  • PNGDEC_GRAYSCALE (1) - Grayscale output
  • PNGDEC_RGB (2) - RGB color output
  • PNGDEC_PALETTE (4) - Palette-indexed color
  • PNGDEC_GRAYSCALE_ALPHA (9) - Grayscale with alpha channel
  • PNGDEC_RGBA (10) - RGBA color output
  • PNGDEC_ARGB (20) - ARGB color output

​
Stream Selection

​
pngStreamSel
enum
Input source selection for PNG data.
  • PNGDEC_FILE (0) - Decode from file
  • PNGDEC_BUFFER (1) - Decode from memory buffer

​
Interlace Modes

​
pngInterlaceMode
enum
PNG interlacing methods.
  • PNGDEC_NO_INTERLACE (0) - Standard sequential image
  • PNGDEC_ADAM7_INTERLACE (1) - Adam7 interlaced image

​
Core Functions

​
pngDecCreate

s32 pngDecCreate(s32 *handle, pngDecThreadInParam *in, pngDecThreadOutParam *out);
Creates a PNG decoder instance.
​
handle
s32*
Pointer to receive the decoder handle.
​
in
pngDecThreadInParam*
Input parameters for decoder creation.
​
spu_enable
u32
Enable SPU acceleration (PNGDEC_SPU_THREAD_ENABLE or PNGDEC_SPU_THREAD_DISABLE).
​
ppu_prio
u32
PPU thread priority.
​
spu_prio
u32
SPU thread priority (if SPU enabled).
​
malloc_func
pngCbCtrlMalloc
Custom memory allocation function (optional, can be NULL).
​
malloc_arg
void*
Argument passed to malloc function.
​
free_func
pngCbCtrlFree
Custom memory free function (optional, can be NULL).
​
free_arg
void*
Argument passed to free function.
​
out
pngDecThreadOutParam*
Output parameters from decoder creation.
​
version
u32
Decoder library version.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecOpen

s32 pngDecOpen(s32 handle, s32 *subhandle, const pngDecSource *src, pngDecOpnInfo *open_info);
Opens a PNG stream for decoding.
​
handle
s32
Decoder handle from pngDecCreate.
​
subhandle
s32*
Pointer to receive the stream subhandle.
​
src
const pngDecSource*
Source configuration for the PNG data.
​
stream_sel
u32
Input stream selection (PNGDEC_FILE or PNGDEC_BUFFER).
​
file_name
const char*
File path (if stream_sel is PNGDEC_FILE).
​
file_offset
s64
Offset in file to start reading.
​
file_size
u32
Size of PNG data in file.
​
stream_ptr
void*
Pointer to PNG data in memory (if stream_sel is PNGDEC_BUFFER).
​
stream_size
u32
Size of PNG data in memory.
​
spu_enable
u32
Enable SPU acceleration for this stream.
​
open_info
pngDecOpnInfo*
Information about the opened stream.
​
init_space_allocated
u32
Amount of memory allocated for initialization.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecReadHeader

s32 pngDecReadHeader(s32 handle, s32 subhandle, pngDecInfo *info);
Reads the PNG header and retrieves image information.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle from pngDecOpen.
​
info
pngDecInfo*
Pointer to receive image information.
​
width
u32
Image width in pixels.
​
height
u32
Image height in pixels.
​
num_comp
u32
Number of color components.
​
color_space
u32
Original color space of the PNG image.
​
bit_depth
u32
Bit depth per channel (1, 2, 4, 8, or 16).
​
interlace_mode
u32
Interlace method used (PNGDEC_NO_INTERLACE or PNGDEC_ADAM7_INTERLACE).
​
chunk_info
u32
Information about chunks present in the PNG.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecSetParameter

s32 pngDecSetParameter(s32 handle, s32 subhandle, const pngDecInParam *in, pngDecOutParam *out);
Sets decoding parameters and prepares the decoder.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle.
​
in
const pngDecInParam*
Input decoding parameters.
​
cmd_ptr
vu32*
Pointer to command variable for decoder control (can be NULL).
​
output_mode
u32
Output scanline order (PNGDEC_TOP_TO_BOTTOM or PNGDEC_BOTTOM_TO_TOP).
​
color_space
u32
Desired output color space.
​
bit_depth
u32
Desired output bit depth.
​
pack_flag
u32
Pixel packing flag (PNGDEC_1BYTE_PER_NPIXEL or PNGDEC_1BYTE_PER_1PIXEL).
​
alpha_select
u32
Alpha channel handling (PNGDEC_STREAM_ALPHA or PNGDEC_FIX_ALPHA).
​
alpha
u32
Fixed alpha value if alpha_select is PNGDEC_FIX_ALPHA.
​
out
pngDecOutParam*
Output parameters after configuration.
​
width_byte
u64
Width of output in bytes (including padding).
​
width
u32
Output image width in pixels.
​
height
u32
Output image height in pixels.
​
num_comp
u32
Number of output color components.
​
bit_depth
u32
Actual output bit depth.
​
output_mode
u32
Actual output mode being used.
​
color_space
u32
Actual output color space.
​
use_memory_space
u32
Memory required for decoding.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecDecodeData

s32 pngDecDecodeData(s32 handle, s32 subhandle, u8 *data, 
                     const pngDecDataCtrlParam *dataCtrlParam, pngDecDataInfo *info);
Decodes the PNG image data.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle.
​
data
u8*
Pointer to output buffer for decoded image data.
​
dataCtrlParam
const pngDecDataCtrlParam*
Data control parameters.
​
output_bytes_per_line
u64
Bytes per line in output buffer (for custom stride).
​
info
pngDecDataInfo*
Information about the decoded data.
​
chunk_info
u32
Chunk information.
​
num_text
u32
Number of text chunks.
​
num_unk_chunk
u32
Number of unknown chunks.
​
decode_status
u32
Decode status (PNGDEC_STATUS_FINISH or PNGDEC_STATUS_STOP).
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecClose

s32 pngDecClose(s32 handle, s32 subhandle);
Closes a PNG stream.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle to close.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngDecDestroy

s32 pngDecDestroy(s32 handle);
Destroys a PNG decoder instance.
​
handle
s32
Decoder handle to destroy.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
Helper Functions

​
pngLoadFromFile

s32 pngLoadFromFile(const char *filename, pngData *out);
Simple helper function to load a PNG image from a file.
​
filename
const char*
Path to the PNG file.
​
out
pngData*
Pointer to receive the decoded image data.
​
bmp_out
void*
Pointer to decoded image buffer (must be freed by caller).
​
pitch
u32
Bytes per scanline.
​
width
u32
Image width in pixels.
​
height
u32
Image height in pixels.
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
pngLoadFromBuffer

s32 pngLoadFromBuffer(const void *buffer, u32 size, pngData *out);
Simple helper function to load a PNG image from a memory buffer.
​
buffer
const void*
Pointer to PNG data in memory.
​
size
u32
Size of PNG data in bytes.
​
out
pngData*
Pointer to receive the decoded image data (same structure as pngLoadFromFile).
Returns: PNGDEC_ERROR_OK on success, error code otherwise.

​
Usage Example

#include <sysmodule/sysmodule.h>
#include <pngdec/pngdec.h>
#include <stdio.h>
#include <stdlib.h>

int main() {
    s32 ret;
    s32 handle;
    s32 subhandle;
    pngDecThreadInParam in_param;
    pngDecThreadOutParam out_param;
    pngDecSource src;
    pngDecOpnInfo open_info;
    pngDecInfo info;
    pngDecInParam dec_in;
    pngDecOutParam dec_out;
    pngDecDataCtrlParam data_ctrl;
    pngDecDataInfo data_info;
    u8 *output_buffer;

    // Load PNG decoder module
    ret = sysModuleLoad(SYSMODULE_PNGDEC);
    if (ret != 0) {
        printf("Failed to load PNGDEC module: 0x%x\n", ret);
        return -1;
    }

    // Create decoder
    in_param.spu_enable = PNGDEC_SPU_THREAD_DISABLE;
    in_param.ppu_prio = 1000;
    in_param.spu_prio = 200;
    in_param.malloc_func = NULL;
    in_param.malloc_arg = NULL;
    in_param.free_func = NULL;
    in_param.free_arg = NULL;

    ret = pngDecCreate(&handle, &in_param, &out_param);
    if (ret != PNGDEC_ERROR_OK) {
        printf("pngDecCreate failed: 0x%x\n", ret);
        return -1;
    }

    // Open PNG file
    src.stream_sel = PNGDEC_FILE;
    src.file_name = "/dev_hdd0/image.png";
    src.file_offset = 0;
    src.file_size = 0;  // 0 = read entire file
    src.spu_enable = PNGDEC_SPU_THREAD_DISABLE;

    ret = pngDecOpen(handle, &subhandle, &src, &open_info);
    if (ret != PNGDEC_ERROR_OK) {
        printf("pngDecOpen failed: 0x%x\n", ret);
        pngDecDestroy(handle);
        return -1;
    }

    // Read header
    ret = pngDecReadHeader(handle, subhandle, &info);
    if (ret != PNGDEC_ERROR_OK) {
        printf("pngDecReadHeader failed: 0x%x\n", ret);
        pngDecClose(handle, subhandle);
        pngDecDestroy(handle);
        return -1;
    }

    printf("Image: %dx%d, %d-bit, %d components\n", 
           info.width, info.height, info.bit_depth, info.num_comp);
    printf("Interlaced: %s\n", 
           info.interlace_mode ? "Yes (Adam7)" : "No");

    // Set decode parameters
    dec_in.cmd_ptr = NULL;
    dec_in.output_mode = PNGDEC_TOP_TO_BOTTOM;
    dec_in.color_space = PNGDEC_ARGB;
    dec_in.bit_depth = 8;
    dec_in.pack_flag = PNGDEC_1BYTE_PER_1PIXEL;
    dec_in.alpha_select = PNGDEC_STREAM_ALPHA;  // Use PNG's alpha
    dec_in.alpha = 0xFF;

    ret = pngDecSetParameter(handle, subhandle, &dec_in, &dec_out);
    if (ret != PNGDEC_ERROR_OK) {
        printf("pngDecSetParameter failed: 0x%x\n", ret);
        pngDecClose(handle, subhandle);
        pngDecDestroy(handle);
        return -1;
    }

    // Allocate output buffer
    output_buffer = (u8*)malloc(dec_out.width_byte * dec_out.height);
    if (!output_buffer) {
        printf("Failed to allocate output buffer\n");
        pngDecClose(handle, subhandle);
        pngDecDestroy(handle);
        return -1;
    }

    // Decode image
    data_ctrl.output_bytes_per_line = dec_out.width_byte;
    ret = pngDecDecodeData(handle, subhandle, output_buffer, 
                          &data_ctrl, &data_info);
    if (ret != PNGDEC_ERROR_OK) {
        printf("pngDecDecodeData failed: 0x%x\n", ret);
        free(output_buffer);
        pngDecClose(handle, subhandle);
        pngDecDestroy(handle);
        return -1;
    }

    printf("Decode complete\n");

    // Use the decoded image data...
    // output_buffer now contains ARGB pixel data

    // Cleanup
    free(output_buffer);
    pngDecClose(handle, subhandle);
    pngDecDestroy(handle);
    sysModuleUnload(SYSMODULE_PNGDEC);

    return 0;
}

​
Simple Usage Example

For basic use cases, the helper functions provide a simpler interface: 
#include <sysmodule/sysmodule.h>
#include <pngdec/pngdec.h>
#include <stdio.h>

int main() {
    pngData png;
    s32 ret;

    // Load PNG decoder module
    sysModuleLoad(SYSMODULE_PNGDEC);

    // Load and decode PNG in one call
    ret = pngLoadFromFile("/dev_hdd0/image.png", &png);
    if (ret == PNGDEC_ERROR_OK) {
        printf("Image loaded: %dx%d\n", png.width, png.height);
        printf("Pitch: %d bytes\n", png.pitch);
        
        // Use png.bmp_out (ARGB format)
        // ...
        
        // Free the image data
        free(png.bmp_out);
    }

    sysModuleUnload(SYSMODULE_PNGDEC);
    return 0;
}
Always free the memory returned in pngData.bmp_out when using the helper functions to avoid memory leaks.

​
Extended API

The pngdec library also provides extended functions for advanced use cases:
  • pngDecExtOpen() - Opens a stream with callback support for streaming data
  • pngDecExtReadHeader() - Reads header with extended information
  • pngDecExtSetParameter() - Sets parameters with extended options (line mode, progressive)
  • pngDecExtDecodeData() - Decodes with display callback support for progressive rendering
These functions allow for more control over the decoding process, including progressive decoding for interlaced images and custom data streaming.

​
Transparency Handling

PNG images can contain transparency information in several ways:
For RGBA and Grayscale+Alpha images, the alpha channel is decoded directly when using PNGDEC_RGBA or PNGDEC_ARGB output modes with PNGDEC_STREAM_ALPHA.
For images with a tRNS chunk (transparent color), the decoder automatically converts the transparent color to alpha values in the output.
You can use PNGDEC_FIX_ALPHA to ignore the PNG’s transparency and use a fixed alpha value for all pixels.

Build docs developers (and LLMs) love

Get started for freeTalk to us