NAME

image_access_storage - Access the underlying backing store of a textured video object.

SYNOPSIS

true or false
image_access_storage( vid, callback(vtbl:context, int:width, int:height) )
image_access_storage( vid, callback(vtbl:context, int:width, int:height, int:cols, int:rows) )

DESCRIPTION

This function permits limited, blocking, access to a backing store. The primary purpose is to provide quick access to trivial measurements without the overhead of setting up a calctarget and performing readbacks. The function returns false if the backing store was unavailable.

The context argument is described in define_calctarget .

If the callback provides cols and rows it means that the table represents a textual backing store rather than a pixel one. In that case the following extra functions are available in context :

NOTES

1

The table provided in the callback is only valid during the scope of the callback, creating aliases outside this scope and trying to use any table method is a terminal state transition that may be difficult to debug.

2

Most frameserver connections do not synchronize the contents of the backing store buffer due to the added bandwidth cost of performing an extra copy each update. This behavior can be changed by calling target_flags and enable TARGET_VSTORE_SYNCH for the specific frameserver.

3

The backing store of a texture video object is not always available, particularly when the engine is running in conservative mode. Make sure that your appl can handle scenarios where the backing store cannot be read.

4

:read is only permitted on a tui backed store. Calling it on a regular one is a terminal state transition.

EXAMPLE

function image_access_storage0()


      img = fill_surface(32, 32, 255, 0, 0);


      image_access_storage(a, function(tbl, w, h)


            print(w, h, tbl:get(1, 1));


      end);
end

SEE ALSO:

define_calctarget(3)