dmFXDrawPixels(3dm)

NAME
     dmFXDrawPixels, dmFXConvolve, dmFXScaleBias, dmFXMatrixMultiply - pixel
     transfer operations for special effects


SYNOPSIS
     #include <dmedia/fx_buffer.h>

     DMstatus dmFXDrawPixels
           ( PRX_ScanlineBuffer destination,
             int xPosition,
             int yPosition,
             PRX_ScanlineBuffer source,
             int xOffset,
             int yOffset,
             int width,
             int height )

     DMstatus dmFXConvolve
           ( PRX_ScanlineBuffer destination,
             PRX_ScanlineBuffer source,
             int matrixWidth,
             int matrixHeight,
             const GLfloat* matrix,
             const GLfloat bias,
             const GLfloat scale )

     DMstatus dmFXScaleBias
           ( 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
           ( PRX_ScanlineBuffer destination,
             PRX_ScanlineBuffer source,
             const GLfloat* matrix,
             const GLfloat bias,
             const GLfloat scale )


PARAMETERS
     These two parameters are common to all of these functions.  The other
     parameters are described below in the sections on the different
     functions.

     destination   The image buffer into which pixels are copied.


     source        The image buffer from which pixels are copied.


DESCRIPTION
     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 top-to-bottom in memory,
     instead of the usual OpenGL bottom-to-top 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 lower-left, and (width,height) at the upper-right.

     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 lower-left 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 lower-
     left 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:
         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.


PIXEL ZOOM
     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
     lower-left corner and (width,height) at the upper-right 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 full-sized image at (0,0) will exactly fill
     the render area with the image.  If (0,0) is at the upper-left of the
     viewport, then the Y pixel zoom should be negative.


     During preview, applications may be rendering the results of plug-ins
     directly to the screen, and may not be rendering full-size.  This is
     allowed as long as the pixel zoom is set to meet the above criteria.


     IMPORTANT: It is highly recommended that plug-in authors use these
     functions whenever doing pixel-oriented operations, because they
     correctly handle drawing images upside-down and they correctly handle
     pixel zoom.


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