15.1. Image loading, writing, and resizing (stb_image)

Low-level image I/O and resizing bindings for stb_image, stb_image_write, and stb_image_resize2.

15.1.1. Enumerations

stbir_datatype

Pixel data type for resize operations.

Values:

  • STBIR_TYPE_UINT8 = 0 - 8-bit unsigned integer.

  • STBIR_TYPE_UINT8_SRGB = 1 - 8-bit unsigned integer with sRGB gamma.

  • STBIR_TYPE_UINT8_SRGB_ALPHA = 2 - 8-bit unsigned integer with sRGB gamma and linear alpha.

  • STBIR_TYPE_UINT16 = 3 - 16-bit unsigned integer.

  • STBIR_TYPE_FLOAT = 4 - 32-bit float.

  • STBIR_TYPE_HALF_FLOAT = 5 - 16-bit float (half precision).

stbir_edge

Edge handling mode for resize operations.

Values:

  • STBIR_EDGE_CLAMP = 0 - Clamp to edge pixels.

  • STBIR_EDGE_REFLECT = 1 - Reflect at edges.

  • STBIR_EDGE_WRAP = 2 - Wrap around (tile).

  • STBIR_EDGE_ZERO = 3 - Use zero for out-of-bounds pixels.

stbir_filter

Resampling filter for resize operations.

Values:

  • STBIR_FILTER_DEFAULT = 0 - Default filter (Catmull-Rom for downscale, cubic B-spline for upscale).

  • STBIR_FILTER_BOX = 1 - Box filter (nearest-neighbor averaging).

  • STBIR_FILTER_TRIANGLE = 2 - Triangle (bilinear) filter.

  • STBIR_FILTER_CUBICBSPLINE = 3 - Cubic B-spline filter.

  • STBIR_FILTER_CATMULLROM = 4 - Catmull-Rom filter.

  • STBIR_FILTER_MITCHELL = 5 - Mitchell-Netravali filter.

  • STBIR_FILTER_POINT_SAMPLE = 6 - Point sampling (nearest neighbor, no filtering).

  • STBIR_FILTER_OTHER = 7 - Reserved for custom filters.

stbir_pixel_layout

Pixel channel layout for resize operations.

Values:

  • STBIR_1CHANNEL = 1 - Single channel.

  • STBIR_2CHANNEL = 2 - Two channels.

  • STBIR_RGB = 3 - RGB layout.

  • STBIR_BGR = 0 - BGR layout.

  • STBIR_4CHANNEL = 5 - Four channels.

  • STBIR_RGBA = 4 - RGBA layout.

  • STBIR_BGRA = 6 - BGRA layout.

  • STBIR_ARGB = 7 - ARGB layout.

  • STBIR_ABGR = 8 - ABGR layout.

  • STBIR_RA = 9 - Red-Alpha layout.

  • STBIR_AR = 10 - Alpha-Red layout.

  • STBIR_RGBA_PM = 11 - RGBA with premultiplied alpha.

  • STBIR_BGRA_PM = 12 - BGRA with premultiplied alpha.

  • STBIR_ARGB_PM = 13 - ARGB with premultiplied alpha.

  • STBIR_ABGR_PM = 14 - ABGR with premultiplied alpha.

  • STBIR_RA_PM = 15 - Red-Alpha with premultiplied alpha.

  • STBIR_AR_PM = 16 - Alpha-Red with premultiplied alpha.

15.1.2. Image loading

stbi_load(filename: string; x: int?; y: int?; comp: int?; req_comp: int): uint8?

Load an image from file, returning pixel data as uint8.

Arguments:

  • filename : string implicit

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_load_16(filename: string; x: int?; y: int?; comp: int?; req_comp: int): uint16?

Load an image from file as 16-bit unsigned integer data.

Arguments:

  • filename : string implicit

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_load_16_from_memory(buffer: uint8 const?; len: int; x: int?; y: int?; comp: int?; req_comp: int): uint16?

Load an image from a memory buffer as 16-bit unsigned integer data.

Arguments:

  • buffer : uint8? implicit

  • len : int

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_load_from_memory(buffer: uint8 const?; len: int; x: int?; y: int?; comp: int?; req_comp: int): uint8?

Load an image from a memory buffer as uint8.

Arguments:

  • buffer : uint8? implicit

  • len : int

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_load_gif_from_memory(buffer: uint8 const?; len: int; delays: int??; x: int?; y: int?; z: int?; comp: int?; req_comp: int): uint8?

Load all frames of an animated GIF from a memory buffer.

Arguments:

  • buffer : uint8? implicit

  • len : int

  • delays : int?? implicit

  • x : int? implicit

  • y : int? implicit

  • z : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_loadf(filename: string; x: int?; y: int?; comp: int?; req_comp: int): float?

Load an image from file as HDR float data.

Arguments:

  • filename : string implicit

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

stbi_loadf_from_memory(buffer: uint8 const?; len: int; x: int?; y: int?; comp: int?; req_comp: int): float?

Load an image from a memory buffer as HDR float data.

Arguments:

  • buffer : uint8? implicit

  • len : int

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

  • req_comp : int

15.1.3. Image info

stbi_info(filename: string; x: int?; y: int?; comp: int?): int

Query image dimensions and channel count from a file without loading pixel data.

Arguments:

  • filename : string implicit

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

stbi_info_from_memory(buffer: uint8 const?; len: int; x: int?; y: int?; comp: int?): int

Query image dimensions and channel count from a memory buffer without decoding.

Arguments:

  • buffer : uint8? implicit

  • len : int

  • x : int? implicit

  • y : int? implicit

  • comp : int? implicit

stbi_is_16_bit(filename: string): int

Check if a file contains 16-bit image data.

Arguments:

  • filename : string implicit

stbi_is_16_bit_from_memory(buffer: uint8 const?; len: int): int

Check if a memory buffer contains 16-bit image data.

Arguments:

  • buffer : uint8? implicit

  • len : int

stbi_is_hdr(filename: string): int

Check if a file contains HDR image data.

Arguments:

  • filename : string implicit

stbi_is_hdr_from_memory(buffer: uint8 const?; len: int): int

Check if a memory buffer contains HDR image data.

Arguments:

  • buffer : uint8? implicit

  • len : int

15.1.4. Memory management

stbi_failure_reason(): string

Return a description of the last load failure.

stbi_image_free(retval_from_stbi_load: void?)

Free pixel data allocated by stbi_load and related functions.

Arguments:

  • retval_from_stbi_load : void? implicit

15.1.5. Load settings

stbi_convert_iphone_png_to_rgb(flag: int)

Set whether to convert iPhone PNG format to standard RGB.

Arguments:

  • flag : int

stbi_set_flip_vertically_on_load(flag: int)

Set whether loaded images should be flipped vertically.

Arguments:

  • flag : int

stbi_set_unpremultiply_on_load(flag: int)

Set whether to unpremultiply alpha on load (iPhone PNG).

Arguments:

  • flag : int

15.1.6. HDR gamma and scale

stbi_hdr_to_ldr_gamma(gamma: float)

Set gamma value for HDR to LDR conversion.

Arguments:

  • gamma : float

stbi_hdr_to_ldr_scale(scale: float)

Set scale factor for HDR to LDR conversion.

Arguments:

  • scale : float

stbi_ldr_to_hdr_gamma(gamma: float)

Set gamma value for LDR to HDR conversion.

Arguments:

  • gamma : float

stbi_ldr_to_hdr_scale(scale: float)

Set scale factor for LDR to HDR conversion.

Arguments:

  • scale : float

15.1.7. File writing

stbi_write_bmp(filename: string; x: int; y: int; comp: int; data: void?): int

Write image data to a BMP file.

Arguments:

  • filename : string implicit

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

stbi_write_hdr(filename: string; x: int; y: int; comp: int; data: float const?): int

Write HDR float image data to an HDR file.

Arguments:

  • filename : string implicit

  • x : int

  • y : int

  • comp : int

  • data : float? implicit

stbi_write_jpg(filename: string; x: int; y: int; comp: int; data: void?; quality: int): int

Write image data to a JPEG file with specified quality.

Arguments:

  • filename : string implicit

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • quality : int

stbi_write_png(filename: string; x: int; y: int; comp: int; data: void?; stride_bytes: int): int

Write image data to a PNG file.

Arguments:

  • filename : string implicit

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • stride_bytes : int

stbi_write_tga(filename: string; x: int; y: int; comp: int; data: void?): int

Write image data to a TGA file.

Arguments:

  • filename : string implicit

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

15.1.8. Write to memory

stbi_write_bmp_to_memory(x: int; y: int; comp: int; data: void?; block: block<(array<uint8>#):void>)

Encode image data as BMP to a memory buffer.

Arguments:

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • block : block<(array<uint8>#):void> implicit

stbi_write_jpg_to_memory(x: int; y: int; comp: int; data: void?; quality: int; block: block<(array<uint8>#):void>)

Encode image data as JPEG to a memory buffer.

Arguments:

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • quality : int

  • block : block<(array<uint8>#):void> implicit

stbi_write_png_to_memory(x: int; y: int; comp: int; data: void?; stride_bytes: int; block: block<(array<uint8>#):void>)

Encode image data as PNG to a memory buffer.

Arguments:

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • stride_bytes : int

  • block : block<(array<uint8>#):void> implicit

stbi_write_tga_to_memory(x: int; y: int; comp: int; data: void?; block: block<(array<uint8>#):void>)

Encode image data as TGA to a memory buffer.

Arguments:

  • x : int

  • y : int

  • comp : int

  • data : void? implicit

  • block : block<(array<uint8>#):void> implicit

15.1.9. Write settings

stbi_flip_vertically_on_write(flag: int)

Set whether to flip images vertically when writing.

Arguments:

  • flag : int

stbi_write_get_force_png_filter(): int

Get current PNG filter mode setting.

stbi_write_get_png_compression_level(): int

Get current PNG compression level.

stbi_write_get_tga_with_rle(): int

Get current TGA RLE compression setting.

stbi_write_set_force_png_filter(filter: int)

Force a specific PNG filter mode (-1 for auto).

Arguments:

  • filter : int

stbi_write_set_png_compression_level(level: int)

Set PNG compression level (default 8).

Arguments:

  • level : int

stbi_write_set_tga_with_rle(rle: int)

Set whether TGA files use RLE compression.

Arguments:

  • rle : int

15.1.10. Image resizing

stbir_resize(input_pixels: void?; input_w: int; input_h: int; input_stride_in_bytes: int; output_pixels: void?; output_w: int; output_h: int; output_stride_in_bytes: int; pixel_layout: stbir_pixel_layout; data_type: stbir_datatype; edge: stbir_edge; filter: stbir_filter): void?

Resize image with full control over data type, layout, edge mode, and filter.

Arguments:

  • input_pixels : void? implicit

  • input_w : int

  • input_h : int

  • input_stride_in_bytes : int

  • output_pixels : void? implicit

  • output_w : int

  • output_h : int

  • output_stride_in_bytes : int

  • pixel_layout : stbir_pixel_layout

  • data_type : stbir_datatype

  • edge : stbir_edge

  • filter : stbir_filter

stbir_resize_float_linear(input_pixels: float const?; input_w: int; input_h: int; input_stride_in_bytes: int; output_pixels: float?; output_w: int; output_h: int; output_stride_in_bytes: int; pixel_type: stbir_pixel_layout): float?

Resize a float image in linear color space.

Arguments:

  • input_pixels : float? implicit

  • input_w : int

  • input_h : int

  • input_stride_in_bytes : int

  • output_pixels : float? implicit

  • output_w : int

  • output_h : int

  • output_stride_in_bytes : int

  • pixel_type : stbir_pixel_layout

stbir_resize_uint8_linear(input_pixels: uint8 const?; input_w: int; input_h: int; input_stride_in_bytes: int; output_pixels: uint8?; output_w: int; output_h: int; output_stride_in_bytes: int; pixel_type: stbir_pixel_layout): uint8?

Resize a uint8 image in linear color space.

Arguments:

  • input_pixels : uint8? implicit

  • input_w : int

  • input_h : int

  • input_stride_in_bytes : int

  • output_pixels : uint8? implicit

  • output_w : int

  • output_h : int

  • output_stride_in_bytes : int

  • pixel_type : stbir_pixel_layout

stbir_resize_uint8_srgb(input_pixels: uint8 const?; input_w: int; input_h: int; input_stride_in_bytes: int; output_pixels: uint8?; output_w: int; output_h: int; output_stride_in_bytes: int; pixel_type: stbir_pixel_layout): uint8?

Resize a uint8 image with sRGB gamma correction.

Arguments:

  • input_pixels : uint8? implicit

  • input_w : int

  • input_h : int

  • input_stride_in_bytes : int

  • output_pixels : uint8? implicit

  • output_w : int

  • output_h : int

  • output_stride_in_bytes : int

  • pixel_type : stbir_pixel_layout

15.1.11. Animated PNG (APNG) writer

stbi_apng_begin(filename: string; w: int; h: int; channels: int): void?

Begin streaming APNG encoding to filename. channels is 3 (RGB) or 4 (RGBA). Returns an opaque writer handle; pass it to stbi_apng_frame and stbi_apng_end, or null on failure.

Arguments:

  • filename : string implicit

  • w : int

  • h : int

  • channels : int

stbi_apng_dropped(writer: void?): int

Return the running count of frames dropped because the encoder thread’s bounded queue was full.

Arguments:

  • writer : void? implicit

stbi_apng_end(writer: void?): int

Finalize the APNG file: drain the encoder thread, backpatch the acTL frame count, write IEND, and free the writer. Returns 1 on success.

Arguments:

  • writer : void? implicit

stbi_apng_frame(writer: void?; pixels: void?; stride_bytes: int; delay_ms: int): int

Queue one frame on writer. Pixels are expected in bottom-up row order (glReadPixels output) — the encoder thread flips rows top-down before encoding, so callers should not pre-flip. stride_bytes is the positive pixel-row stride and must be at least width * channels; negative-stride values are rejected. delay_ms is how long the frame is shown. Returns 1 on success (including the queue-full case, which silently drops the oldest queued frame — see stbi_apng_dropped for the running count), 0 on invalid input (null pixels / bad stride) or if the writer has entered an internal error state from a prior async I/O or encode failure; in that case callers should stop and call stbi_apng_end.

Arguments:

  • writer : void? implicit

  • pixels : void? implicit

  • stride_bytes : int

  • delay_ms : int