fxAllocateImageBuffers(3dm)

NAME
     dmFXAllocateImageBuffers, dmFXFreeImageBuffers - create and destroy image
     buffers for special effects


SYNOPSIS
     #include <dmedia/fx_buffer.h>

     DMstatus dmFXAllocateImageBuffers
           ( Display* dpy,
             const DMparams* imageFormat,
             int inputUsage,
             int outputUsage,
             int numberOfBuffers,
             DMfxbuffer* returnBuffers[] )

     void dmFXFreeImageBuffers
           ( int numberOfBuffers,
             DMfxbuffer* buffers[] )


PARAMETERS
     dpy               An open connection to an X server.  Used to create
                       off-screen render areas for OpenGL.  The caller must
                       not close the display connection until all of the
                       DMfxbuffers have been freed.

     imageFormat       A complete image format parameter list (see
                       dmSetImageDefaults(3dm)).  This format is used to
                       determine how large the buffers need to be.

     inputUsage        Specifies the modes in which the buffer will be used as
                       input; says how the image will be read from the buffer
                       and used as input to a plug-in or application.  The
                       value is a bitwise combination of one or more of:
                       bufInputDirect, bufInputTexture, bufInputDrawPixels,
                       bufInputMovie.  The options set must include all of the
                       different ways in which the buffer will be used.

     outputUsage       Specifies the modes in which the buffer will be used as
                       output; says how the image will be placed into the
                       buffer by a plug-in or application.  the value is a
                       bitwise combination of one or more of bufOutputDirect,
                       bufOutputOpenGL, bufOutputmovie.  The options set must
                       include all of the different ways in which the buffer
                       will be used.

     numberOfBuffers   The number of buffers to be allocated or freed.

     returnBuffers     A pointer to an array of DMfxbuffer*, which will be
                       filled in.

     buffers           A pointer to an array of DMfxbuffer*.


DESCRIPTION
     dmFXAllocateImageBuffers creates buffers for use with the special-effects
     plugin manager.  The buffers it creates can be used to efficiently pass
     images to an from image processing plugins.

     The input and output usage given are used to determine the
     characteristics of the buffers to be allocated.  For example, when the
     bufOutputOpenGL bit is set, the buffers created will be suitable for
     OpenGL rendering.  An application can determine values for input and
     output usage by examining the input and output usage of all of the
     plugins to be used and or-ing them together.

     On many SGI machines, image buffers for special effects processing take
     advantage of special hardware resources associated with graphical
     rendering.  These resources are frequently in short supply.  An
     application that uses special effects should avoid holding image buffers
     unnecessarily.  For example, when the application is iconized, it should
     release these image buffers.


RETURN VALUES
     dmFXAllocateImageBuffers will either create all of the buffers requested
     and return DM_SUCCESS, or will create no buffers and return DM_FAILURE.
     In the case of failure, error information can be obtained from
     dmGetError(3dm).


EXAMPLE
     This will combine the usage bits for a number of filter plugins and then
     a pair of buffers that can be used with any of them:

         DMparams* imageFormat;
         DMplugin* plugins[];
         int pluginCount;
         int in;   /* combined input usage  */
         int out;  /* combined output usage */
         int i;
         DMfxbuffer buffers[2];

         /* get the list of plugins to use */
         ...

         /* combine the usage bits of all of the plugins */
         in  = 0;
         out = 0;
         for ( i = 0;  i < pluginCount;  i++ )
         {
             in  |= pmGetSourceAUsage( plugins[i] );
             out |= pmGetDestUsage   ( plugins[i] );
         }

         /* allocate two buffers */
         if ( dmFXAllocateImageBuffers( imageFormat, in, out, 2,
                  buffers ) != DM_SUCCESS )
         {
             /* allocation failed */
         }


SEE ALSO
     dmFXMovieRenderImage(3dm), dmFXSetupInputImageBuffer(3dm),
     dmFXSetupScanlineBuffer(3dm), dmGetError(3dm).