NAME

load_image - synchronously load supported images

SYNOPSIS

VID, fail:BADID
load_image( resource, startzv, desired width, desired height )

DESCRIPTION

Sets up a new video object container and attempts to load and decode an image from the specified resource.

NOTES

1: The new VID has its opacity set to 0 (hidden)
2: This routine is synchronous, so it will block until the image has been loaded
3: desired width/desired height are capped to the engine compile-time values CONST_MAX_SURFACEW , CONST_MAX_SURFACEH (2048x2048)
4: If the engine is running in conservative mode, no local copy will be kept in memory and the resource will be reloaded on every operation that manipulates the current rendering context (e.g. stack push / pop or launch_target(external).
5: supported file formats vary with platform and engine build, only ones that are guaranteed to work are PNG and JPEG .

EXAMPLE

function load_image0()
      vid = load_image("test.png");
      show_image(vid);
      vid2 = load_image("test.png", 2, 48, 48);
      show_image(vid);
end

MISUSE

function load_image0()
      vid = load_image();
end

MISUSE

function load_image1()
      vid = load_image("test.png", -1, -1, -1);
end