15.2. High-level image API (stbimage_boost)

High-level image API built on stbimage and raster. Provides the Image struct with load, save, resize, flip, crop, blit, and format conversion.

15.2.1. Structures

Image

Image container with raw pixel data in original format. bpc (bytes per component): 1 = uint8, 2 = uint16, 4 = float. channels: 1 = grey, 2 = grey+alpha, 3 = RGB, 4 = RGBA.

Fields:

  • bytes : array<uint8> - Raw pixel data stored as a byte array.

  • width : int - Width of the image in pixels.

  • height : int - Height of the image in pixels.

  • channels : int - Number of color channels (1=grey, 2=grey+alpha, 3=RGB, 4=RGBA).

  • bpc : int - Bytes per component (1=uint8, 2=uint16, 4=float).

Image.valid(): bool

def Image.valid

Image.stride(): int

def Image.stride

Image.has_alpha(): bool

def Image.has_alpha

Image.pixel_size(): int

def Image.pixel_size

Image.is_hdr(): bool

def Image.is_hdr

Image.data_size(): int

def Image.data_size

Image.load(path: string; requested_channels: int = 0): tuple<bool;string>

def Image.load

Arguments:

  • path : string

  • requested_channels : int

Image.load_hdr(path: string; requested_channels: int = 0): tuple<bool;string>

def Image.load_hdr

Arguments:

  • path : string

  • requested_channels : int

Image.load_16(path: string; requested_channels: int = 0): tuple<bool;string>

def Image.load_16

Arguments:

  • path : string

  • requested_channels : int

Image.load_from_memory(data: array<uint8>; requested_channels: int = 0): tuple<bool;string>

def Image.load_from_memory

Arguments:

  • data : array<uint8>

  • requested_channels : int

Image.load_from_memory(data: array<uint8>#; requested_channels: int = 0): tuple<bool;string>

def Image.load_from_memory

Arguments:

  • data : array<uint8>#

  • requested_channels : int

Image.load_hdr_from_memory(data: array<uint8>; requested_channels: int = 0): tuple<bool;string>

def Image.load_hdr_from_memory

Arguments:

  • data : array<uint8>

  • requested_channels : int

Image.load_hdr_from_memory(data: array<uint8>#; requested_channels: int = 0): tuple<bool;string>

def Image.load_hdr_from_memory

Arguments:

  • data : array<uint8>#

  • requested_channels : int

Image.load_16_from_memory(data: array<uint8>; requested_channels: int = 0): tuple<bool;string>

def Image.load_16_from_memory

Arguments:

  • data : array<uint8>

  • requested_channels : int

Image.load_16_from_memory(data: array<uint8>#; requested_channels: int = 0): tuple<bool;string>

def Image.load_16_from_memory

Arguments:

  • data : array<uint8>#

  • requested_channels : int

Image.save(path: string; quality: int = 0): tuple<bool;string>

def Image.save

Arguments:

  • path : string

  • quality : int

Image.encode(format: string; out_data: array<uint8>; quality: int = 0): tuple<bool;string>

def Image.encode

Arguments:

  • format : string

  • out_data : array<uint8>

  • quality : int

Image.resize(new_w: int; new_h: int): Image

def Image.resize

Arguments:

  • new_w : int

  • new_h : int

Image.resize(new_w: int; new_h: int; filter: stbir_filter): Image

def Image.resize

Arguments:
Image.flip_vertical(): Image

def Image.flip_vertical

Image.flip_horizontal(): Image

def Image.flip_horizontal

Image.crop(cx: int; cy: int; cw: int; ch: int): Image

def Image.crop

Arguments:

  • cx : int

  • cy : int

  • cw : int

  • ch : int

Image.blit(src: Image; dst_x: int; dst_y: int)

def Image.blit

Arguments:

  • src : Image

  • dst_x : int

  • dst_y : int

Image.fill_rect(x: int; y: int; w: int; h: int; color: uint)

def Image.fill_rect

Arguments:

  • x : int

  • y : int

  • w : int

  • h : int

  • color : uint

Image.fill_rect(x: int; y: int; w: int; h: int; val: uint8)

def Image.fill_rect

Arguments:

  • x : int

  • y : int

  • w : int

  • h : int

  • val : uint8

Image.blit_alpha(src: Image; sx: int; sy: int; dx: int; dy: int; w: int; h: int; r: int; g: int; b: int)

def Image.blit_alpha

Arguments:

  • src : Image

  • sx : int

  • sy : int

  • dx : int

  • dy : int

  • w : int

  • h : int

  • r : int

  • g : int

  • b : int

Image.to_channels(target_channels: int): Image

def Image.to_channels

Arguments:

  • target_channels : int

Image.to_bpc(target_bpc: int): Image

def Image.to_bpc

Arguments:

  • target_bpc : int

15.2.2. Image construction

make_image(w: int; h: int; channels: int; bpc: int = 1): Image

Create a blank (zeroed) image with the given dimensions.

Arguments:

  • w : int

  • h : int

  • channels : int

  • bpc : int

15.2.3. Image loading

image_info(path: string): tuple<w:int;h:int;comp:int>

Get image dimensions and channel count without loading pixel data.

Arguments:

  • path : string

is_16_bit(path: string): bool

Returns true if the file contains 16-bit data.

Arguments:

  • path : string

is_16_bit_from_memory(data: array<uint8>): bool

Returns true if the memory buffer contains 16-bit data.

Arguments:

  • data : array<uint8>

is_hdr(path: string): bool

Returns true if the file is in HDR format.

Arguments:

  • path : string

is_hdr_from_memory(data: array<uint8>): bool

Returns true if the memory buffer contains HDR format data.

Arguments:

  • data : array<uint8>

15.2.3.1. load_image

load_image(path: string; error: string&): Image

Load an image from file. Sets error on failure.

Arguments:

  • path : string

  • error : string&

load_image(path: string): Image

15.2.4. Pixel access

15.2.4.1. with_pixels

with_pixels(self: Image; blk: block<(var pixels:array<float>#):void>)

Access pixel data as array<float>. Image must have bpc == 4.

Arguments:

  • self : Image

  • blk : block<(pixels:array<float>#):void>

with_pixels(self: Image; blk: block<(var pixels:array<uint8>#):void>)
with_pixels(self: Image; blk: block<(var pixels:array<uint16>#):void>)
with_pixels_16(self: Image; blk: block<(var pixels:array<uint16>#):void>)

Explicit-name alias for with_pixels with uint16 block. For use in generics.

Arguments:

  • self : Image

  • blk : block<(pixels:array<uint16>#):void>

with_pixels_f(self: Image; blk: block<(var pixels:array<float>#):void>)

Explicit-name alias for with_pixels with float block. For use in generics.

Arguments:

  • self : Image

  • blk : block<(pixels:array<float>#):void>

15.2.4.2. with_row

with_row(self: Image; y: int; blk: block<(var row:array<float>#):void>)

Access a single row as array<float>. Image must have bpc == 4.

Arguments:

  • self : Image

  • y : int

  • blk : block<(row:array<float>#):void>

with_row(self: Image; y: int; blk: block<(var row:array<uint8>#):void>)
with_row(self: Image; y: int; blk: block<(var row:array<uint16>#):void>)
with_row_16(self: Image; y: int; blk: block<(var row:array<uint16>#):void>)

Explicit-name alias for with_row with uint16 block.

Arguments:

  • self : Image

  • y : int

  • blk : block<(row:array<uint16>#):void>

with_row_f(self: Image; y: int; blk: block<(var row:array<float>#):void>)

Explicit-name alias for with_row with float block.

Arguments:

  • self : Image

  • y : int

  • blk : block<(row:array<float>#):void>

15.2.5. Image properties