dmFXDrawPixels(3dm) dmFXDrawPixels(3dm)
dmFXDrawPixels, dmFXConvolve, dmFXScaleBias, dmFXMatrixMultiply  pixel
transfer operations for special effects
#include <dmedia/fx_buffer.h>
DMstatus dmFXDrawPixels [Toc] [Back]
( PRX_ScanlineBuffer destination,
int xPosition,
int yPosition,
PRX_ScanlineBuffer source,
int xOffset,
int yOffset,
int width,
int height )
DMstatus dmFXConvolve [Toc] [Back]
( PRX_ScanlineBuffer destination,
PRX_ScanlineBuffer source,
int matrixWidth,
int matrixHeight,
const GLfloat* matrix,
const GLfloat bias,
const GLfloat scale )
DMstatus dmFXScaleBias [Toc] [Back]
( PRX_ScanlineBuffer destination,
PRX_ScanlineBuffer source,
const GLfloat redScale,
const GLfloat redBias,
const GLfloat greenScale,
const GLfloat greenBias,
const GLfloat blueScale,
const GLfloat blueBias,
const GLfloat alphaScale,
const GLfloat alphaBias )
DMstatus dmFXMatrixMultiply [Toc] [Back]
( PRX_ScanlineBuffer destination,
PRX_ScanlineBuffer source,
const GLfloat* matrix,
const GLfloat bias,
const GLfloat scale )
These two parameters are common to all of these functions. The other
parameters are described below in the sections on the different
functions.
Page 1
dmFXDrawPixels(3dm) dmFXDrawPixels(3dm)
destination The image buffer into which pixels are copied.
source The image buffer from which pixels are copied.
All of these functions copy pixels from one image buffer to another.
They make it easy to do common image processing operations without having
to set up all of the proper OpenGL state. They also correctly compensate
for the fact that video images are stored toptobottom in memory,
instead of the usual OpenGL bottomtotop orientation.
All these routines assume that the destination buffer has the standard
coordinate system that is set up by dmFXSetupOutputImageBuffer, with
(0,0) at the lowerleft, and (width,height) at the upperright.
The values of GL_UNPACK_ROW_LENGTH, GL_UNPACK_SKIP_ROWS,
GL_UNPACK_SKIP_PIXELS, and GL_UNPACK_ALIGNMENT may all be changed by
these functions.
dmFXDrawPixels copies a rectangular block of pixels from the source to
the destination, unmodified. xPosition and yPosition are the coordinates
of the lowerleft corner of the rectangle in the destination where the
pixel will be placed. Any rectangular portion of the source buffer can be
copied. The rectangle is specified by xOffset and yOffset (the lowerleft
corner), and width and height.
dmFXConvolve copies the entire source buffer to the destination, applying
an arbitrary 2D convolution matrix, matrix. The size of the matrix is
specified by matrixWidth and matrixHeight, and matrix points to a 2
dimensional array of coefficients indexed with coordinates i,j such that
i increases from left to right and j increases from bottom to top. The
same convolution matrix is applied equally to the R, G, B, and A
components of each pixel. After each component of each pixel is computed
(by the matrix multiplication), it is multiplied by scale and offset by
bias. The resulting pixel values are clamped to the range from 0.0 to
1.0. If the matrix size given exceeds the maximum allowed by OpenGL,
DM_FAILURE is returned, and the error code is set to
FX_ERROR_CONV_KERNEL_SIZE.
dmFXScaleBias copies the entire source buffer to the destination,
applying a color correction. Each component of each pixel is multiplied
by a scale (redScale, greenScale, blueScale, or alphaScale) and the
offset by a bias (redBias, greenBias, blueBias, or alphaBias). The
resulting values are clamped to the range from 0.0 to 1.0.
dmFXMatrixMultiply performs a more general color correction than
dmFXScaleBias. The four components of each pixel are treated as a 4
element vector and multiplied by a 4x4 matrix (matrix) to produce new
values for the four components, then the resulting components are each
multiplied by scale and offset by bias:
Page 2
dmFXDrawPixels(3dm) dmFXDrawPixels(3dm)
R' = ((m1 * R) + (m5 * G) + (m9 * B) + (m13 * A)) * Rscale + Rbias
G' = ((m2 * R) + (m6 * G) + (m10 * B) + (m14 * A)) * Gscale + Gbias
B' = ((m3 * R) + (m7 * G) + (m11 * B) + (m15 * A)) * Bscale + Bbias
A' = ((m4 * R) + (m8 * G) + (m12 * B) + (m16 * A)) * Ascale + Abias
Finally, each component is clamped to the range from 0.0 to 1.0.
The functions all assume that the modelview matrix has been set up so
that the coordinate system for the full output image has (0,0) at the
lowerleft corner and (width,height) at the upperright corner. They
also assume that the screen coordinates are the same. In other words,
they assume that the pixel zoom (see glPixelZoom) has been set so that
using glDrawPixels to draw a fullsized image at (0,0) will exactly fill
the render area with the image. If (0,0) is at the upperleft of the
viewport, then the Y pixel zoom should be negative.
During preview, applications may be rendering the results of plugins
directly to the screen, and may not be rendering fullsize. This is
allowed as long as the pixel zoom is set to meet the above criteria.
IMPORTANT: It is highly recommended that plugin authors use these
functions whenever doing pixeloriented operations, because they
correctly handle drawing images upsidedown and they correctly handle
pixel zoom.
dmFXSetupInputImageBuffer(3dm), dmFXSetupScanlineBuffer(3dm),
dmFXIsGLExtensionSupported(3dm), dmGetError(3dm).
PPPPaaaaggggeeee 3333 [ Back ]
