dmFXSetupInputImageBuffer(3dm) dmFXSetupInputImageBuffer(3dm)
dmFXSetupInputImageBuffer, dmFXSetupInputImageBufferWithUsage,
dmFXSetupOutputImageBuffer, dmFXCleanupInputImageBuffer,
dmFXCleanupOutputImageBuffer - manage special-effects image buffers
#include <dmedia/fx_buffer.h>
DMstatus dmFXSetupInputImageBuffer [Toc] [Back]
( DMfxbuffer* buffer )
DMstatus dmFXSetupInputImageBufferWithUsage [Toc] [Back]
( int inputUsage,
DMfxbuffer* buffer )
DMstatus dmFXSetupOutputImageBuffer [Toc] [Back]
( int outputUsage,
int inputUsage,
DMfxbuffer* buffer )
DMstatus dmFXCleanupInputImageBuffer [Toc] [Back]
( DMfxbuffer* buffer )
DMstatus dmFXCleanupOutputImageBuffer [Toc] [Back]
( DMfxbuffer* buffer )
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.
These functions are used to prepare buffers before calling an image
processing plugin, and clean up after calling a plugin.
Page 1
dmFXSetupInputImageBuffer(3dm) dmFXSetupInputImageBuffer(3dm)
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.
Page 2
dmFXSetupInputImageBuffer(3dm) dmFXSetupInputImageBuffer(3dm)
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).
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 )
Page 3
dmFXSetupInputImageBuffer(3dm) dmFXSetupInputImageBuffer(3dm)
{
/* ... 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 */
}
dmFXAllocateImageBuffers(3dm), dmFXMovieRenderImage(3dm),
dmFXSetupScanlineBuffer(3dm), dmGetError(3dm).
PPPPaaaaggggeeee 4444 [ Back ]
|
