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

​
Overview

The jpgdec library allows you to decode JPEG images from files or memory buffers. It supports standard JPEG features including multiple color spaces, downscaling, and both basic and extended decoding modes.
Before using jpgdec functions, you must load the SYSMODULE_JPGDEC system module using sysModuleLoad().

​
Error Codes

CodeValueDescription
JPGDEC_ERROR_OK0x00Operation successful
JPGDEC_ERROR_HEADER0x80611101Invalid JPEG header
JPGDEC_ERROR_STREAM_FORMAT0x80611102Invalid stream format
JPGDEC_ERROR_ARG0x80611103Invalid argument
JPGDEC_ERROR_SEQ0x80611104Invalid sequence
JPGDEC_ERROR_BUSY0x80611105Decoder is busy
JPGDEC_ERROR_FATAL0x80611106Fatal error
JPGDEC_ERROR_OPEN_FILE0x80611107Failed to open file
JPGDEC_ERROR_SPU_UNSUPPORT0x80611108SPU acceleration unsupported
JPGDEC_ERROR_CB_PARAM0x80611109Invalid callback parameter

​
Color Spaces

​
jpgColorSpace
enum
Supported color space formats for JPEG decoding.
  • JPGDEC_GRAYSCALE (1) - Grayscale output
  • JPGDEC_RGB (2) - RGB color output
  • JPGDEC_YCBCR (3) - YCbCr color output
  • JPGDEC_RGBA (10) - RGBA color output
  • JPGDEC_UPSTREAM (11) - Upstream format
  • JPGDEC_ARGB (20) - ARGB color output

​
Stream Selection

​
jpgStreamSel
enum
Input source selection for JPEG data.
  • JPGDEC_FILE (0) - Decode from file
  • JPGDEC_BUFFER (1) - Decode from memory buffer

​
Core Functions

​
jpgDecCreate

s32 jpgDecCreate(s32 *handle, jpgDecThreadInParam *in, jpgDecThreadOutParam *out);
Creates a JPEG decoder instance.
​
handle
s32*
Pointer to receive the decoder handle.
​
in
jpgDecThreadInParam*
Input parameters for decoder creation.
​
spu_enable
u32
Enable SPU acceleration (JPGDEC_SPU_THREAD_ENABLE or JPGDEC_SPU_THREAD_DISABLE).
​
ppu_prio
u32
PPU thread priority.
​
spu_prio
u32
SPU thread priority (if SPU enabled).
​
malloc_func
jpgCbCtrlMalloc
Custom memory allocation function (optional, can be NULL).
​
malloc_arg
void*
Argument passed to malloc function.
​
free_func
jpgCbCtrlFree
Custom memory free function (optional, can be NULL).
​
free_arg
void*
Argument passed to free function.
​
out
jpgDecThreadOutParam*
Output parameters from decoder creation.
​
version
u32
Decoder library version.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecOpen

s32 jpgDecOpen(s32 handle, s32 *subhandle, const jpgDecSource *src, jpgDecOpnInfo *openInfo);
Opens a JPEG stream for decoding.
​
handle
s32
Decoder handle from jpgDecCreate.
​
subhandle
s32*
Pointer to receive the stream subhandle.
​
src
const jpgDecSource*
Source configuration for the JPEG data.
​
stream_sel
u32
Input stream selection (JPGDEC_FILE or JPGDEC_BUFFER).
​
file_name
const char*
File path (if stream_sel is JPGDEC_FILE).
​
file_offset
s64
Offset in file to start reading.
​
file_size
u32
Size of JPEG data in file.
​
stream_ptr
void*
Pointer to JPEG data in memory (if stream_sel is JPGDEC_BUFFER).
​
stream_size
u32
Size of JPEG data in memory.
​
spu_enable
u32
Enable SPU acceleration for this stream.
​
openInfo
jpgDecOpnInfo*
Information about the opened stream.
​
init_space_allocated
u32
Amount of memory allocated for initialization.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecReadHeader

s32 jpgDecReadHeader(s32 handle, s32 subhandle, jpgDecInfo *info);
Reads the JPEG header and retrieves image information.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle from jpgDecOpen.
​
info
jpgDecInfo*
Pointer to receive image information.
​
width
u32
Image width in pixels.
​
height
u32
Image height in pixels.
​
num_comp
u32
Number of color components (1 for grayscale, 3 for RGB/YCbCr).
​
color_space
u32
Original color space of the JPEG image.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecSetParameter

s32 jpgDecSetParameter(s32 handle, s32 subhandle, const jpgDecInParam *in, jpgDecOutParam *out);
Sets decoding parameters and prepares the decoder.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle.
​
in
const jpgDecInParam*
Input decoding parameters.
​
cmd_ptr
vu32*
Pointer to command variable for decoder control (can be NULL).
​
down_scale
u32
Downscaling factor (1, 2, 4, or 8).
​
quality_mode
u32
Quality mode (JPGDEC_QUALITY or JPGDEC_FAST).
​
output_mode
u32
Output scanline order (JPGDEC_TOP_TO_BOTTOM or JPGDEC_BOTTOM_TO_TOP).
​
color_space
u32
Desired output color space.
​
alpha
u8
Alpha value for RGBA/ARGB output (0-255).
​
out
jpgDecOutParam*
Output parameters after configuration.
​
width_bytes
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.
​
output_mode
u32
Actual output mode being used.
​
color_space
u32
Actual output color space.
​
down_scale
u32
Actual downscale factor being used.
​
use_memory_space
u32
Memory required for decoding.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecDecodeData

s32 jpgDecDecodeData(s32 handle, s32 subhandle, u8 *data, 
                     const jpgDecDataCtrlParam *dataCtrlParam, jpgDecDataInfo *info);
Decodes the JPEG image data.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle.
​
data
u8*
Pointer to output buffer for decoded image data.
​
dataCtrlParam
const jpgDecDataCtrlParam*
Data control parameters.
​
output_bytes_per_line
u64
Bytes per line in output buffer (for custom stride).
​
info
jpgDecDataInfo*
Information about the decoded data.
​
value
f32
Progress value (0.0 to 1.0).
​
output_lines
u32
Number of lines decoded.
​
decode_status
u32
Decode status (JPGDEC_STATUS_FINISH or JPGDEC_STATUS_STOP).
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecClose

s32 jpgDecClose(s32 handle, s32 subhandle);
Closes a JPEG stream.
​
handle
s32
Decoder handle.
​
subhandle
s32
Stream subhandle to close.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgDecDestroy

s32 jpgDecDestroy(s32 handle);
Destroys a JPEG decoder instance.
​
handle
s32
Decoder handle to destroy.
Returns: JPGDEC_ERROR_OK on success, error code otherwise.

​
Helper Functions

​
jpgLoadFromFile

s32 jpgLoadFromFile(const char *filename, jpgData *out);
Simple helper function to load a JPEG image from a file.
​
filename
const char*
Path to the JPEG file.
​
out
jpgData*
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: JPGDEC_ERROR_OK on success, error code otherwise.

​
jpgLoadFromBuffer

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

​
Usage Example

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

int main() {
    s32 ret;
    s32 handle;
    s32 subhandle;
    jpgDecThreadInParam in_param;
    jpgDecThreadOutParam out_param;
    jpgDecSource src;
    jpgDecOpnInfo open_info;
    jpgDecInfo info;
    jpgDecInParam dec_in;
    jpgDecOutParam dec_out;
    jpgDecDataCtrlParam data_ctrl;
    jpgDecDataInfo data_info;
    u8 *output_buffer;

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

    // Create decoder
    in_param.spu_enable = JPGDEC_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 = jpgDecCreate(&handle, &in_param, &out_param);
    if (ret != JPGDEC_ERROR_OK) {
        printf("jpgDecCreate failed: 0x%x\n", ret);
        return -1;
    }

    // Open JPEG file
    src.stream_sel = JPGDEC_FILE;
    src.file_name = "/dev_hdd0/image.jpg";
    src.file_offset = 0;
    src.file_size = 0;  // 0 = read entire file
    src.spu_enable = JPGDEC_SPU_THREAD_DISABLE;

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

    // Read header
    ret = jpgDecReadHeader(handle, subhandle, &info);
    if (ret != JPGDEC_ERROR_OK) {
        printf("jpgDecReadHeader failed: 0x%x\n", ret);
        jpgDecClose(handle, subhandle);
        jpgDecDestroy(handle);
        return -1;
    }

    printf("Image: %dx%d, %d components\n", 
           info.width, info.height, info.num_comp);

    // Set decode parameters
    dec_in.cmd_ptr = NULL;
    dec_in.down_scale = 1;  // No downscaling
    dec_in.quality_mode = JPGDEC_QUALITY;
    dec_in.output_mode = JPGDEC_TOP_TO_BOTTOM;
    dec_in.color_space = JPGDEC_ARGB;
    dec_in.alpha = 0xFF;

    ret = jpgDecSetParameter(handle, subhandle, &dec_in, &dec_out);
    if (ret != JPGDEC_ERROR_OK) {
        printf("jpgDecSetParameter failed: 0x%x\n", ret);
        jpgDecClose(handle, subhandle);
        jpgDecDestroy(handle);
        return -1;
    }

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

    // Decode image
    data_ctrl.output_bytes_per_line = dec_out.width_bytes;
    ret = jpgDecDecodeData(handle, subhandle, output_buffer, 
                          &data_ctrl, &data_info);
    if (ret != JPGDEC_ERROR_OK) {
        printf("jpgDecDecodeData failed: 0x%x\n", ret);
        free(output_buffer);
        jpgDecClose(handle, subhandle);
        jpgDecDestroy(handle);
        return -1;
    }

    printf("Decode complete: %d lines\n", data_info.output_lines);

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

    // Cleanup
    free(output_buffer);
    jpgDecClose(handle, subhandle);
    jpgDecDestroy(handle);
    sysModuleUnload(SYSMODULE_JPGDEC);

    return 0;
}

​
Simple Usage Example

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

int main() {
    jpgData jpg;
    s32 ret;

    // Load JPEG decoder module
    sysModuleLoad(SYSMODULE_JPGDEC);

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

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

​
Extended API

The jpgdec library also provides extended functions for advanced use cases:
  • jpgDecExtOpen() - Opens a stream with callback support for streaming data
  • jpgDecExtReadHeader() - Reads header with extended information
  • jpgDecExtSetParameter() - Sets parameters with extended options (MCU mode, line mode)
  • jpgDecExtDecodeData() - Decodes with display callback support for progressive rendering
These functions allow for more control over the decoding process, including progressive decoding and custom data streaming.

Build docs developers (and LLMs) love

Get started for freeTalk to us