fxSetupInputImageBuffer(3dm)

NAME
     dmFXSetupInputImageBuffer, dmFXSetupInputImageBufferWithUsage,
     dmFXSetupOutputImageBuffer, dmFXCleanupInputImageBuffer,
     dmFXCleanupOutputImageBuffer - manage special-effects image buffers


SYNOPSIS
     #include <dmedia/fx_buffer.h>

     DMstatus dmFXSetupInputImageBuffer
           ( DMfxbuffer* buffer )

     DMstatus dmFXSetupInputImageBufferWithUsage
           ( int         inputUsage,
             DMfxbuffer* buffer )

     DMstatus dmFXSetupOutputImageBuffer
           ( int outputUsage,
             int inputUsage,
             DMfxbuffer* buffer )

     DMstatus dmFXCleanupInputImageBuffer
           ( DMfxbuffer* buffer )

     DMstatus dmFXCleanupOutputImageBuffer
           ( DMfxbuffer* buffer )


PARAMETERS
     buffer        a special-effects image buffer, allocated with
                   dmFXAllocateImageBuffers.

     outputUsage   Specifies the mode 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 one of
                   bufOutputDirect, bufOutputOpenGL, bufOutputmovie.  No more
                   that one can be set.

     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
                   this specific image will be used.


DESCRIPTION
     These functions are used to prepare buffers before calling an image
     processing plugin, and clean up after calling a plugin.

     Image buffers for special effects require special handling because they
     must support efficient access to OpenGL and image
     compression/decompression.  Because of this, they may reside in memory
     that is shared with the graphics and compression device drivers.  Setting
     up a buffer before calling a plugin may involve cache flushing and image
     reformatting.  Similarly, after a plugin is called, cleanup may involve
     restoring cache coherency and reformatting the image.

     Every use of an image buffer must be preceeded by a setup call, and
     succeeded by a cleanup call.

     If an image buffer is to be used as input to a plugin,
     dmFXSetupInputImageBuffer should be called before calling the plugin, and
     dmFXCleanupInputImageBuffer should be called after the plugin has
     finished.

     If an image buffer is to be used to store the output of a plugin,
     dmFXSetupOutputImageBuffer should be called before the plugin is invoked,
     and dmFXCleanupOutputImageBuffer should be called afterward.

     Usage bits must be supplied to dmFXSetupOutputImageBuffer that specify
     both how the image will be generated (output usage)  and how it will
     later be used (input usage).  The input usage must be specified at this
     point so that the format of the data in the buffer will match the way it
     will be used.  If an application does not know how a buffer will be used,
     it can use bufInputAll as the input usage, but this may impair
     performance.

     It is acceptable to always use bufInputAll when specifying input usage,
     but doing so may slow things down.  If your application does not have the
     input usage available when calling dmFXSetupOutputImageBuffer, you can
     give it bufInputAll.  If the input usage is known later, at the time when
     the buffer is set up for input, dmFXSetupInputImageBufferWithUsage may be
     used.  This will enable the some optimizations, but may not be as
     efficient as specifying the input usage when the buffer is set up for
     output.

     If an application needs to read or write the contents of an image buffer
     directly, it should treat itself as a plugin that uses direct access.
     For example, to place an image in a buffer, call
     dmFXSetupOutputImageBuffer with bufOutputDirect, use
     dmFXSetupScanlineBuffer to get a pointer to the buffer, store the pixels,
     and finally call dmFXCleanupOutputImageBuffer.

     Normally, calling dmFXSetupOutputImageBuffer will discard any previous
     contents of the buffer.  In one case, though, the contents of the buffer
     are guaranteed to be preserved: if a buffer has been set up for direct
     input, setting it up for direct output will preserve the contents of the
     buffer.

RETURN VALUES
     All of these functions return DM_FAILURE if anything goes wrong, and
     DM_SUCCESS if successful.  In the case of failure, error information can
     be obtained from dmGetError(3dm).


EXAMPLE
     This example stores an image in a buffer, processes it through an image
     filter, and the retrieves the result:

         DMplugin* filter = ...;
         DMfxbuffer* inputBuffer  = ...;
         DMfxbuffer* outputBuffer = ...;
         PRX_ScanlineBuffer sbuf;

         /* Store a black image in the first buffer.  (It's */
         /* being used here as an output buffer to store */
         /* the original image.) */
         if ( dmFXSetupOutputImageBuffer( inputBuffer,
              bufOutputDirect, pmGetSourceAUsage( filter ) )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( dmFXSetupScanlineBuffer( inputBuffer, &sbuf )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         /* ... store the image.  At this point, sbuf.data */
         /* holds a pointer to the image buffer. */
         if ( dmFXCleanupOutputImageBuffer( inputBuffer )n
              != DM_SUCCESS )
         {
              /* ... handle error */
         }

         /* Execute the plug-in. */
         if ( dmFXSetupInputImageBuffer( inputBuffer )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( dmFXSetupOutputImageBuffer( outputBuffer,
              pmGetDestUsage(filter), bufInputDirect )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( pmBufferExecuteVideoFilter( filter,
              inputBuffer, outputBuffer, 0, 1 )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( dmFXCleanupInputImageBuffer( inputBuffer )n
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( dmFXCleanupOutputImageBuffer( outputBuffer )n
              != DM_SUCCESS )
         {
              /* ... handle error */
         }

         /* Now we want to get the image */
         if ( dmFXSetupInputImageBuffer( outputBuffer )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         if ( dmFXSetupScanlineBuffer( outputBuffer, &sbuf )
              != DM_SUCCESS )
         {
              /* ... handle error */
         }
         /* ... read the image.  At this point, sbuf.data */
         /* holds a pointer to the image buffer. */
         if ( dmFXCleanupInputImageBuffer( outputBuffer )n
              != DM_SUCCESS )
         {
              /* ... handle error */
         }


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