Written from a line-by-line source review; every example output is from a real run.
Introduction
The image plugin loads image files from disk and returns them as an **OMVF frame-packet** blob: the same 64-byte-header RGBA8 layout that ffmpeg.DecodeNextBlob produces and that the opengl/sdl plugin's texture operations expect. So a loaded image can be used directly, without conversion, in 3D scenes, in cube textures, or in video channels — there is a unified “image blob” format behind them.
Supported formats
The plugin chooses by file extension. `.bmp` (case-insensitive) always goes to the built-in BMP loader. On Linux, `.png` (8-bit, non-interlaced) goes to the built-in PNG loader — it uses zlib to decompress the image data. On Windows, every other extension is handled by the system's GDI image loader, so support is broader there (e.g. JPG, GIF, TIFF), but BMP still uses the own code.
The OMVF frame packet
Every loaded image goes into a blob beginning with a 64-byte header. The header layout: 4 bytes magic (“OMVF”), 4 bytes version (1), 4 bytes header size (64), 4-4 bytes width and height, 4 bytes stride (width\*4), 4 bytes format id (1=RGBA8), 4 bytes pixel offset (64), 8-8 bytes index and pts (both 0). After the header, exactly width\*height\*4 bytes of pixels follow in RGBA order. The same format is produced by ffmpeg-decoded frames, and the opengl texture uploaders accept it as well.
Loading the plugin
plugin "../plugins/print/PrintPlugin"; plugin "../plugins/image/ImagePlugin";
A typical flow — loading an image for a texture
blob $img[1048576];
if (image.FileExists("sprites/hero.png") == 1)
{
$img = image.Load("sprites/hero.png");
// ... $img can be passed directly to a texture uploader ...
}What to know about every function (the basics)
Load returns a frame-packet blob: 64 bytes header + width\*height\*4 bytes RGBA8 pixels. The total size is therefore 64 + 4\*width\*height bytes.
It decides by extension: `.bmp` always goes to the own BMP loader. On Linux, `.png` to the own PNG loader (8-bit, non-interlaced). On Windows, every other extension is handled by GDI.
FileExists gives a quick yes/no answer — without actually opening or reading the file.
The loaded image always arrives as RGBA8 in the blob, even if the source file was 24-bit BMP: the alpha channel is then 0xFF (opaque).
The OMVF header's version is 1, the format id is 1 (RGBA8). These constants match the formats used by the ffmpeg and opengl plugins.
An error (stopping the script) is caused by an empty path, a missing or unsupported-format file, a corrupted image, and memory exhaustion.
How to read the signatures
path is a filesystem path as a string (relative or absolute). The type after the -> arrow is the return type. image.Load(path) -> blob expects a path and returns an OMVF frame-packet blob; image.FileExists(path) -> int takes the same path but gives a 1/0 answer.
Loading
Reading an image file into an OMVF frame packet (64-byte header + RGBA8 pixels).
image.Load
image.Load(path) -> blob
Loads an image file and returns an OMVF frame-packet blob: a 64-byte header + width\*height\*4 bytes of RGBA8 pixels.
| Parameter | Type | Description |
|---|---|---|
| path | string | The file path. Chosen by extension: `.bmp` always to the BMP loader, `.png` on Linux to the PNG loader, other extensions on Windows to GDI. |
An OMVF frame-packet blob. Size: 64 + 4\*width\*height bytes. A runtime error on failure.
blob $img[1024];
$img = image.Load("Examples/_test2x2.bmp");
printf("%d\n", $img.Length);
printf("%d %d %d %d\n", $img[0], $img[1], $img[2], $img[3]);80 79 77 86 70
For loading sprites, icons, and background images. The returned blob can be passed directly to opengl.UpdateTexture or similar texture uploaders — they all work on the same OMVF format. If you load many images, check first with FileExists, because Load raises a runtime error on failure.
Inspection
A quick check of a file's existence — before the actual load.
image.FileExists
image.FileExists(path) -> int
Tells whether the given file exists in the filesystem.
| Parameter | Type | Description |
|---|---|---|
| path | string | The path of the file to check. |
1 if the file exists; 0 if not.
printf("%d\n", image.FileExists("Examples/_test2x2.bmp"));
printf("%d\n", image.FileExists("Examples/missing.bmp"));1 0
A quick guard before loading an image. FileExists does not open or read the file — it only checks filesystem-level existence. For error-handling logic (e.g. optional image fallback), it is often simpler than wrapping Load with error handling.
Practical notes
What the image plugin is good for
Loading sprites, icons, backgrounds, and textures from disk into a directly usable OMVF format.
Same format as ffmpeg-decoded frames: the same opengl/sdl texture operations process both.
Simple file-existence check (FileExists) — quick and non-blocking.
Reading and converting to RGBA8 in a single step: 24-bit BMP, 8-bit PNG, and the GDI-supported formats are all equally transparent to the caller.
OMVF compatibility
The blob returned by the plugin is the same OMVF format that the ffmpeg-decoder output and the opengl/sdl texture uploaders also use. So an image and a video frame are the same kind of data — equally passable to a texture channel, and equally interpretable through the header fields (width, height, stride, format). The key fields of the 64-byte header: the magic (offset 0, “OMVF”), the width (offset 12, little-endian uint32), the height (offset 16), the stride (offset 20, always 4\*width), and the format id (offset 24, 1=RGBA8).
BMP and PNG support
The BMP loader handles 24- and 32-bit uncompressed BMP files — for the 24-bit ones it fills the alpha channel with 0xFF. The PNG loader (on Linux) reads 8-bit-per-channel, NON-interlaced PNG files; paletted and other variants are NOT supported. The Windows GDI loader provides broad support: JPG, GIF, TIFF, etc. If you want guaranteed cross-platform behavior, use BMP (works everywhere) or the strict PNG variant described above.
Memory and performance
The total size of the returned blob is 64 + 4\*width\*height bytes. So a 1920×1080 image takes about 8.3 MB. For large images it is worth estimating memory in advance and releasing the blob after use. Loading is synchronous — file I/O and decoding block the calling thread; a large PNG can take several 10 ms.
Error handling
An empty or invalid path, a missing file, an unsupported format (e.g. .gif on Linux), a corrupted image file, and memory exhaustion are reported by the runtime as a runtime error, and the script stops. FileExists, in contrast, gives a neutral 1/0 — it never fails, and it does not open the file, only inspects the meta-information.
The callbackudpserver UDP server plugin
Loopback UDP server, packet-driven callbacks, and diagnostics — complete function reference