DominScript — sdl2image

3 functionsnamespace sdl2imagesource plugins/sdl2_image/Sdl2ImagePlugin.c

Introduction

The sdl2_image plugin is a thin adapter around the SDL2_image library: one plugin, one library. It initialises itself: IMG_Init (the decoder set) runs in the plugin’s Ready hook when the plugin is loaded and IMG_Quit at shutdown, so there is no init or quit verb to call — sdl2image.Load works from the first statement, headless too. It decodes an image file — PNG, JPG, WebP, TIFF, whatever the installed SDL2_image build supports — and returns the pixels as an OMVF packet blob: a 64-byte header (width, height, stride, format) followed by RGBA8 bytes. It is the same packet the built-in image plugin and ffmpeg.DecodeNextBlob produce, and the one sdl2.TextureFromPixels, sdl2.UpdateTexture and gl.UpdateTexture accept. The blob is the interface between the plugins: nothing here knows about windows or textures, so the same packet can go to a texture, a file, or a socket.

Libraries at run time

SDL2_image and SDL2 (for the surface and file functions) are opened when the plugin loads, before the script starts; if either is missing the script does not start, and the message names the file to copy into the runtime folder. No window and no sdl2.Init are needed to decode, so this works headless and without the sdl2 plugin.

When to use which image loader

The built-in image plugin reads BMP and simple PNG with no library at all; use it where nothing may be installed. Use sdl2image for the full format range. sdl2.LoadTexture loads BMP only.

Loading

From a file to a pixel packet.

sdl2image.Load

sdl2image.Load(path) -> blob

Decodes the image file at path and returns an OMVF RGBA8 pixel packet.

Parameters

Name	Type	Description
path	string	the image file (PNG, JPG, WebP, TIFF, BMP, GIF, … as SDL2_image supports)

Return value

A blob: 64-byte header, then width × height × 4 bytes of RGBA. The header fields (little-endian u32 at offsets 12, 16, 20) are width, height and stride; a struct can read them directly. A missing or undecodable file is a runtime error naming the file; a decoded image over 256 MiB is refused.

Example

blob $Logo[1] = sdl2image.Load("logo.png");
i32 $Tex = sdl.TextureFromPixels($Win, $Logo);

When to use

Any image that is not a plain BMP, for SDL2 textures (sdl2.TextureFromPixels), OpenGL textures (gl.UpdateTexture), or pixel processing in the script.

Capabilities

What this SDL2_image build can do.

sdl2image.Formats

sdl2image.Formats() -> string

The decoders the installed SDL2_image initialised, space-separated: "png jpg webp tif" on a full build, fewer on a trimmed one. BMP and GIF need no decoder and are always available.

Parameters

This function takes no arguments.

Return value

The format list, possibly empty.

Example

printf("%s\n", sdl2image.Formats());

Output after running

png jpg webp tif

sdl2image.FileExists

sdl2image.FileExists(path) -> int

1 if the file can be opened for reading, else 0. A convenience for choosing an asset before loading it.

Parameters

Name	Type	Description
path	string	the file to test

Return value

1 or 0.