ilbuffer(3G)

NAME
     ilbuffer - allocates framebuffer space to hold temporary image processing
     results

C SPECIFICATION
     long ilbuffer(long buffers)

PARAMETERS
     buffers    the number of 12bit-per-component screen-sized buffers
                requested

FUNCTION RETURN VALUE
     The returned value of the function is the number of buffers granted.

DESCRIPTION
     ilbuffer attempts to allocte buffers 12bit/component color buffers that
     span the entire display surface.

     On the RealityEngine, a 12bit/componenent color buffer consumes 3 16bit
     framebuffer words.  A count of the deepest pixel currently used is
     maintained by the Kernel graphics driver. The count is always at least 9
     16bit words, the value required to support 2 12bit/component color
     buffers and a Z/stencil buffer.  The remainder of the pixel depth can be
     allocated to the caller for use as temporary image processing storage.

     Any requests by other graphics contexts to use pixel depths that would
     extend into the allocated buffer are denied until the buffer is
     explicitly freed by ilbuffer(0), or the graphics context (window) is
     destroyed. Equivalently, if a graphics context uses features that require
     all of the pixel depth, ilbuffer may return 0. The resource is not
     virtualized and is allocated first come, first served.

     For example on a RealityEngine running with small pixel depth, 12 16bit
     framebuffer words available for graphics features. Six are required for
     double color buffers and three for Z/stencil. That leaves three that
     could be alloced for 1 ilbuffer if no other program has allocated a pixel
     depth greater than 9 impwords.

     On a RealityEngine running with medium pixel depth, 28 16bit framebuffer
     words are available for graphics features. Nine are required for basic
     double buffered Zbuffer operation, so 19 16bit words are available to be
     allocated as 6 ilbuffers if no other program has allocated a pixel depth
     greater than 9 16bit framebuffer words.

     Multiple contexts may allocate the same framebuffer space through calls
     to ilbuffer, but the ilbuffer is not virtualized (context switched), so
     user contexts must synchronize the use of this buffer themselves. The
     ImageLibrary uses this feature, so concurrent use of the ImageLibrary
     when it is using hardware acceleration and user programs that use this
     feature will not necessarily work together correctly. One possibility is
     to cause the ImageLibrary to use only the CPU while user programs use
     this feature.
     The ilbuffers can be selected for drawing with ildraw or as a readsource
     for pixel copies or framebuffer to texture loads with readsource

SEE ALSO
     ildraw, readsource

NOTE
     This routine is available only in immediate mode, and only on
     RealityEngine running 5.0.1 or later.