*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> fx/fxSetupInputImageBuffer (3d)              


dmFXSetupInputImageBuffer(3dm)			dmFXSetupInputImageBuffer(3dm)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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	)

PARAMETERS    [Toc]    [Back]

     buffer	   a special-effects image buffer, allocated with

     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    [Toc]    [Back]

     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

     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

     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

     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

									Page 2

dmFXSetupInputImageBuffer(3dm)			dmFXSetupInputImageBuffer(3dm)

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

     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 */

SEE ALSO    [Toc]    [Back]

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

									PPPPaaaaggggeeee 4444
[ Back ]
 Similar pages
Name OS Title
fxAllocateImageBuffers IRIX create and destroy image buffers for special effects
fxSetupScanlineBuffer IRIX get information about a special-effects image buffer
dmFXTexImage2D IRIX load an image for use as a texture for special effects
dmPMCreateEffect IRIX create and destroy special effects
dmPMProcessClip IRIX apply special effects to movies
dmFXDrawPixels IRIX pixel transfer operations for special effects
dmPMGetPlugin IRIX retrieve a pointer to a special effects plugin
fxMovieRenderImage IRIX transfer images between movies and special effects
dmFXUpdateImageBuffer IRIX change the active size of a special effects buffer
securelevel OpenBSD securelevel and its effects
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service