instance_image

declaration:

instance_vid(source_vid) => VID or BADID

Creates a linked clone of source_vid. Clones are automatically destroyed when the parent is removed and its parent property cannot be changed. Like with any other function that creates a vid, it starts out hidden, with its coordinate system linked to the parent.

example use:

This will create a red block in the middle of the screen, and a smaller red block as an instance that will move around it's parent in an outer square formation. Both will disappear when the parent expires.

::lua
function test()
parent = fill_surface(32, 32, 255, 0, 0);
child = instance_image(parent);
show_image(parent);
show_image(child);

move_image(parent, VRESW * 0.5, VRESH * 0.5);
scale_image(child, 0.5, 0.5);

move_image(child, -64, -64, 0);
move_image(child, 64, -64, 25);
move_image(child, 64, 64, 25);
move_image(child, -64, 64, 25);
move_image(child, -64, -64, 25);

expire_image(parent, 100);
end

caveats:

This function is particularly useful for particle systems, and as a way of reducing memory usage with multiple objects using the same video source.

The vids resulting from instancing should be tracked carefully. A lot of operations that are valid on normal objects would fail on a cloned one (manipulating frameset for instance.)

Any dangling references when the parent have been destroyed are likely sources of errors. [check_vid] can be used to as a means to hunt these down.

related functions:

[link_image] [image_parent] [image_children]