source: svn/trunk/newcon3bcm2_21bu/magnum/portinginterface/grc/7552/bgrc.h

/***************************************************************************
 *     Copyright (c) 2003-2012, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: bgrc.h $
 * $brcm_Revision: Hydra_Software_Devel/67 $
 * $brcm_Date: 2/16/12 3:40p $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: /magnum/portinginterface/grc/7405/bgrc.h $
 * 
 * Hydra_Software_Devel/67   2/16/12 3:40p nissen
 * SW7405-5427: Adding flags for output mirroring when blitting
 * 
 * Hydra_Software_Devel/66   4/20/11 1:31p nissen
 * SW7630-104: Added support for A8_Y8 format and big endian 420
 * conversion.
 * 
 * Hydra_Software_Devel/65   11/19/09 2:53p nissen
 * SW7405-3429: Changed KeyMatrixScale order default to
 * KeyThenScaleThenMatrix.
 * 
 * Hydra_Software_Devel/64   4/17/09 4:41p nissen
 * PR 51077: Added callbacks to wait functions.
 * 
 * Hydra_Software_Devel/63   3/20/09 4:31p nissen
 * PR 51077: Added functions to wait on operations, and better handling
 * for running out of memory.
 * 
 * Hydra_Software_Devel/62   3/17/09 3:00p nissen
 * PR 52321: Added functions for enabling Alpha Premultiply.
 * 
 * Hydra_Software_Devel/61   9/23/08 1:57p nissen
 * PR 46638: Increased max operation define.
 * 
 * Hydra_Software_Devel/60   9/8/08 9:35p nissen
 * PR 46638: Increased packet memory size max.
 * 
 * Hydra_Software_Devel/59   2/7/08 12:43p nissen
 * PR 24618: Added sharper anti-flutter filter coefficient table.
 * 
 * Hydra_Software_Devel/58   12/17/07 10:03a nissen
 * PR 38269: Added support for inverting sources during a blit.
 * 
 * Hydra_Software_Devel/57   11/16/07 3:14p nissen
 * PR 36759: Added support for setting the scale factor independently of
 * the provided rectangle sizes.
 * 
 * Hydra_Software_Devel/56   8/20/07 2:15p nissen
 * PR 34132: Added support for setting a linear 420 source.
 * 
 * Hydra_Software_Devel/55   6/18/07 11:49a nissen
 * PR 32140: Added support for setting scale, color key, and color matrix
 * order.
 * 
 * Hydra_Software_Devel/54   5/2/07 11:40a nissen
 * PR 29724: Added support for 7405 A0 including new MacroBlock strip
 * width setting.
 * 
 * Hydra_Software_Devel/53   10/25/06 9:45a nissen
 * PR 24648: Added formula for range remapping to comments.
 * 
 * Hydra_Software_Devel/52   10/19/06 10:57a nissen
 * PR 24647: Added support for preallocting all device memory when module
 * is opened.
 * 
 * Hydra_Software_Devel/51   10/5/06 2:01p nissen
 * PR 24648: Added support for VC-1 macro block range remapping and
 * expansion for 7401 C0 and 7118.
 * 
 * Hydra_Software_Devel/50   9/29/06 10:06a nissen
 * PR 24618: Added support for second blurryer anti-flutter filter
 * coefficient table.
 * 
 * Hydra_Software_Devel/49   5/30/06 10:48a nissen
 * PR 21878: Added support for setting the operation time out interval
 * with settings structure when opening module.
 * 
 * Hydra_Software_Devel/48   5/8/06 1:48p nissen
 * PR 21399: Added BGRC_OperationsComplete function that will read the
 * M2MC registers to determine if all pending operations are complete.
 * 
 * Hydra_Software_Devel/47   2/21/06 12:05p nissen
 * PR 19084: Added support for second m2mc device.
 * 
 * Hydra_Software_Devel/46   11/7/05 10:11a nissen
 * PR 17518: Removed offset adjust and clut scale functions for 7401.
 * 
 * Hydra_Software_Devel/45   10/26/05 1:50p nissen
 * PR 17518: Added new entry point functions for 7401 scaling parameters.
 * Added code to return error if not using Sharp filtering while scaling
 * for 7401.
 * 
 * Hydra_Software_Devel/44   9/13/05 4:33p nissen
 * PR 16499: Added code to free memory past a default or specified
 * threshold.
 * 
 * Hydra_Software_Devel/43   5/12/05 4:38p nissen
 * PR 15264: Modified support for user defined phase adjustment when
 * filtering.
 * 
 * Hydra_Software_Devel/42   5/12/05 2:49p nissen
 * PR 15264: Added support for user defined phase adjustment when
 * filtering.
 * 
 * Hydra_Software_Devel/41   12/16/04 12:46p nissen
 * PR 13484: Add comments about bit location of constant color value for
 * sub-byte formats.
 * 
 * Hydra_Software_Devel/40   12/13/04 2:16p nissen
 * PR 13488: Added support for M2MC C0.
 * 
 * Hydra_Software_Devel/39   9/24/04 2:29p nissen
 * PR 12728: Removed commas at the end of enums for pedantic errors.
 * 
 * Hydra_Software_Devel/38   9/24/04 2:20p nissen
 * PR 12697: Fixed comment.
 * 
 * Hydra_Software_Devel/37   9/23/04 2:19p nissen
 * PR 12729: Added anti-flutter filter to filter coefficient enums.
 * 
 * Hydra_Software_Devel/36   4/9/04 4:14p nissen
 * PR 10394: Added filter coefficient enum descriptions.
 * 
 * Hydra_Software_Devel/35   3/12/04 2:25p nissen
 * PR 10024: Added include for error header file.
 * 
 * Hydra_Software_Devel/34   2/17/04 4:20p nissen
 * PR 9719: Added sharper to filter coefficient enums.
 * 
 * Hydra_Software_Devel/33   2/17/04 3:57p jasonh
 * PR 9726: Added documentation for real-time vs. non real time, color
 * key, and dithering.
 * 
 * Hydra_Software_Devel/32   2/10/04 11:15a nissen
 * PR 9700: Added blurry to filter coefficient enums.
 * 
 * Hydra_Software_Devel/31   1/21/04 1:54p nissen
 * PR 9432: Updated comments.
 * 
 * Hydra_Software_Devel/30   11/21/03 6:39p nissen
 * Fixed problem with callback function pointer.
 * 
 * Hydra_Software_Devel/29   11/20/03 6:59p nissen
 * Added support for interrupts.
 * 
 * Hydra_Software_Devel/28   9/29/03 1:26p nissen
 * Modified Close function to return void.
 * 
 * Hydra_Software_Devel/27   9/23/03 5:42p jasonh
 * Fixed documentation for some arguments.
 * 
 * Hydra_Software_Devel/26   9/10/03 9:14a jasonh
 * Fixed documentation headers in module overview.
 * 
 * Hydra_Software_Devel/25   9/5/03 12:52p jasonh
 * Updated overview documentation.
 * 
 * Hydra_Software_Devel/24   8/21/03 1:31p nissen
 * Rearranged function definition order.
 * 
 * Hydra_Software_Devel/23   8/19/03 10:16a nissen
 * Removed functions that set component sizes.
 * 
 * Hydra_Software_Devel/22   8/14/03 4:48p jasonh
 * Changed SetPaletteBypass to ToggleFilterBypass.
 * 
 * Hydra_Software_Devel/21   8/14/03 4:37p jasonh
 * API review changes. Change AMNO->AC2C1C0. Added ToggleFilter. Broke out
 * enable/disable of colorkey/matrix and state setting into different
 * functions. Added ResetState and SetDefault functions.
 * 
 * Hydra_Software_Devel/20   8/12/03 11:32a nissen
 * Added more scale coeffs enums. Added dither function definition.
 * 
 * Hydra_Software_Devel/19   8/6/03 2:32p nissen
 * Updated test plan. Added function definitions.
 * 
 * Hydra_Software_Devel/18   6/25/03 11:56a nissen
 * Added exclusive parameter to color key entry points.
 * 
 * Hydra_Software_Devel/17   6/5/03 11:48a nissen
 * Updated test plan.
 * 
 * Hydra_Software_Devel/16   5/29/03 10:05a nissen
 * Update comments.
 * 
 * Hydra_Software_Devel/15   5/28/03 6:26p nissen
 * Updated test plan.
 * 
 * Hydra_Software_Devel/14   5/28/03 4:55p nissen
 * Fixing comments.
 * 
 * Hydra_Software_Devel/13   5/22/03 10:36a nissen
 * Adjusted test plan.
 * 
 * Hydra_Software_Devel/12   5/21/03 2:24p nissen
 * Added dates to test plan.
 * 
 * Hydra_Software_Devel/11   5/21/03 2:11p nissen
 * Added test plan comments.
 * 
 * Hydra_Software_Devel/10   4/25/03 3:45p nissen
 * Fixed use of surface handle.
 * 
 * Hydra_Software_Devel/9   4/24/03 6:15p nissen
 * Updated feature set.
 * 
 * Hydra_Software_Devel/8   4/18/03 1:41p nissen
 * Fixed feature set documentation.
 * 
 * Hydra_Software_Devel/7   4/16/03 12:44p nissen
 * Added some feature set documentation.
 * 
 * Hydra_Software_Devel/6   4/10/03 6:04p jasonh
 * General cleanup.
 * 
 * Hydra_Software_Devel/5   4/10/03 6:03p jasonh
 * Added changes from last code review. Added description of sub-apis.
 * Fixed scaling to use rectangles and not scale factors. Removed inverse
 * control from blending. Added state function calls. Fixed alpha/main
 * surface description. Added chroma expansion functions. Added palette
 * bypass functions. Removed horizontal/vertical scaler controls. Added
 * better description for matrix, color keying, blending, and color
 * selection. Added better description of AC2C1C0 channels. Changed ROP to
 * blending sub-api.
 * 
 * Hydra_Software_Devel/4   3/25/03 2:42p jasonh
 * Pre-code review updates.
 * 
 * Hydra_Software_Devel/3   3/3/03 4:11p jasonh
 * Added ROP and blending documentation.
 * 
 * Hydra_Software_Devel/2   3/3/03 4:05p jasonh
 * Flushed out more documentation issues.
 *
 ***************************************************************************/

#ifndef BGRC_H__
#define BGRC_H__

#include "bchp.h"
#include "bmem.h"
#include "bsur.h"
#include "bint.h"
#include "breg_mem.h"
#include "bgrc_errors.h"

#ifdef __cplusplus
extern "C" {
#endif

/*=Module Overview: ********************************************************
The purpose of this module is to take surfaces allocated by the surface
module, composite the pixels together, and create new pixels for another
surface. The resulting surface (frame buffer) can then be displayed by
providing it to the Video Display Control module, or it can be used in
another graphics compositor operation to create another result.

Non Real-Time Client
--------------------

Each operation of the compositor may take several fields to compute
and the same operation may take more or less time each time it is
computed. The compositor is referred to as a "non real-time client" since 
its operations are not guaranteed to finish within a certain amount of
time.

The reasons for using this approach are:

o The entire graphics operation can be computed once and stored in a frame
  buffer. Other real-time graphics engines that do not use frame buffers
  have to re-compute the results of graphics and contually consume bandwidth
  in order to compute the same result.

o Since we are allowed to take several frames to compute a frame buffer, the
  complexity of the operation is no longer constrained by the available
  bandwidth of one field. We can now implement programmable blenders, 
  high-resolution scaling in both X and Y, and anti-flutter filters for HD 
  resolution graphics without reducing the real-time capabilities of
  the chipset.

o The number of source surfaces used to create the frame buffer is not
  limited. Typical real-time graphics engines have limits on how many 
  surfaces they support per line and how many may overlap on a given pixel.

o Complex graphics operations do not effect the video display. Whatever
  bandwidth is remaining after the other chipset operations will be used to
  compute the graphics. In real-time graphics, if you pushed the capabilities
  of the graphics engine, you could affect the actual display and other
  real-time clients by reducing their available bandwidth.

The disadvantages to this approach are:

o User must allocate a frame buffer to store the computed frame buffer.
  In order to prevent tearing and similar issues, the user 
  will need to implement double-buffering or a similar mechanism.

o When the user changes an original source surface, the user must
  re-compute the frame buffer which used that source surface. Graphics
  engines that don't use frame buffers don't have this problem since 
  they are continually updating the display allowing them to automatically
  update when a change to a source surface is made.

Color Channels
--------------

The graphics compositor does not work in one specific color space, such as
YCbCr or RGB space, but operates in a generic color space that the user
defines. This arbitrary color space has one alpha channel, always referred
to as A, and three color channels, referred to as C2, C1, and C0.

Once the user understands the rules for converting input pixels into
(A,C2,C1,C0) space, and understands the steps taken from input to output, 
this generic color space will allow the user to define the color space at
many of the stages in the pipeline. Literally the user can have a color
space for the input data, a second color space for blending, and a third
color space for the output. They could also just use one color space for
the entire pipeline. 

The rules for translation are as follows. When constant values are provided,
such as when supplying color key ranges, matrix coefficients, and constant
color values, they are always provided as (A,C2,C1,C0) values. These values
are passed directly to hardare for use in the pipeline. When pixels
are translated from input surfaces, alpha and color channels use the
following rules that operate according to the surface's format:

o If the pixels contain an alpha value, the alpha channel (A) will contain
  the pixel value. If it doesn't, the constant alpha value will be used.
o If the pixels contain color information, the color channels (C2,C1,C0)
  will be assigned colors from that pixel. If using YCrCb colors then
  C2=Y, C1=Cb, C0=Cr. If using RGB colors then C2=R, C1=G, C0=B. If the
  pixels do not contain color information the constant color channel values
  will be used.
o If the surface references a palette, the above rules are applied on the
  palette entries according to the format of the palette. If the pixels
  also contain other values, such as an alpha in addition to a palette index,
  then those values will replace any entries within the palette before
  conversion. The user may override derefrencing of the palette and use
  the index value directly. In that case, C0 will contain the palette index
  while the other two color channels will contain zero.
o If the surface uses a compressed format, such as BPXL_eY08_Cb8_Y18_Cr8,
  the values will be uncompressed using user specified chroma expansion
  rules before using the above rules t convert into (A,C2,C1,C0) values.
o After conversion, all color channels will be internally stored as 8-bit
  values. When used in equations, such as the blending equation, those
  8-bit values are treated as if that range yielded values from 0 to 1
  (inclusive).

The same rules are used in reverse to store color channels in the output.

In all of the above cases, when an input pixel value contains less than
8 bits, the value will be converted to an 8-bit value by replicating the
high order bits. For example, if you have a 5-bit binary value of 01101,
the resulting 8-bit expanded value will be 01101011. This rule applies
for the alpha (A) channel as well as the color channels (C2,C1,C0).

Color conversion example
------------------------

BPXL_eR5_G6_B5        - Alpha (A) from constant. C2=R, C1=G, and C0=B.
BPXL_eB5_G5_R5_A1     - Alpha (A) from pixel. C2=R, C1=G, and C0=B.
BPXL_eA8              - Alpha (A) from pixel. C2, C1, and C0 from constant.
BPXL_eY08_Cb8_Y18_Cr8 - Alpha (A) from constant for both pixels. C2=Y0 for
first pixel. C2=Y1 for second pixel. C1=converted Cr and C0=converted Cb
for both pixels.

Data Flow
---------

The process and the routing of the alpha and color channels can be seen in
the following diagram. The diagram shows the main process as well as showing
what state each of the blocks control. The five blocks of the graphics 
compositor process are named source, destination, blend, pattern, and output.

{image:graphicscompositor overview}

Main Surface and Alpha Surface
------------------------------

You will notice that for both the Source and Destination blocks, two surfaces
can be provided for each block. One of these surfaces is the main surface,
simply referred to as "Surface". The other surface is the "Alpha Surface". 
In general, most users will only be using main surface. This surface supports
any of the standard pixel formats. The only time where the alpha surface is
being used is in one very specific case. The main surface must have a format
of BPXL_R5_G6_B5 and the alpha surface must have a format of BPXL_A1 or BPXL_W1.
These two surfaces combined will describe a 17-bit format where the color
channel information will come from the main surface and the alpha information
will come from the alpha surface.

Color Keying
------------

In addition to the four color channel values stored for each pixel, there is
one additional bit of information. This is the color key bit which is set in the 
color keying state in the source and destination blocks. The operation to set
this bit is enabled with BGRC_Source_ToggleColorKey and
BGRC_Destination_ToggleColorKey. The parameters for the color key are set
with calls to BGRC_Source_SetColorKey and BGRC_Source_SetColorKey.

The parameters that you can set allow you to define a min/max range of the color
key, and a mask which can be used to mask out the value of the input pixel
before the comparison is made. If the pixel passes the color key test, the 
color key bit for that pixel is marked and if any bit in the replacement mask
is set, the corresponding bit in the replacement color is used to replace the 
input color.

The additional color key bit is used later on in the output block in the
procedure defined by the BGRC_Output_SetColorKeySelection. This section determines
which pixel will be the final result by looking at the color key bit for 
the source and destination. Depending on those four possible combinations,
the final pixel can come from the source block, the destination block, the
blend block, or the pattern block.

Color keying is typically used when a specific color value in the source needs
to be replaced by the corresponding pixel in the destination. To get this
effect, set the source color key min, max, and mask to appropriate values.
Remember that if your mask contains zeros, you must adjust your min and max
ranges to allow a match when those input bits are masked. In addition to the
source color key parameters you must also tell the output
color key selection to choose the pixel from the destination when the source
color key is on. With this final setting you will be able to get source color
keying working.

In this typical case, there is no real need to specify a replacement color
and replacement mask since the purpose here is to replace the pixel with one
from the destination and not replace it with a constant color. 

One real tricky case with color keying is when you're combining it with
scaling. The issue is centered around the additional color key bit. This bit
along with the corresponding four color channels is fed into the scaler.
The scaler must then produce four new color channel values as well as a new
color key bit. The color key bit will be set only if all the contributors to
that pixel have the color key bit set. The issue this causes can be seen by
noticing that if half the pixels entering the scaler are color keyed and
the rest are not, the result will be marked as not color keyed even though
the color key color was used by the scaler. This will mean that the color
used for the color key can be spread outside the color key range and those
pixels will not be marked as color keyed.

There are several ways to lessen the impact of this problem. You can use
the replacement mask and replacement color to replace the input color key with
a color like black that doesn't stand out when filtered with neighboring
pixels. If you need to re-introduce this color after the scaler, like if
you're planning to use it in a color key operation in the display, you can do
so by providing the color key value as the destination constant color and using
the output selection to choose the destination color when source color keying
is enabled.

Another way to lessen the impact is to choose different filter coefficients 
for the scaler with a call to BGRC_Source_SetFilterCoeffs. This can be used
to lessen the spread of the color key value outside of the color key area.

Source Block
------------

The source block is responsible for defining the one of the main inputs to
the compositor. In a typical situation where a graphic surface is being
composited into a frame buffer surface, the source block represents the
graphic surface and not the frame buffer.

The functions used to define the source block are the following:

o Surface: BGRC_Source_SetSurface,
  BGRC_Source_SetRectangle
o Alpha Surface: BGRC_Source_SetRectangle,
  BGRC_Source_SetAlphaSurface
o Constant Color: BGRC_Source_SetColor
o Chroma Expansion: BGRC_Source_SetChromaExpansion
o Palette Dereference: BGRC_Source_TogglePaletteBypass
o Per-pixel (A,C2,C1,C0) value: BGRC_Source_SetZeroPad
o Color Keying and Color Matrix operation: BGRC_Source_SetColorKey,
  BGRC_Source_ToggleColorMatrix, BGRC_Source_ToggleColorKey,
  BGRC_Source_SetColorMatrix5x4,
  BGRC_Source_SetColorMatrixRounding,
  BGRC_Source_SetKeyMatrixOrder
o Scaling: BGRC_Source_SetScaleAlphaAdjust,
  BGRC_Source_SetFilterCoeffs, BGRC_Source_SetScaleRounding,
  BGRC_Source_SetScaleEdgeCondition
o General: BGRC_Source_SetDefault, BGRC_Source_Reset

Destination Block
-----------------

The destination block is responsible for defining the one of the main
inputs to the compositor. In a typical situation where a graphic surface
is being composited into a frame buffer surface, the destination block
represents the frame buffer and not the graphic surface.

In general, all the capabilities of the source block are found in the
destination block. The only exception to this is that you cannot
scale an input specified as a destination.

The functions used to define the destination block are the following:

o Surface: BGRC_Destination_SetSurface,
  BGRC_Destination_SetRectangle
o Alpha Surface: BGRC_Destination_SetRectangle,
  BGRC_Destination_SetAlphaSurface
o Constant Color: BGRC_Destination_SetColor
o Chroma Expansion: BGRC_Destination_SetChromaExpansion
o Palette Dereference: BGRC_Destination_TogglePaletteBypass
o Per-pixel (A,C2,C1,C0) value: BGRC_Destination_SetZeroPad
o Color Keying and Color Matrix operation: BGRC_Destination_SetColorKey,
  BGRC_Destination_ToggleColorMatrix, BGRC_Destination_ToggleColorKey,
  BGRC_Destination_SetColorMatrix5x4,
  BGRC_Destination_SetColorMatrixRounding,
  BGRC_Destination_SetKeyMatrixOrder
o General: BGRC_Destination_SetDefault, BGRC_Destination_Reset

Blend Block
-----------

The purpose of the blend block is to blend the results from the source
block with the results from the destination block and provide that value
as an input the output block. 

The functions used to define the blend block are the following:

o Constant Color: BGRC_Blend_SetColor
o Color and Alpha Blending Operations: BGRC_Blend_SetAlphaBlend,
  BGRC_Blend_SetColorBlend
o General: BGRC_Blend_SetDefault, BGRC_Blend_Reset

Pattern Block
-------------

The purpose of the pattern block is to provide pattern operations using
the results from the source block and the destination block and provide
that value as an input the output block. 

The functions used to define the pattern block are the following:

o Pattern Operation: BGRC_Pattern_Set
o General: BGRC_Pattern_SetDefault, BGRC_Pattern_Reset

Output Block
------------

Results from the other four blocks are provided as inputs to this block.
The purpose of this block is to choose which inputs to use as the final
result, to convert the (A,C2,C1,C0) value into the final color space,
and to specify where the output should be stored.

The functions used to define the output block are the following:

o Output Selection: BGRC_Output_SetColorKeySelection
o Color Matrix: BGRC_Output_SetColorMatrixRounding
o Dither: BGRC_Output_SetDither 
o Surface: BGRC_Output_SetRectangle,
  BGRC_Output_SetSurface
o Alpha Surface: BGRC_Output_SetAlphaSurface, 
  BGRC_Output_SetRectangle
o General: BGRC_Output_SetDefault, BGRC_Output_Reset

Usage
-----

o User creates handle using BGRC_Open.
o User sets state using the source, destination, blend, pattern,
  and output blocks.
o User issues the state using BGRC_IssueState or
  BGRC_IssueStateAndWait.

It is important to note that until the operation is completed, the user should 
not modify any input pixels or input palettes. Doing so will result in an 
undefined result.

Test Plan
---------

        (I) - Test implemented.
        (F) - Test failed.
        (P) - Test passed.
        (?) - Questions about implementation.

        * Feeders: Responsible for fetching graphics data from a specified format.
                * Format Definition: Describes input and output pixel formats.
                        * (P) Blit RGB formats to RGB formats.
                        * (P) Blit YCrCb formats to YCrCb formats.
                        * (F) Blit Alpha formats to Alpha formats.
                        * (F) Blit Alpha formats to RGB formats.
                        * (F) Blit Alpha formats to YCrCb formats.
                        * (F) Blit RGB formats to Alpha formats.
                        * (F) Blit YCrCb formats to Alpha formats.
                * Palette: Use fetched pixel as an index into color lookup table.
                        * (P) Blit Palette formats to same Palette formats bypassing table lookup.
                        * (P) Blit Palette formats to RGB formats with table lookup.
                        * (P) Blit Palette formats to YCrCb formats with table lookup.
                * YCrCb Filtering: Expands chroma values using filtering.
                        * (F) Blit YCrCb422 to AYCrCb444 with filtering.
                * Blit Direction: Feeders can fetch data in any direction.
                        * (P) Blit RGB format from top-to-bottom and left-to-right.
                        * (P) Blit RGB format from bottom-to-top and left-to-right.
                        * (P) Blit RGB format from top-to-bottom and right-to-left.
                        * (P) Blit RGB format from bottom-to-top and right-to-left.
                * Constant Pixel: Replaces fetched pixel from surface.
                        * (P) Blit constant pixel to RGB and YCrCb formats.

        * Color Key: Allows replacement of the pixels fetched by the feeder.
                * Single or Range
                        * (P) Blit RGB and YCrCb formats using single color key.
                        * (P) Blit RGB and YCrCb formats using ranged color key.

        * Color Matrix: Multiplies pixels fetched by the feeder with a matrix.
                * Color Conversion: Matrix can be used to convert to a new color space.
                        * (P) Blit RGB formats to YCrCb formats.
                        * (P) Blit YCrCb formats to RGB formats.

        * Blend: Blends pixels using formula with specified inputs.
                * Standard Blends: Several blends commonly supported by APIs.
                        * (P) Blit RGB and YCrCb formats using One/Zero blend.
                        * (P) Blit RGB and YCrCb formats using Zero/One blend.
                        * (P) Blit RGB and YCrCb formats using One/One blend.
                        * (P) Blit RGB and YCrCb formats using SrcAlpha/InvSrcAlpha blend.
                        * (P) Blit RGB and YCrCb formats using One/InvSrcAlpha blend.
                        * (P) Blit RGB and YCrCb formats using DstColor/One blend.

        * ROP: Logically combines input pixels.
                * Standard ROPs: Simple ROPs using source and destination.
                        * (P) Blit RGB and YCrCb formats using 'copy' ROP.
                        * (P) Blit RGB and YCrCb formats using 'and' ROP.
                        * (P) Blit RGB and YCrCb formats using 'or' ROP.
                        * (P) Blit RGB and YCrCb formats using 'xor' ROP.
                * Pattern ROPs: ROPs using pattern as a source.
                        * (P) Blit RGB and YCrCb formats using several pattern ROPs.

        * Scaler: Source surface can be scaled to output size.
                * Rounding Mode: Least significant bit handling.
                        * Blit RGB format using truncate rounding.
                        * Blit RGB format using nearest rounding.
                * Edge Condition: Filling of missing taps on edges.
                        * Blit RGB format using using replicate edge condition.
                        * Blit RGB format using using mirror edge condition.
                * Scaler Order: Determines order of horizontal and vertical scales.
                        * Blit RGB format using horizontal then vertical scale.
                        * Blit RGB format using vertical then horizontal scale.
                * Averagers and Filters: Produce filtered pixels during scale.
                        * Blit RGB format using horizontal averagers and filters.
                        * Blit RGB format using vertical averager.
                        * Blit RGB format using horizontal and vertical averagers and filters.

See Also:
        BGRC_Open,
        BSUR_Surface_Create
****************************************************************************/

/***************************************************************************
Summary:
        The handle for the graphics compositor module.

Description:
        This is the main handle required to do any operations within the 
        graphics compositor module.

See Also:
        BGRC_Open
****************************************************************************/
typedef struct BGRC_P_Handle *BGRC_Handle;

/***************************************************************************
Summary:
        Callback used for task completion.

Description:
        When a task is issued, this callback can be used to get notification
        when the task is completed.

See Also:
        BGRC_IssueState
****************************************************************************/
typedef BERR_Code (*BGRC_Callback)(BGRC_Handle hGrc, void *pData);

/***************************************************************************
Summary:
        Used to specify how values are rounded for the final result.

Description:

See Also:
        BGRC_Source_SetChromaExpansion,
        BGRC_Destination_SetChromaExpansion
****************************************************************************/
typedef enum BGRC_ChromaExpansion
{
        BGRC_ChromaExpansion_eReplicate,  /* Cr and Cb values are replicated */
        BGRC_ChromaExpansion_eFilter      /* Cr and Cb values are filtered */
} BGRC_ChromaExpansion;

/***************************************************************************
Summary:
        Used to specify how values are rounded for the final result.

Description:

See Also:
        BGRC_Source_SetColorMatrixRounding,
        BGRC_Destination_SetColorMatrixRounding,
        BGRC_Output_SetColorMatrixRounding,
        BGRC_Source_SetScaleRounding
****************************************************************************/
typedef enum BGRC_Rounding
{
        BGRC_Rounding_eTruncate,  /* Values are truncated */
        BGRC_Rounding_eNearest    /* Values are rounded to nearest */
} BGRC_Rounding;

/***************************************************************************
Summary:
        Used to determine whether color keying comes before or after the color
        matrix operation.

Description:

See Also:
        BGRC_Source_SetKeyMatrixOrder,
        BGRC_Destination_SetKeyMatrixOrder
****************************************************************************/
typedef enum BGRC_KeyMatrixOrder
{
        BGRC_KeyMatrixOrder_eKeyThenMatrix, /* Color keying operation
                                               comes before color matrix. */
        BGRC_KeyMatrixOrder_eMatrixThenKey  /* Color matrix operation
                                               comes before color keying. */
} BGRC_KeyMatrixOrder;

/***************************************************************************
Summary:
        Used to determine the order of color keying, color matrix, and scaling
        when processing pixels.

Description:

See Also:
        BGRC_Source_SetKeyMatrixScaleOrder,
****************************************************************************/
typedef enum BGRC_KeyMatrixScaleOrder
{
        BGRC_KeyMatrixScaleOrder_eScaleThenKeyThenMatrix, /* Scale-Key-Matrix */
        BGRC_KeyMatrixScaleOrder_eScaleThenMatrixThenKey, /* Scale-Matrix-Key */
        BGRC_KeyMatrixScaleOrder_eKeyThenMatrixThenScale, /* Key-Matrix-Scale */
        BGRC_KeyMatrixScaleOrder_eKeyThenScaleThenMatrix, /* Key-Scale-Matrix */
        BGRC_KeyMatrixScaleOrder_eMatrixThenScaleThenKey, /* Matrix-Scale-Key */
        BGRC_KeyMatrixScaleOrder_eMatrixThenKeyThenScale, /* Matrix-Key-Scale */
        BGRC_KeyMatrixScaleOrder_eBypassAll               /* None */
} BGRC_KeyMatrixScaleOrder;

/***************************************************************************
Summary:
        Specifies what coefficients to use for scaling.

        The following is a description of the filter types:

        Point Sample: Single closest pixel (1 tap) is used, resulting in 
        no filtering. Generates blocky up-scales, and down-scales with missing 
        pixel information.

        Bilinear: Closest pixel is filtered with its neighbor (2 taps) using 
        coefficients dervied from the pixel position. Generates slightly blurry 
        up-scales, and down-scales of less than a half will have missing pixel 
        information.

        Anisotropic: Closest pixel is area filtered with its neighbors 
        (up to 8 taps). This filter is the same as bilinear when up-scaling. 
        When down-scaling, the amount of taps used depends on the scale factor.

        Sharp: Closet pixel is area filtered with its neighbors using filter
        coefficents generated with a sin wave formula (all 8 taps). Each scale
        factor has its own table of filter coefficients up to a scale of 8 to 9.
        Up-scales larger than 8 to 9 use a 1 to N coefficent table. (Default)

        Sharper: Same as sharp, except when scaling larger than 8 to 9, a 
        sharper filter coefficent table is used.

        Blurry: Closest pixel is filtered with two closet neighbors (3 tap).
        Similar to bilinear except blurryer.

See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
typedef enum BGRC_FilterCoeffs
{
        BGRC_FilterCoeffs_ePointSample,      /* Point sampled filtering */
        BGRC_FilterCoeffs_eBilinear,         /* Bilinear filtering */
        BGRC_FilterCoeffs_eAnisotropic,      /* Anisotropic filtering */
        BGRC_FilterCoeffs_eSharp,            /* Tabled sin(x)/x filtering */
        BGRC_FilterCoeffs_eSharper,          /* Sharper upscale */
        BGRC_FilterCoeffs_eBlurry,           /* 3-point filtering */
        BGRC_FilterCoeffs_eAntiFlutter,      /* Anti-Flutter filtering */
        BGRC_FilterCoeffs_eAntiFlutterBlurry,/* Blurry Anti-Flutter filtering */
        BGRC_FilterCoeffs_eAntiFlutterSharp  /* Sharp Anti-Flutter filtering */
} BGRC_FilterCoeffs;

/***************************************************************************
Summary:
        Specifies what to do when an edge condition is reached.

Description:

See Also:
        BGRC_Source_SetScaleEdgeCondition
****************************************************************************/
typedef enum BGRC_EdgeCondition
{
        BGRC_EdgeCondition_eReplicateLast,  /* Last pixel is replicated */
        BGRC_EdgeCondition_eMirror          /* Mirrored along edge */
} BGRC_EdgeCondition;

/***************************************************************************
Summary:
        Specifies what source to use for each individual piece of the 
        blending equation.

Description:

See Also:
        BGRC_Blend_SetColorBlend,
        BGRC_Blend_SetAlphaBlend
****************************************************************************/
typedef enum BGRC_Blend_Source
{
        BGRC_Blend_Source_eZero,                    /* Zero */
        BGRC_Blend_Source_eHalf,                    /* 1/2 */
        BGRC_Blend_Source_eOne,                     /* One */
        BGRC_Blend_Source_eSourceColor,             /* Color from source */
        BGRC_Blend_Source_eInverseSourceColor,      /* 1-color from source */
        BGRC_Blend_Source_eSourceAlpha,             /* Alpha from source */
        BGRC_Blend_Source_eInverseSourceAlpha,      /* 1-alpha from source */
        BGRC_Blend_Source_eDestinationColor,        /* Color from destination */
        BGRC_Blend_Source_eInverseDestinationColor, /* 1-color from destination */
        BGRC_Blend_Source_eDestinationAlpha,        /* Alpha from destination */
        BGRC_Blend_Source_eInverseDestinationAlpha, /* 1-alpha from destination */
        BGRC_Blend_Source_eConstantColor,           /* Color from blend color */
        BGRC_Blend_Source_eInverseConstantColor,    /* 1-color from blend color */
        BGRC_Blend_Source_eConstantAlpha,           /* Alpha from blend color */
        BGRC_Blend_Source_eInverseConstantAlpha     /* 1-alpha from blend color */

} BGRC_Blend_Source;

/***************************************************************************
Summary:
        Used to determine what value to take depending on the color keying
        results.

Description:

See Also:
        BGRC_Output_SetColorKeySelection
****************************************************************************/
typedef enum BGRC_Output_ColorKeySelection
{
        BGRC_Output_ColorKeySelection_eTakeSource,       /* Take source pixel */
        BGRC_Output_ColorKeySelection_eTakeBlend,        /* Take blended pixel */
        BGRC_Output_ColorKeySelection_eTakeDestination,  /* Take destination pixel */
        BGRC_Output_ColorKeySelection_eTakePattern       /* Take pattern pixel */
} BGRC_Output_ColorKeySelection;

/***************************************************************************
Summary:
        Used to determine range type when using a YCbCr 420 source surface.

See Also:
        BGRC_Output_SetColorKeySelection
****************************************************************************/
typedef enum BGRC_MacroBlockRange
{
        BGRC_MacroBlockRange_None,       /* Disable */
        BGRC_MacroBlockRange_Expansion,  /* MacroBlock range expansion */
        BGRC_MacroBlockRange_Remapping   /* MacroBlock range remapping */
} BGRC_MacroBlockRange;

/***************************************************************************
Summary:
        This structure describes some initial settings when opening the
        graphics compositor.

Description:
        This structure is used to initialize some private settings within the
        driver. If this structure is not used when opening the driver, the 
        driver will use its own default settings.

        ulPacketMemoryMax - Maximum memory threshold for register set allocations 
                           that are placed in the M2MC operation queue. The 
                                           driver will allocate past this threshold but will 
                                           deallocte to the threshold when the memory becomes 
                                           idle. Setting this to 0 will allow for unlimited
                                           packet memory allocations. The default value is 
                                           BGRC_PACKET_MEMORY_MAX defined below.
        ulOperationMax    - Maximum amount of operation structures allowed to be
                           stored before deallocations begin. These structures 
                                           are used by the driver's interrupt handler to track
                                           M2MC operations. It will allocate past this threshold 
                                           but will deallocate to the threshold when the 
                                           structures become idle. Setting this to 0 will allow 
                                           for unlimited operation structure allocations. The 
                                           default value is BGRC_OPERATION_MAX defined below.
        ulDeviceNum      - M2MC Device number. 0 is default, and only 7400 and
                                           7438 can set this value to 0 or 1.
        ulWaitTimeout    - How many seconds to wait before the device times out,
                           and the driver assumes the device is hung. The default
                                           is 10 seconds.
        bPreAllocMemory  - Allocate all memory specified by ulPacketMemoryMax
                           when opening module. An error will be returned 
                       when memory is exceeded. Defaults to true.

See Also:
        BGRC_Open
****************************************************************************/
typedef struct BGRC_Settings
{
        uint32_t ulPacketMemoryMax;      /* max packet memory */
        uint32_t ulOperationMax;         /* max operations */
        uint32_t ulDeviceNum;            /* M2MC device number */
        uint32_t ulWaitTimeout;          /* seconds to wait before timing out */
        bool bPreAllocMemory;            /* allocate memory when opening module */
} BGRC_Settings;

#define BGRC_PACKET_MEMORY_MAX    131072
#define BGRC_OPERATION_MAX          2048
#define BGRC_WAIT_TIMEOUT             10

/***************************************************************************
Summary:
        Gets default settings.

Description:
        This function returns that default settings which can be modified
        when calling BGRC_Open. These settings are defined above.

Returns:
        BERR_SUCCESS - Default settings returned.

See Also:
        BGRC_Open
****************************************************************************/
BERR_Code BGRC_GetDefaultSettings(
        BGRC_Settings *pDefSettings 
);

/***************************************************************************
Summary:
        Opens the graphics compositor module.

Description:
        The module is opened and a graphics compositor module handle is
        created and returned. This handle will be necessary to perform any
        tasks in the graphics compositor module.

        Once opened, all state for each of the sub-modules will be reset as
        if a call to BGRC_ResetState was made.

Returns:
        BERR_SUCCESS - Module was opened and valid handle was returned.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Close
****************************************************************************/
BERR_Code BGRC_Open( 
        BGRC_Handle *phGrc,                /* [out] Pointer to returned GRC
                                              handle. */
        BCHP_Handle hChip,                 /* [in] Chip handle. */
        BREG_Handle hRegister,             /* [in] Register access handle. */
        BMEM_Handle hMemory,               /* [in] Memory allocation handle. */
        BINT_Handle hInterrupt,            /* [in] Interrupt handle. */
        const BGRC_Settings *pDefSettings  /* [in] Pointer to initial settings. */
);

/***************************************************************************
Summary:
        Closes the graphics compositor module.

Description:
        Once this function is called no more graphics compositor module
        functions can be used. 

        Outstanding tasks may be interrupted without callbacks being
        called.

See Also:
        BGRC_Open
****************************************************************************/
void BGRC_Close(
        BGRC_Handle hGrc                   /* [in] GRC module handle to close. */
);

/***************************************************************************
Summary:
        Resets all state back to default values.

Description:
        This call does not make any changes in hardware, nor does it
        effect any outstanding operations.

        This is implemented by calling reset functions for source,
        destination, blend, pattern, and output.

Returns:
        BERR_SUCCESS - Module state was successfully reset.

See Also:
        BGRC_Open,
        BGRC_Source_ResetState,
        BGRC_Destination_ResetState,
        BGRC_Blend_ResetState,
        BGRC_Pattern_ResetState,
        BGRC_Output_ResetState
****************************************************************************/
BERR_Code BGRC_ResetState(
        BGRC_Handle hGrc                   /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Issues state to hardware.

Description:
        When this call is made, all the state specified in the source,
        destination, blend, pattern, and output blocks will be 
        checked to make sure it is valid. If it is valid, it will be
        combined together to form one task which will then be issued
        to hardware.

    Hardware will work on this task asyncronously. The user has
        the option of waiting for the task to complete by using the function
        BGRC_IssueStateAndWait, having the module call a callback function
        when complete using BGRC_IssueState, or not be notified when
        this task is complete.

        Tasks issued to hardware will be completed in the order given.
        For example, you could issue five tasks without task completion
        notification and then wait on the sixth. When the sixth
        completes then all six tasks are guaranteed to have completed.

        Callbacks will be called from an interrupt handler and must
        follow the calling restrictions of interrupt handlers.

Returns:
        BERR_SUCCESS - Task was issued.

See Also:
        BGRC_IssueStateAndWait
****************************************************************************/
BERR_Code BGRC_IssueState(
        BGRC_Handle   hGrc,           /* [in] Handle to GRC module. */
        BGRC_Callback pCallback,      /* [in] Pointer to completion callback. */
        void         *pData           /* [in] Pointer to callback user data. */
);

/***************************************************************************
Summary:
        Issues state to hardware and wait for completion.

Description:
        When this call is made, all the state specified in the source,
        destination, blend, pattern, and output blocks will be 
        checked to make sure it is valid. If it is valid, it will be
        combined together to form one task which will then be issued
        to hardware.

    Hardware will work on this task asyncronously. The user has
        the option of waiting for the task to complete by using the function
        BGRC_IssueStateAndWait, having the module call a callback function
        when complete using BGRC_IssueState, or not be notified when
        this task is complete.

        Tasks issued to hardware will be completed in the order given.
        For example, you could issue five tasks without task completion
        notification and then wait on the sixth. When the sixth
        completes then all six tasks are guaranteed to have completed.

        This specific function does not use a callback but waits for
        the given task to complete.

Returns:
        BERR_SUCCESS - Task was issued and finished.

See Also:
        BGRC_IssueState
****************************************************************************/
BERR_Code BGRC_IssueStateAndWait(
        BGRC_Handle    hGrc                /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Checks if device operations have completed.

Description:
        This function will check the hardware registers to determine if all
        previous device operations issued through BGRC_IssueState() have 
        completed. If pending operations are complete, then true will be 
        returned in the pbComplete parameter, otherwise false will be returned.

Returns:
        BERR_SUCCESS - Task was issued and finished.

See Also:
        BGRC_IssueState
****************************************************************************/
BERR_Code BGRC_OperationsComplete(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        bool *pbComplete                   /* [out] Pointer to return value. */
);

/***************************************************************************
Summary:
        Wait until operations are ready.

Description:
        This function will wait until there are memory resources available to
        perform another blit. If a callback function is provided then this 
        function will return immediately, and call the callback function when
        memory resources are available.

Returns:
        BERR_SUCCESS - Task was issued and finished.

See Also:
        BGRC_WaitForOperationsComplete
****************************************************************************/
BERR_Code BGRC_WaitForOperationReady(
        BGRC_Handle   hGrc,
        BGRC_Callback pCallback_isr,
        void         *pData
);

/***************************************************************************
Summary:
        Wait until operations are complete.

Description:
        This function will wait until all operations are complete. If a callback 
        function is provided then this function will return immediately, and 
        call the callback function when all operations are complete.

Returns:
        BERR_SUCCESS - Task was issued and finished.

See Also:
        BGRC_WaitForOperationReady
****************************************************************************/
BERR_Code BGRC_WaitForOperationsComplete(
        BGRC_Handle   hGrc,
        BGRC_Callback pCallback_isr,
        void         *pData
);

/***************************************************************************
Summary:
        Sets the main surface for the source.

Description:
        This is used in conjunction with the alpha surface specified
        with BGRC_Source_SetAlphaSurface to describe the source pixels.

        This surface is not required. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Main surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_SetAlphaSurface,
****************************************************************************/
BERR_Code BGRC_Source_SetSurface(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface       /* [in] Main surface handle. */
);

/***************************************************************************
Summary:
        Sets the alpha surface for the source

Description:
        This is used in conjunction with the main surface specified with
        BGRC_Source_SetSurface to describe the source pixels.

        Currently, this can only be used with a main surface having a pixel
        format of BPXL_eR5_G6_B5 and an alpha surface having a pixel format
        of BPXL_eA1 or BPXL_eW1.

        This surface is not required. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Alpha surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetSurface
****************************************************************************/
BERR_Code BGRC_Source_SetAlphaSurface(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface          /* [in] Alpha surface handle. */
);

/***************************************************************************
Summary:
        Enables or disables the palette index bypass.

Description:
    Typically when a source contains a palette, the palette index
        is used to get color channel information from an actual palette.
        However, the user may decide to override this behavior and
        pass through the index as is. This function is used to 
        enable and disable this state.

        If this state is enabled, C2 and C1 will be set to zero and C0 will
        contain the index value. 

    The default is for the palette index to be used as a reference
        to a palette and not to use the palette index.

Returns:
        BERR_SUCCESS - Palette bypass was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetSurface
****************************************************************************/
BERR_Code BGRC_Source_TogglePaletteBypass(
        BGRC_Handle hGrc,               /* [in] Handle to GRC module. */
        bool bEnableBypass              /* [in] If true, index will be used
                                                                           directly. If false, the palette will
                                                                           be referenced. */
);

/***************************************************************************
Summary:
        Controls the chroma expansion for compressed YCrCb formats.

Description:
    When a compressed YCrCb format is used as an input, say
        BPXL_eY08_Cb8_Y18_Cr8, the pixels must first be uncompressed
        before they are converted. This function controls how the 
        pixels are uncompressed.

        As a default, eChromaExpansion will have a value of
        BGRC_ChromaExpansion_eReplicate.

Returns:
        BERR_SUCCESS - Alpha surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetSurface
****************************************************************************/
BERR_Code BGRC_Source_SetChromaExpansion(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_ChromaExpansion eChromaExpansion  /* [in] Chroma expansion type. */
);

/***************************************************************************
Summary:
        Enables zero padding or bit replication.

Description:
        When the source feeder reads pixels, if the pixel components are less 
        than 8 bits in size, it can either zero pad the low order bits, or 
        replicate the high order bits into the low order bits.

    The default is false (replication).

Returns:
        BERR_SUCCESS - Palette bypass was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetSurface
****************************************************************************/
BERR_Code BGRC_Source_SetZeroPad(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnableZeroPad              /* [in] If true, zero padding will be
                                                                            used. If false, bit replication
                                                                                will be used. */
);

/***************************************************************************
Summary:
        Sets color key values for the source.

Description:
        When called, the source color key state is set to use the given values.
        When color keying is enabled with BGRC_Source_ToggleColorKey,
        the values are used as follows:

        o Input color channels are masked with ulMask. The minimum
          (ulMin) and maximum (ulMax) range values are also masked.
        o If each of the components is less than or equal to the masked
          maximum and greater than or equal to the masked minimum, then the
          value is considered to be color keyed. Otherwise, it is not color
          keyed.
        o If the value is color keyed, Any bits of the result that have
          a corresponding bit set in ulReplacementMask are replaced
          with the bit value in ulReplacement.

        When setting bExclusive to true, the above compares become less than
        instead of less equal, and greater than instead of greater equal.

        When using ARGB, the color format of the parameters are 
        BPXL_eA8_R8_G8_B8, and when using AYCbCr, the formats are 
        BPXL_eA8_Y8_Cb8_Cr8.

        When a pixel is or isn't chroma keyed it effects the final output
        selection specified with the function BGRC_Output_SetColorKeySelection.

        The default is for all values to be set to zero, and bExclusive set 
        to false.

Returns:
        BERR_SUCCESS - Color key was enabled and set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_ToggleColorKey,
        BGRC_Source_SetKeyMatrixOrder,
        BGRC_Output_SetColorKeySelection,
****************************************************************************/
BERR_Code BGRC_Source_SetColorKey(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module. */
        uint32_t ulMin,                       /* [in] Minimum color key value. */
        uint32_t ulMax,                       /* [in] Maximum color key value. */
        uint32_t ulMask,                      /* [in] Color key mask. */
        uint32_t ulReplacement,               /* [in] Replacement value. */
        uint32_t ulReplacementMask,           /* [in] Replacement mask. */
        bool bExclusive                       /* [in] Inclusive/exclusive
                                                 compare. */
);

/***************************************************************************
Summary:
        Toggles the state of color keying.

Description:
        This function is used to enable and disable the state of color keying.
        When enabled, the values and process described in 
        BGRC_Source_SetColorKey will be used. When disabled, all pixels
        are marked as not being color keyed. This effects the final output
        selection, specified with the function
        BGRC_Output_SetColorKeySelection.

        The default is for color keying to be disabled.
        
Returns:
        BERR_SUCCESS - Color key was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_SetColorKey,
        BGRC_Source_SetKeyMatrixOrder,
        BGRC_Output_SetColorKeySelection,
****************************************************************************/
BERR_Code BGRC_Source_ToggleColorKey(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnable                     /* [in] If true, color keying is
                                                                                enabled. If false, color keying
                                                                                is disabled. */
);

/***************************************************************************
Summary:
        Sets the 5x4 color matrix for the source. 

Description:
        This matrix is used to modify the incoming source values.
        Typically this is done to convert from one color space to another.

        The values used for the color matrix are equal to the values stored 
        in the ai32_Matrix array right shifted by the ulShift value. In
        addition, negative values are converted to positive values before
        shifting and then turned back into negative values. For
        example, if a value in the matrix was 4 and the shift value was 2, then
        the final value is 1 (4>>2 = 1). If a value in the matrix was 7
        and the shift value was 3, then the final value would be 0.875.
        If a value in the matrix was -7 and the shift value was 3 then the
        final values is -0.875.

        The values within the color matrix are in the following order:

              |  M[0]   M[1]   M[2]   M[3]   M[4] |
              |  M[5]   M[6]   M[7]   M[8]   M[9] |
              | M[10]  M[11]  M[12]  M[13]  M[14] |
              | M[15]  M[16]  M[17]  M[18]  M[19] |

        This is multiplied with a column vector of 
        < C2in, C1in, C0in, Ain, 1 > which yields the following equations:

        C2out =  M[0]*C2in +  M[1]*C1in +  M[2]*C0in +  M[3]*Ain +  M[4]
        C1out =  M[5]*C2in +  M[6]*C1in +  M[7]*C0in +  M[8]*Ain +  M[9]
        C0out = M[10]*C2in + M[11]*C1in + M[12]*C0in + M[13]*Ain + M[14]
        Aout  = M[15]*C2in + M[16]*C1in + M[17]*C0in + M[18]*Ain + M[19]

        The default is to for the matrix to represent the identity.
        M[0] = M[6] = M[12] = M[18] = 1. All other values are zero.

Returns:
        BERR_SUCCESS - Color matrix was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_ToggleColorMatrix,
        BGRC_Source_SetColorMatrixRounding,
        BGRC_Source_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Source_SetColorMatrix5x4(
        BGRC_Handle hGrc,                 /* [in] Handle to GRC module. */
        const int32_t ai32_Matrix[20],    /* [in] Array of unshifted matrix
                                             values. */
        uint32_t ulShift                  /* [in] Matrix shift value. */
);

/***************************************************************************
Summary:
        Toggles the state of the color matrix.

Description:
        This function is used to enable and disable the color matrix.
        When enabled, the values and process described in 
        BGRC_Source_SetColorMatrix5x4 will be used. When disabled, the matrix
        values have no effect.

        The default is for the color matrix to be disabled.
        
Returns:
        BERR_SUCCESS - Color matrix was enabled and set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetColorMatrix5x4,
        BGRC_Source_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Source_ToggleColorMatrix(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnable                     /* [in] If true, the color matrix is
                                                                                enabled. If false, the color matrix
                                                                                is disabled. */
);

/***************************************************************************
Summary:
        Specifies how to round the output values from the source color matrix.

Description:
        The default rounding state is BGRC_Rounding_eNearest.

        In our current hardware implementation, this setting cannot differ from
        the destination color matrix rounding setting or output color matrix
        rounding setting. The user must insure that these settings are the
        same or an error will result.

Returns:
        BERR_SUCCESS - Color matrix rounding was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_SetColorMatrix5x4,
        BGRC_Source_ToggleColorMatrix,
        BGRC_Destination_SetColorMatrixRounding,
        BGRC_Output_SetColorMatrixRounding
****************************************************************************/
BERR_Code BGRC_Source_SetColorMatrixRounding(
        BGRC_Handle hGrc,                   /* [in] Handle to GRC module. */
        BGRC_Rounding eMatrixRounding       /* [in] Matrix rounding selection. */
);

/***************************************************************************
Summary:
        Determines the order of the color key and matrix operation.

Description:
        Gives the user the option of doing color keying first and color 
        matrix operations second or the option of doing color matrix
        operations first and color keying second.

        The default is to use an order of 
        BGRC_KeyMatrixOrder_eKeyThenMatrix.

Returns:
        BERR_SUCCESS - Order was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_ToggleColorKey,
        BGRC_Source_ToggleColorMatrix
****************************************************************************/
BERR_Code BGRC_Source_SetKeyMatrixOrder(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_KeyMatrixOrder eKeyMatrixOrder    /* [in] Color key/matrix order
                                                  selection. */
);

/***************************************************************************
Summary:
        Determines the order of the color key, color matrix, and scaling.

Description:
        Gives the user the option of selecting the order of color key,
        color matrix, and scaling operations. The user also has the option
        of bypassing all these operations.

        The default is to use an order of 
        BGRC_KeyMatrixScaleOrder_eKeyThenScaleThenMatrix.

Returns:
        BERR_SUCCESS - Order was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_ToggleColorKey,
        BGRC_Source_ToggleColorMatrix
****************************************************************************/
BERR_Code BGRC_Source_SetKeyMatrixScaleOrder(
        BGRC_Handle hGrc,                             /* [in] Handle to GRC. */
        BGRC_KeyMatrixScaleOrder eKeyMatrixScaleOrder /* [in] Key/matrix/scale
                                                         order selection. */
);

/***************************************************************************
Summary:
        Sets the constant color for the source.

Description:
        This value is used when the source surfaces are missing the alpha
        or color channels. When the color is ARGB, the color format is 
        BPXL_eA8_R8_G8_B8, and when it is AYCbCr, the format is 
        BPXL_eA8_Y8_Cb8_Cr8. When the surface format is less than a byte in 
        size, the high-bits of the low-byte contains the constant color.


        The default is 0xFF000000 (Alpha is 1, color channels are 0).
  
Returns:
        BERR_SUCCESS - Constant alpha and color was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetSurface,
        BGRC_Source_SetAlphaSurface
****************************************************************************/
BERR_Code BGRC_Source_SetColor(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulColor                       /* [in] Constant values to use. */
);

/***************************************************************************
Summary:
        Specifies the sub-rectangle of the source surface.

Description:
        Only the values within this rectangle will be used in the
        compositor calculations. The values given here must be restricted
        to the size of the surface itself.

        The source will be scaled to the size of the output
        rectangle, specified by BGRC_Output_SetRectangle.

        The default behavior is to use a rectangle the size of the entire
        specified source.

Returns:
        BERR_SUCCESS - Rectangle was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Output_SetRectangle
****************************************************************************/
BERR_Code BGRC_Source_SetRectangle(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulLeft,                       /* [in] Rectangle left. */
        uint32_t ulTop,                        /* [in] Rectangle top. */
        uint32_t ulWidth,                      /* [in] Rectangle width. */
        uint32_t ulHeight                      /* [in] Rectangle height. */
);

/***************************************************************************
Summary:
        Sets the coefficients for the source filter.

Description:
        Specifies the coefficients to use when filtering is enabled on the
        source. If scaling is enabled, filtering will be enabled except
        for severe downscaling. If scaling isn't enabled, filtering
        can be enabled through BGRC_Source_ToggleFilter.

        The default for both filter coefficients is BGRC_FilterCoeffs_eSharp.

Returns:
        BERR_SUCCESS - Filter coefficients were set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_ToggleFilter
****************************************************************************/
BERR_Code BGRC_Source_SetFilterCoeffs(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_FilterCoeffs eHorizontalCoeffs,   /* [in] Horizontal coefficients 
                                                  selection. */
        BGRC_FilterCoeffs eVerticalCoeffs      /* [in] Vertical coefficients
                                                  selection. */
);

/***************************************************************************
Summary:
        Used to toggle filtering on the source.

Description:
        This function is used to enable filtering on the horizontal
        or vertical axis of the source. This state is only used when scaling
        is disabled for a specific axis.

Returns:
        BERR_SUCCESS - Filtering state was updated.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_ToggleFilter(
        BGRC_Handle hGrc,                 /* [in] Handle to GRC module. */
        bool bEnableHorizontalFilter,     /* [in] If true, the horizontal
                                             filter is enabled. When false,
                                                                             the horizontal filter is disabled. */       
        bool bEnableVerticalFilter        /* [in] If true, the vertical
                                             filter is enabled. When false,
                                                                             the vertical filter is disabled. */
);

/***************************************************************************
Summary:
        Sets the initial phase adjustment for filtering.

Description:
        Specifies how many source pixels to initial shift when filtering.
        The phase will be shifted by the shift value and added to the default
        initial phase value. A positive value will shift the image left or 
        up, and a negative value will shift it right or down.

        The resulting initial phase shift formula when scaling is:
                (SrcSize / OutSize - 1) / 2 + PhaseAdj

        When not scaling the formula is:
                1/2 + PhaseAdj

        The final adjusted phase shift must be greater than or equal to -4.0 
        and less than 4.0.

        The default values are all 0.

Returns:
        BERR_SUCCESS - Filter inital phase was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_SetFilterPhaseAdjustment(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        int32_t iHorizontalPhase,          /* [in] Horizontal initial phase. */
        int32_t iVerticalPhase,            /* [in] Vertical initial phase. */
        uint32_t ulShift                   /* [in] Initial phase shift value. */
);

/***************************************************************************
Summary:
        Sets the scale factors when scaling or filtering.

Description:
        Overrides the horizontal and vertical scale factor when scaling or when 
        filtering is enabled. When either a numerator or a denominator is set 
        to 0, the corresponding scale factor will be calculated using the source 
        and output rectangles, where the source size is used as the numerator.

        The default values are all 0.

Returns:
        BERR_SUCCESS - Scale factors were set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetFilterPhaseAdjustment
****************************************************************************/
BERR_Code BGRC_Source_SetFixedScaleFactor(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        uint32_t ulHorizontalNumerator,    /* [in] Horizontal/Source numerator */
        uint32_t ulHorizontalDenominator,  /* [in] Horizontal/Source denominator */
        uint32_t ulVerticalNumerator,      /* [in] Vertical/Output numerator */
        uint32_t ulVerticalDenominator     /* [in] Vertical/Output denominator */
);

/***************************************************************************
Summary:
        Specifies whether to adjust alpha for scaling.

Description:
        This bit will have effect only when "ScaleAlphaAdjust" is enabled.
        When enabled, alpha/2 value is subtracted from input sample components. 
        When disabled, a constant value of 128 is subtracted from the input 
        sample components. These subtractions are done before data goes into 
        the filter and are added back once the sample comes out, however the 
        alpha value added is the modified (scaled) alpha value.

        The default is false.

Returns:
        BERR_SUCCESS - Alpha adjust was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_SetScaleAlphaAdjust(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        bool bAdjustAlpha                      /* [in] Adjust alpha enable. */
);

/***************************************************************************
Summary:
        Specifies whether to alpha premultiply for scaling.

Description:
        Indicates if the input samples are required to be treated as alpha 
        premultiplied by the scaler. This will have effect only when 
        BGRC_Source_SetScaleAlphaAdjust is enabled. When enabled, alpha/2 value 
        is subtracted from input sample. When disabled, a constant value of 0x80 
        is subtracted from the input sample. These subtractions are done before 
        data goes into the FIR. They are added back in the same way as above once 
        the sample comes out of FIR. However, the alpha value added is the 
        modified (scaled) alpha value.

        The default is false.

Returns:
        BERR_SUCCESS - Scale premultiply was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_SetScaleAlphaPreMultiply(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        bool bAlphaPreMultiply                 /* [in] Premultiply enable. */
);

/***************************************************************************
Summary:
        Specifies how to round values after scaling.

Description:
        The default rounding state is BGRC_Rounding_eNearest.

Returns:
        BERR_SUCCESS - Scale rounding was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_SetScaleRounding(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        BGRC_Rounding eScaleRounding         /* [in] Scale rounding selection. */
);
        
/***************************************************************************
Summary:
        Specifies what to do on scaler edge conditions.

Description:
        The default is to use an edge condition of BGRC_EdgeCondition_eMirror.

Returns:
        BERR_SUCCESS - Scale edge condition was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetFilterCoeffs
****************************************************************************/
BERR_Code BGRC_Source_SetScaleEdgeCondition(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        BGRC_EdgeCondition eEdgeCondition    /* [in] Edge condition selection. */
);

/***************************************************************************
Summary:
        Enables alpha premultiply.

Description:
        When this bit is enabled the components of the pixel are multiplied by 
        the correspnding alpha value before scaling. 

Returns:
        BERR_SUCCESS - Alpha premultiply was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetClutScaleMode
****************************************************************************/
BERR_Code BGRC_Source_SetAlphaPreMultiply(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        bool bAlphaPreMultiply               /* [in] Alpha premultiply enable. */
);

/***************************************************************************
Summary:
        Enables alpha premultiply offset.

Description:
        When this bit is enabled a constant value of 128 is subtracted from 
        the components before alpha-premultiply and is added back afterwords. 
        This has no effect if "AlphaPreMultiply" is not enabled.

Returns:
        BERR_SUCCESS - Alpha premultiply offset was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetClutScaleMode
****************************************************************************/
BERR_Code BGRC_Source_SetAlphaPreMultiplyOffset(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        bool bOffset                         /* [in] Offset adjustment enable. */
);

/***************************************************************************
Summary:
        Sets MacroBlock range type for YCbCr 420 source.

Description:
        When using a YCbCr 420 source, the MacroBlock range can be set to
        none, expansion, or remapping for both Y and CbCr. With remapping, 
        a scale factor between 0 and 7 is required.

        The formula for range remapping using a scale factor is:
        Y = CLIP(((Y - 128) * (ucScaleFactorY + 9) + 4) >> 3) + 128)
        C = CLIP(((C - 128) * (ucScaleFactorC + 9) + 4) >> 3) + 128)

        Default is none.

Returns:
        BERR_SUCCESS - MacroBlock was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetSurface
****************************************************************************/
BERR_Code BGRC_Source_SetMacroBlock(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        BGRC_MacroBlockRange eRangeY,        /* [in] Range type for Y */
        BGRC_MacroBlockRange eRangeC,        /* [in] Range type for CbCr */
        uint8_t ucScaleFactorY,              /* [in] Scale factor for Y */
        uint8_t ucScaleFactorC               /* [in] Scale factor for CbCr */
);

/***************************************************************************
Summary:
        Sets MacroBlock strip width.

Description:
        When using a YCbCr 420 source, the MacroBlock strip width defaults
        to 64 but can also be set to 128 for newer M2MCs.

        Default is 64.

Returns:
        BERR_SUCCESS - MacroBlock strip width was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetMacroBlock
****************************************************************************/
BERR_Code BGRC_Source_SetMacroBlock_StripWidth(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        uint32_t ulStripWidth                /* [in] Macroblock strip width */
);

/***************************************************************************
Summary:
        Sets MacroBlock storage format.

Description:
        When using a YCbCr 420 source, the MacroBlock source can either be 
        stored in the display or linear format.

        Default is display format (false).

Returns:
        BERR_SUCCESS - MacroBlock linear format was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetMacroBlock
****************************************************************************/
BERR_Code BGRC_Source_SetMacroBlock_LinearFormat(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        bool bLinearFormat                   /* [in] Enable linear format */
);

/***************************************************************************
Summary:
        Sets MacroBlock endian.

Description:
        When using a YCbCr 420 source, the MacroBlock source can either be 
        stored as little or big endian.

        Default is little endian (false).

Returns:
        BERR_SUCCESS - MacroBlock endian was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Source_SetMacroBlock
****************************************************************************/
BERR_Code BGRC_Source_SetMacroBlock_Endian(
        BGRC_Handle hGrc,                    /* [in] Handle to GRC module. */
        bool bBigEndian                      /* [in] Enable big endian format */
);

/***************************************************************************
Summary:
        Sets source blit direction.

Description:
        This function inverts the pixels of the surface in the specified 
        direction(s), from right to left, and bottom to top.

        Defaults are false, left to right, and top to bottom.

Returns:
        BERR_SUCCESS - Direction was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
****************************************************************************/
BERR_Code BGRC_Source_SetDirection(
        BGRC_Handle hGrc,
        bool bRightToLeft,
        bool bBottomToTop 
);

/***************************************************************************
Summary:
        Resets the state of the source.

Description:
        All state set by source functions is now set to be the default value.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_SetDefault
****************************************************************************/
BERR_Code BGRC_Source_ResetState(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the default parameters for the source.

Description:
        Each source function has a default state associated with it, described
        in each of the functions used to modify that state. However, the user
        may wish to modify the default state so that future calls to 
        BGRC_Source_ResetState will use user defined values.
        
        This function allows you to change the default state. First the user
        calls functions to set the needed source state. It then calls
        this function which will then use the current state as the default.
        Subsequent calls to BGRC_Source_ResetState will use the new
        values.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_ResetState
****************************************************************************/
BERR_Code BGRC_Source_SetDefault(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the main surface for the destination.

Description:
        This is used in conjunction with the alpha surface specified
        with BGRC_Destination_SetAlphaSurface to describe the destination
        pixels.

        This surface is not required. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Main surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Destination_SetAlphaSurface,
****************************************************************************/
BERR_Code BGRC_Destination_SetSurface(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface       /* [in] Main surface handle. */
);

/***************************************************************************
Summary:
        Sets the alpha surface for the destination

Description:
        This is used in conjunction with the main surface specified with
        BGRC_Destination_SetSurface to describe the destination pixels.

        Currently, this can only be used with a main surface having a pixel
        format of BPXL_eR5_G6_B5 and an alpha surface having a pixel format
        of BPXL_eA1 or BPXL_eW1.

        This surface is not required. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Alpha surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Destination_SetSurface,
****************************************************************************/
BERR_Code BGRC_Destination_SetAlphaSurface(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface          /* [in] Alpha surface handle. */
);

/***************************************************************************
Summary:
        Enables or disables the palette index bypass.

Description:
    Typically when a source contains a palette, the palette index
        is used to get color channel information from an actual palette.
        However, the user may decide to override this behavior and
        pass through the index as is. This function is used to 
        enable and disable this state.

        If this state is enabled, C2 and C1 will be set to zero and C0 will
        contain the index value. 

    The default is for the palette index to be used as a reference
        to a palette and not to use the palette index.

Returns:
        BERR_SUCCESS - Palette bypass was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Destination_SetSurface
****************************************************************************/
BERR_Code BGRC_Destination_TogglePaletteBypass(
        BGRC_Handle hGrc,               /* [in] Handle to GRC module. */
        bool bEnableBypass              /* [in] If true, index will be used
                                                                           directly. If false, the palette will
                                                                           be referenced. */
);

/***************************************************************************
Summary:
        Controls the chroma expansion for compressed YCrCb formats.

Description:
    When a compressed YCrCb format is used as an input, say
        BPXL_eY08_Cb8_Y18_Cr8, the pixels must first be uncompressed
        before they are converted into the device's internal color format, 
        BPXL_eA8_Y8_Cb8_Cr8. This function controls how the pixels 
        are uncompressed.

        As a default, eChromaExpansion will have a value of
        BGRC_ChromaExpansion_eReplicate.

Returns:
        BERR_SUCCESS - Alpha surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Destination_SetSurface,
****************************************************************************/
BERR_Code BGRC_Destination_SetChromaExpansion(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_ChromaExpansion eChromaExpansion  /* [in] Chroma expansion type. */
);

/***************************************************************************
Summary:
        Enables zero padding or bit replication.

Description:
        When the destination feeder reads pixels, it the pixel components are 
        less than 8 bits in size, it can either zero pad the low order bits, or 
        replicate the high order bits into the low order bits.

    The default is false (replication).

Returns:
        BERR_SUCCESS - Palette bypass was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Destination_SetSurface
****************************************************************************/
BERR_Code BGRC_Destination_SetZeroPad(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnableZeroPad              /* [in] If true, zero padding will be
                                                                            used. If false, bit replication
                                                                                will be used. */
);

/***************************************************************************
Summary:
        Sets color key values for the destination.

Description:
        When called, the destination color key state is set to use the given
        values. When color keying is enabled with
        BGRC_Destination_ToggleColorKey, the values are used as follows:

        o Input color channels are masked with ulMask. The minimum (ulMin) 
          and maximum (ulMax) range values are also masked.
        o If each of the components is less than or equal to the masked
          maximum and greater than or equal to the masked minimum, then the
          value is considered to be color keyed. Otherwise, it is not color
          keyed.
        o If the value is color keyed, Any bits of the result that have
          a corresponding bit set in ulReplacementMask are replaced with 
          the bit value in ulReplacement.

        When setting bExclusive to true, the above compares become less than
        instead of less equal, and greater than instead of greater equal.

        When using ARGB, the color format of the parameters are 
        BPXL_eA8_R8_G8_B8, and when using AYCbCr, the formats are 
        BPXL_eA8_Y8_Cb8_Cr8.

        When a pixel is or isn't chroma keyed it effects the final output
        selection specified with the function BGRC_Output_SetColorKeySelection.

        The default is for all values to be set to zero, and bExclusive set to 
        false.

Returns:
        BERR_SUCCESS - Color key was enabled and set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Destination_ToggleColorKey,
        BGRC_Destination_SetKeyMatrixOrder,
        BGRC_Output_SetColorKeySelection,
****************************************************************************/
BERR_Code BGRC_Destination_SetColorKey(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module. */
        uint32_t ulMin,                       /* [in] Minimum color key value. */
        uint32_t ulMax,                       /* [in] Maximum color key value. */
        uint32_t ulMask,                      /* [in] Color key mask. */
        uint32_t ulReplacement,               /* [in] Replacement value. */
        uint32_t ulReplacementMask,           /* [in] Replacement mask. */
        bool bExclusive                       /* [in] Inclusive/exclusive
                                                 compare. */
);

/***************************************************************************
Summary:
        Toggles the state of color keying.

Description:
        This function is used to enable and disable the state of color keying.
        When enabled, the values and process described in 
        BGRC_Destination_SetColorKey will be used. When disabled, all pixels
        are marked as not being color keyed. This effects the final output
        selection, specified with the function
        BGRC_Output_SetColorKeySelection.

        The default is for color keying to be disabled.
        
Returns:
        BERR_SUCCESS - Color key was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Destination_SetColorKey,
        BGRC_Destination_SetKeyMatrixOrder,
        BGRC_Output_SetColorKeySelection,
****************************************************************************/
BERR_Code BGRC_Destination_ToggleColorKey(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnable                     /* [in] If true, color keying is
                                                                                enabled. If false, color keying
                                                                                is disabled. */
);

/***************************************************************************
Summary:
        Sets the 5x4 color matrix for the destination. 

Description:
        This matrix is used to modify the incoming destination values.
        Typically this is done to convert from one color space to another.

        The values used for the color matrix are equal to the values stored 
        in the ai32_Matrix array right shifted by the ulShift value. In
        addition, negative values are converted to positive values before
        shifting and then turned back into negative values. For
        example, if a value in the matrix was 4 and the shift value was 2, then
        the final value is 1 (4>>2 = 1). If a value in the matrix was 7
        and the shift value was 3, then the final value would be 0.875.
        If a value in the matrix was -7 and the shift value was 3 then the
        final values is -0.875.

        The values within the color matrix are in the following order:

              |  M[0]   M[1]   M[2]   M[3]   M[4] |
              |  M[5]   M[6]   M[7]   M[8]   M[9] |
              | M[10]  M[11]  M[12]  M[13]  M[14] |
              | M[15]  M[16]  M[17]  M[18]  M[19] |

        This is multiplied with a column vector of 
        < C2in, C1in, C0in, Ain, 1 > which yields the following equations:

        C2out =  M[0]*C2in +  M[1]*C1in +  M[2]*C0in +  M[3]*Ain +  M[4]
        C1out =  M[5]*C2in +  M[6]*C1in +  M[7]*C0in +  M[8]*Ain +  M[9]
        C0out = M[10]*C2in + M[11]*C1in + M[12]*C0in + M[13]*Ain + M[14]
        Aout  = M[15]*C2in + M[16]*C1in + M[17]*C0in + M[18]*Ain + M[19]

        The default is to for the matrix to represent the identity.
        M[0] = M[6] = M[12] = M[18] = 1. All other values are zero.

Returns:
        BERR_SUCCESS - Color matrix was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Destination_ToggleColorMatrix,
        BGRC_Destination_SetColorMatrixRounding,
        BGRC_Destination_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Destination_SetColorMatrix5x4(
        BGRC_Handle hGrc,                 /* [in] Handle to GRC module. */
        const int32_t ai32_Matrix[20],    /* [in] Array of unshifted matrix
                                             values. */
        uint32_t ulShift                  /* [in] Matrix shift value. */
);

/***************************************************************************
Summary:
        Toggles the state of the color matrix.

Description:
        This function is used to enable and disable the color matrix.
        When enabled, the values and process described in 
        BGRC_Destination_SetColorMatrix5x4 will be used. When disabled,
        the matrix values have no effect.

        The default is for the color matrix to be disabled.
        
Returns:
        BERR_SUCCESS - Color matrix was enabled and set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Destination_SetColorMatrix5x4,
        BGRC_Destination_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Destination_ToggleColorMatrix(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnable                     /* [in] If true, the color matrix is
                                                                                enabled. If false, the color matrix
                                                                                is disabled. */
);

/***************************************************************************
Summary:
        Specifies how to round the output values from the destination color
        matrix.

Description:
        The default rounding state is BGRC_Rounding_eNearest.

        In our current hardware implementation, this setting cannot differ from
        the source color matrix rounding setting or output color matrix
        rounding setting. The user must insure that these settings are the
        same or an error will result.

Returns:
        BERR_SUCCESS - Color matrix rounding was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Destination_SetColorMatrix5x4,
        BGRC_Destination_ToggleColorMatrix,
        BGRC_Source_SetColorMatrixRounding,
        BGRC_Output_SetColorMatrixRounding
****************************************************************************/
BERR_Code BGRC_Destination_SetColorMatrixRounding(
        BGRC_Handle hGrc,                   /* [in] Handle to GRC module. */
        BGRC_Rounding eMatrixRounding       /* [in] Matrix rounding selection. */
);

/***************************************************************************
Summary:
        Determines the order of the color key and matrix operation.

Description:
        Gives the user the option of doing color keying first and color 
        matrix operations second or the option of doing color matrix
        operations first and color keying second.

        The default is to use an order of 
        BGRC_KeyMatrixOrder_eKeyThenMatrix.

Returns:
        BERR_SUCCESS - Color keying was enabled.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Destination_ToggleColorKey,
        BGRC_Destination_ToggleColorMatrix
****************************************************************************/
BERR_Code BGRC_Destination_SetKeyMatrixOrder(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_KeyMatrixOrder eKeyMatrixOrder    /* [in] Color key/matrix order 
                                                  selection. */
);

/***************************************************************************
Summary:
        Sets the constant color for the destination.

Description:
        This value is used when the destination surfaces are missing the alpha
        or color channels. When the color is ARGB, the color format is 
        BPXL_eA8_R8_G8_B8, and when it is AYCbCr, the format is 
        BPXL_eA8_Y8_Cb8_Cr8. When the surface format is less than a byte in 
        size, the high-bits of the low-byte contains the constant color.

        The default is 0xFF000000 (Alpha is 1, color channels are 0).
  
Returns:
        BERR_SUCCESS - Constant alpha and color was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Destination_SetSurface,
        BGRC_Destination_SetAlphaSurface
****************************************************************************/
BERR_Code BGRC_Destination_SetColor(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulColor                       /* [in] Constant values to use. */
);

/***************************************************************************
Summary:
        Specifies the sub-rectangle of the destination surface.

Description:
        Only the values within this rectangle will be used in the
        compositor calculations. The values given here must be restricted
        to the size of the surface itself.

        The source will be scaled to the size of the output
        rectangle, specified by BGRC_Output_SetRectangle. Since our
        current hardware does not support scaling of the destination, 
        the destination rectangle size must match the size of the 
        output rectangle.

        The default behavior is to use a rectangle the size of the entire
        specified destination.

Returns:
        BERR_SUCCESS - Rectangle was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Output_SetRectangle
****************************************************************************/
BERR_Code BGRC_Destination_SetRectangle(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulLeft,                       /* [in] Rectangle left. */
        uint32_t ulTop,                        /* [in] Rectangle top. */
        uint32_t ulWidth,                      /* [in] Rectangle width. */
        uint32_t ulHeight                      /* [in] Rectangle height. */
);

/***************************************************************************
Summary:
        Sets destination blit direction.

Description:
        This function inverts the pixels of the surface in the specified 
        direction(s), from right to left, and bottom to top.

        Defaults are false, left to right, and top to bottom.

Returns:
        BERR_SUCCESS - Direction was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
****************************************************************************/
BERR_Code BGRC_Destination_SetDirection(
        BGRC_Handle hGrc,
        bool bRightToLeft,
        bool bBottomToTop 
);

/***************************************************************************
Summary:
        Resets the state of the destination.

Description:
        All state set by destination functions is now set to be the default
        value.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Destination_SetDefault
****************************************************************************/
BERR_Code BGRC_Destination_ResetState(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the default parameters for the destination.

Description:
        Each destination function has a default state associated with it,
        described in each of the functions used to modify that state. However,
        the user may wish to modify the default state so that future calls to 
        BGRC_Destination_ResetState will use user defined values.
        
        This function allows you to change the default state. First the user
        calls functions to set the needed destination state. It then calls
        this function which will then use the current state as the default.
        Subsequent calls to BGRC_Destination_ResetState will use the new
        values.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Destination_ResetState
****************************************************************************/
BERR_Code BGRC_Destination_SetDefault(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the parameters for the pattern operation.

Description:
        Mixes source, destination, and/or pattern using standard 
        ROP3 operations.

        The pattern will be oriented to the output top/left position.

Returns:
        BERR_SUCCESS - Pattern was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Output_SetColorKeySelection
****************************************************************************/
BERR_Code BGRC_Pattern_Set(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint8_t ucVector,                      /* [in] 8 bit ROP vector. */
        const uint8_t aucPattern[8],           /* [in] 8x8 bit ROP pattern. */
        uint32_t ulColor0,                     /* [in] ROP background color. */
        uint32_t ulColor1                      /* [in] ROP foreground color. */
);

/***************************************************************************
Summary:
        Resets the state of the pattern block.

Description:
        All state set by pattern functions is now set to be the default value.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Pattern_SetDefault
****************************************************************************/
BERR_Code BGRC_Pattern_ResetState(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the default parameters for the pattern block.

Description:
        Each pattern function has a default state associated with it, described
        in each of the functions used to modify that state. However, the user
        may wish to modify the default state so that future calls to 
        BGRC_Pattern_ResetState will use user defined values.
        
        This function allows you to change the default state. First the user
        calls functions to set the needed source state. It then calls
        this function which will then use the current state as the default.
        Subsequent calls to BGRC_Pattern_ResetState will use the new
        values.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Pattern_ResetState
****************************************************************************/
BERR_Code BGRC_Pattern_SetDefault(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the constant color for blending operations.

Description:
        This value is used during the blend operations when blend source values
        are BGRC_Blend_Source_eConstantColor, 
        BGRC_Blend_Source_eInverseConstantColor, 
        BGRC_Blend_Source_eConstantAlpha, or 
        BGRC_Blend_Source_eInverseConstantAlpha. When the color is ARGB, the 
        color format is BPXL_eA8_R8_G8_B8, and when it is AYCbCr, the format 
        is BPXL_eA8_Y8_Cb8_Cr8. When the surface format is less than a byte in 
        size, the high-bits of the low-byte contains the constant color.

        The default is 0xFF000000 (Alpha is 1, color channels are 0).

Returns:
        BERR_SUCCESS - Constant color was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Blend_SetColorBlend,
        BGRC_Blend_SetAlphaBlend
****************************************************************************/
BERR_Code BGRC_Blend_SetColor(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulColor                       /* [in] Constant values to use. */
);

/***************************************************************************
Summary:
        Sets the blending operations for the color components.

Description:
        The basic function used for each color component is determined
        by the following function:

        (A*B) +/- (C*D) +/- E

        By picking and choosing the values for A, B, C, D, and E, you can
        achieve many different kinds of blending effects. In addition,
        you can make the +/- choice in the equation.

        The default is for eSourceA to be BGRC_Blend_Source_eSourceColor,
        eSourceB to be BGRC_Blend_Source_eOne, bSubtractCD to be false,
        eSourceC to be BGRC_Blend_Source_eZero, eSourceD to be
        BGRC_Blend_Source_eZero, bSubtractE to be false, and eSourceE to be
        BGRC_Blend_Source_eZero. This results in a pass through of the color
        information.

Returns:
        BERR_SUCCESS - Color blend operations were set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Blend_SetAlphaBlend
****************************************************************************/
BERR_Code BGRC_Blend_SetColorBlend(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_Blend_Source eSourceA,            /* [in] Source for A. */
        BGRC_Blend_Source eSourceB,            /* [in] Source for B. */
        bool bSubtractCD,                      /* [in] Subtract C*D enable. */
        BGRC_Blend_Source eSourceC,            /* [in] Source for C. */
        BGRC_Blend_Source eSourceD,            /* [in] Source for D. */
        bool bSubtractE,                       /* [in] Subtract for E enable. */
        BGRC_Blend_Source eSourceE             /* [in] Source for E. */
);

/***************************************************************************
Summary:
        Sets the blending operations for the alpha component.

Description:
        The basic function used for the alpha component is determined
        by the following function:

        (A*B) +/- (C*D) +/- E

        By picking and choosing the values for A, B, C, D, and E, you can
        achieve many different kinds of blending effects. In addition,
        you can make the +/- choice in the equation.

        The default is for eSourceA to be BGRC_Blend_Source_eSourceAlpha,
        eSourceB to be BGRC_Blend_Source_eOne, bSubtractCD to be false,
        eSourceC to be BGRC_Blend_Source_eZero, eSourceD to be
        BGRC_Blend_Source_eZero, bSubtractE to be false, and eSourceE to be
        BGRC_Blend_Source_eZero. This results in a pass through of the alpha
        component.

    Note that the following sources cannot be used by the alpha blender:
        BGRC_Blend_Source_eSourceColor, BGRC_Blend_Source_eInverseSourceColor,
        BGRC_Blend_Source_eDestinationColor, or 
        BGRC_Blend_Source_eInverseDestinationColor.

Returns:
        BERR_SUCCESS - Alpha blend operations were set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Blend_SetColorBlend
****************************************************************************/
BERR_Code BGRC_Blend_SetAlphaBlend(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        BGRC_Blend_Source eSourceA,            /* [in] Source for A. */
        BGRC_Blend_Source eSourceB,            /* [in] Source for B. */
        bool bSubtractCD,                      /* [in] Subtract C*D enable. */
        BGRC_Blend_Source eSourceC,            /* [in] Source for C. */
        BGRC_Blend_Source eSourceD,            /* [in] Source for D. */
        bool bSubtractE,                       /* [in] Subtract for E enable. */
        BGRC_Blend_Source eSourceE             /* [in] Source for E. */
);

/***************************************************************************
Summary:
        Resets the state of the blend block.

Description:
        All state set by blend functions is now set to be the default value.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Blend_SetDefault
****************************************************************************/
BERR_Code BGRC_Blend_ResetState(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the default parameters for the blend block.

Description:
        Each blend function has a default state associated with it, described
        in each of the functions used to modify that state. However, the user
        may wish to modify the default state so that future calls to 
        BGRC_Blend_ResetState will use user defined values.
        
        This function allows you to change the default state. First the user
        calls functions to set the needed blend state. It then calls
        this function which will then use the current state as the default.
        Subsequent calls to BGRC_Blend_ResetState will use the new
        values.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Blend_ResetState
****************************************************************************/
BERR_Code BGRC_Blend_SetDefault(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the main surface for the output.

Description:
        This is used in conjunction with the alpha surface specified
        with BGRC_Output_SetAlphaSurface to describe the location where the
        final pixels are stored.

        This surface must be supplied. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Main surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Output_SetAlphaSurface,
****************************************************************************/
BERR_Code BGRC_Output_SetSurface(
        BGRC_Handle hGrc,                  /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface       /* [in] Main surface handle. */
);

/***************************************************************************
Summary:
        Sets the alpha surface for the output.

Description:
        This is used in conjunction with the main surface specified with
        BGRC_Output_SetSurface to describe the location where the
        final pixels are stored.

        Currently, this can only be used with a main surface having a pixel
        format of BPXL_eR5_G6_B5 and an alpha surface having a pixel format
        of BPXL_eA1 or BPXL_eW1.

        This surface is not required. As a default, this surface is not
        specified.

Returns:
        BERR_SUCCESS - Alpha surface was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Output_SetSurface
****************************************************************************/
BERR_Code BGRC_Output_SetAlphaSurface(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module. */
        BSUR_Surface_Handle hSurface          /* [in] Alpha surface handle. */
);

/***************************************************************************
Summary:
        Sets the 5x4 color matrix for the output. 

Description:
        This matrix is used to modify the outgoing output values.
        Typically this is done to convert from one color space to another.

        The values used for the color matrix are equal to the values stored 
        in the ai32_Matrix array right shifted by the ulShift value. In
        addition, negative values are converted to positive values before
        shifting and then turned back into negative values. For
        example, if a value in the matrix was 4 and the shift value was 2, then
        the final value is 1 (4>>2 = 1). If a value in the matrix was 7
        and the shift value was 3, then the final value would be 0.875.
        If a value in the matrix was -7 and the shift value was 3 then the
        final values is -0.875.

        The values within the color matrix are in the following order:

              |  M[0]   M[1]   M[2]   M[3]   M[4] |
              |  M[5]   M[6]   M[7]   M[8]   M[9] |
              | M[10]  M[11]  M[12]  M[13]  M[14] |
              | M[15]  M[16]  M[17]  M[18]  M[19] |

        This is multiplied with a column vector of 
        < C2in, C1in, C0in, Ain, 1 > which yields the following equations:

        C2out =  M[0]*C2in +  M[1]*C1in +  M[2]*C0in +  M[3]*Ain +  M[4]
        C1out =  M[5]*C2in +  M[6]*C1in +  M[7]*C0in +  M[8]*Ain +  M[9]
        C0out = M[10]*C2in + M[11]*C1in + M[12]*C0in + M[13]*Ain + M[14]
        Aout  = M[15]*C2in + M[16]*C1in + M[17]*C0in + M[18]*Ain + M[19]

        The default is to for the matrix to represent the identity.
        M[0] = M[6] = M[12] = M[18] = 1. All other values are zero.

Returns:
        BERR_SUCCESS - Color matrix was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Output_ToggleColorMatrix,
        BGRC_Output_SetColorMatrixRounding,
        BGRC_Output_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Output_SetColorMatrix5x4(
        BGRC_Handle hGrc,                 /* [in] Handle to GRC module. */
        const int32_t ai32_Matrix[20],    /* [in] Array of unshifted matrix
                                             values. */
        uint32_t ulShift                  /* [in] Matrix shift value. */
);

/***************************************************************************
Summary:
        Toggles the state of the color matrix.

Description:
        This function is used to enable and disable the color matrix.
        When enabled, the values and process described in 
        BGRC_Output_SetColorMatrix5x4 will be used. When disabled, the matrix
        values have no effect.

        The default is for the color matrix to be disabled.
        
Returns:
        BERR_SUCCESS - Color matrix was enabled and set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.

See Also:
        BGRC_Output_SetColorMatrix5x4,
        BGRC_Output_SetKeyMatrixOrder,
****************************************************************************/
BERR_Code BGRC_Output_ToggleColorMatrix(
        BGRC_Handle hGrc,                /* [in] Handle to GRC module. */
        bool bEnable                     /* [in] If true, the color matrix is
                                                                                enabled. If false, the color matrix
                                                                                is disabled. */
);

/***************************************************************************
Summary:
        Specifies how to round the output values from the output color matrix.

Description:
        The default rounding state is BGRC_Rounding_eNearest.

        In our current hardware implementation, this setting cannot differ from
        the source color matrix rounding setting or destination color matrix
        rounding setting. The user must insure that these settings are the
        same or an error will result.

Returns:
        BERR_SUCCESS - Color matrix rounding was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
  
See Also:
        BGRC_Output_SetColorMatrix5x4,
        BGRC_Output_ToggleColorMatrix,
        BGRC_Source_SetColorMatrixRounding,
        BGRC_Destination_SetColorMatrixRounding
****************************************************************************/
BERR_Code BGRC_Output_SetColorMatrixRounding(
        BGRC_Handle hGrc,                   /* [in] Handle to GRC module. */
        BGRC_Rounding eMatrixRounding       /* [in] Matrix rounding selection. */
);

/***************************************************************************
Summary:
        Specifies the sub-rectangle of the output surface.

Description:
        Only the values within this rectangle will be used to store the
        compositor calculations. The values given here must be restricted
        to the size of the surface itself.

        The source rectangle, specified with BGRC_Source_SetRectangle will
        be scaled to the size of this output rectangle. Since the destination
        cannot be scaled, its rectangle specified with
        BGRC_Destination_SetRectangle must have the same with and height as
        the output rectangle.

        The default behavior is to use a rectangle the size of the entire
        specified output.

Returns:
        BERR_SUCCESS - Rectangle was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Source_SetRectangle,
        BGRC_Destination_SetRectangle
****************************************************************************/
BERR_Code BGRC_Output_SetRectangle(
        BGRC_Handle hGrc,                      /* [in] Handle to GRC module. */
        uint32_t ulLeft,                       /* [in] Rectangle left. */
        uint32_t ulTop,                        /* [in] Rectangle top. */
        uint32_t ulWidth,                      /* [in] Rectangle width. */
        uint32_t ulHeight                      /* [in] Rectangle height. */
);

/***************************************************************************
Summary:
        Determines the selection based on color key results to be customized.

Description:
        This function determines the final output of the blender by checking
        whether a specific pixel was color keyed by source or destination
        and using the result specified in this table.

        The following defaults are used:

        eSrcNotKeyedDstNotKeyed - BGRC_Output_ColorKeySelection_eTakeSource
        eSrcNotKeyedDstKeyed - BGRC_Output_ColorKeySelection_eTakeSource
        eSrcKeyedDstNotKeyed - BGRC_Output_ColorKeySelection_eTakeDestination
        eSrcKeyedDstKeyed - BGRC_Output_ColorKeySelection_eTakeDestination

Returns:
        BERR_SUCCESS - Selection based on color key was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Source_ToggleColorKey,
        BGRC_Destination_ToggleColorKey
****************************************************************************/
BERR_Code BGRC_Output_SetColorKeySelection(
        BGRC_Handle hGrc,         /* [in] Handle to GRC module. */             
        BGRC_Output_ColorKeySelection eSrcNotKeyedDstNotKeyed, /* [in] 
                Selection when neither source or destination is color keyed. */
        BGRC_Output_ColorKeySelection eSrcNotKeyedDstKeyed,    /* [in]
                Selection when source isn't color keyed but the destination is. */
        BGRC_Output_ColorKeySelection eSrcKeyedDstNotKeyed,    /* [in]
                Selection when source is color keyed but the destination isn't. */
        BGRC_Output_ColorKeySelection eSrcKeyedDstKeyed        /* [in]
                Selection when both source and destination are color keyed. */

);

/***************************************************************************
Summary:
        Enables dithering.

Description:
        Enables dithering of output pixels. 

        If dithering is enabled, a 2-dimensional dithering will be applied
        to adjust the channels in the output block based on the low 2 bits of
        the current X and Y position being written. 

        This is typically done to increase the perceived range of colors for
        a given resulting image.

        The default state is false.
  
Returns:
        BERR_SUCCESS - Constant alpha and color was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.

See Also:
        BGRC_Output_SetSurface,
****************************************************************************/
BERR_Code BGRC_Output_SetDither(
        BGRC_Handle hGrc,                     /* [in] Handle to GRC module.*/
        bool bEnableDither                    /* [in] If true, dither will be used.
                                                 If false, dither will not be
                                                                                         used. */
);

/***************************************************************************
Summary:
        Sets output blit direction.

Description:
        This function inverts the pixels of the surface in the specified
        direction(s), from right to left, and bottom to top.

        Defaults are false, left to right, and top to bottom.

Returns:
        BERR_SUCCESS - Direction was set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
        BERR_NOT_SUPPORTED - Not supported.
****************************************************************************/
BERR_Code BGRC_Output_SetDirection(
        BGRC_Handle hGrc,
        bool bRightToLeft,
        bool bBottomToTop
);

/***************************************************************************
Summary:
        Resets the state of the output.

Description:
        All state set by output functions is now set to be the default value.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Output_SetDefault
****************************************************************************/
BERR_Code BGRC_Output_ResetState(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

/***************************************************************************
Summary:
        Sets the default parameters for the output.

Description:
        Each output function has a default state associated with it, described
        in each of the functions used to modify that state. However, the user
        may wish to modify the default state so that future calls to 
        BGRC_Output_ResetState will use user defined values.
        
        This function allows you to change the default state. First the user
        calls functions to set the needed output state. It then calls
        this function which will then use the current state as the default.
        Subsequent calls to BGRC_Output_ResetState will use the new
        values.

Returns:
        BERR_SUCCESS - Default state now set.
        BERR_INVALID_PARAMETER - One of the input parameters was invalid.
  
See Also:
        BGRC_Output_ResetState
****************************************************************************/
BERR_Code BGRC_Output_SetDefault(
        BGRC_Handle hGrc                     /* [in] Handle to GRC module. */
);

#ifdef __cplusplus
}
#endif

#endif /* #ifndef BGRC_H__ */

/* end of file */