cafe/gx2/gx2RenderStateReg.h

/*---------------------------------------------------------------------------*

  Copyright (C) Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/

// gx2RenderStateReg.h
//
// Declares gx2RenderStateReg-related types & functions for gx2 library.

#ifndef _CAFE_GX2_RENDERSTATE_REG_H_
#define _CAFE_GX2_RENDERSTATE_REG_H_

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

/// @addtogroup GX2RenderStateRegGroup
/// @{

// -----------------
// GX2RenderStateReg.h

/// \brief Structure for depth & stencil controls register.
///
typedef struct{
    u32 reg;
}GX2DepthStencilControlReg;

/// \brief Structure for culling, front/back polygon modes, polygon offset controls register.
///
typedef struct{
    u32 reg;
}GX2PolygonControlReg;

/// \brief Structure for stencil mask controls registers.
///
typedef struct{
    u32 reg[2];
}GX2StencilMaskReg;

/// \brief Structure for alpha test controls registers.
///
typedef struct{
    u32 reg[2];
}GX2AlphaTestReg;

/// \brief Structure for alpha to mask controls register.
///
typedef struct{
    u32 reg;
}GX2AlphaToMaskReg;

/// \brief Structure for polygon offset controls registers.
///
typedef struct{
    union {
        u32 u32All;
        f32 f32All;
    } reg[5];
}GX2PolygonOffsetReg;

/// \brief Structure for target channel mask register.
///
typedef struct{
    u32 reg;
}GX2TargetChannelMaskReg;

/// \brief Structure for AA mask register.
///
typedef struct{
    u32 reg;
}GX2AAMaskReg;

/// \brief Structure for color control register.
///
typedef struct{
    u32 reg;
}GX2ColorControlReg;

/// \brief Structure for blend control registers.
///
typedef struct{
    u32 reg[2];
}GX2BlendControlReg;

/// \brief Structure for blend constant color registers.
///
typedef struct{
    union {
        u32 u32All;
        f32 f32All;
    } reg[4];
}GX2BlendConstantColorReg;

/// \brief Structure for point size register.
///
typedef struct{
    u32 reg;
}GX2PointSizeReg;

/// \brief Structure for point limits register.
///
typedef struct{
    u32 reg;
}GX2PointLimitsReg;

/// \brief Structure for line width register.
///
typedef struct{
    u32 reg;
}GX2LineWidthReg;

/// \brief Structure for viewport registers.
///
typedef struct{
    union {
        u32 u32All;
        f32 f32All;
    } reg[12];
}GX2ViewportReg;

/// \brief Structure for scissor registers.
///
typedef struct{
    u32 reg[2];
}GX2ScissorReg;


/// \brief Function to update depth & stencil controls state.
///
/// \param pState            Pointer to GX2DepthStencilControlReg structure to update.
/// \param depthEnable       enables depth testing. if depthEnable is false,
///                          then all depth operations are disabled
///                          (depthWriteEnable is ignored), and color writes
///                          will not be impacted by the depth test.
/// \param depthWriteEnable  enables writing to the depth buffer
///                          if the depth test passes.
/// \param depthFunc         function that compares the depth at each sample
///                          in the fragment to the destination depth at the
///                          corresponding sample point.
/// \param stencilTestEnable enables stencil testing. if disabled, all pixels
///                          pass the stencil test. If there is no stencil
///                          buffer this is treated as disabled.
/// \param backStencilEnable if false, forces all quads to be stencil tested
///                          as frontface quads.
/// \param frontStencilFunc  function that compares stencil reference value to
///                          the destination stencil value for frontface quads.
/// \param frontStencilZPass stencil operation for frontface quads if the
///                          stencil and depth functions both pass.
/// \param frontStencilZFail stencil operation for frontface quads if the
///                          stencil function passes and the depth function
///                          fails.
/// \param frontStencilFail  stencil operation for frontface quads if the
///                          stencil function fails.
/// \param backStencilFunc   function that compares backface stencil reference
///                          value to the destination stencil value for
///                          backface quads.
/// \param backStencilZPass  stencil operation for backface quads if the
///                          stencil and depth functions both pass.
/// \param backStencilZFail  stencil operation for backface quads if the
///                          stencil function passes and the depth function
///                          fails.
/// \param backStencilFail   stencil operation for backface quads if the
///                          stencil function fails.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitDepthStencilControlReg(GX2DepthStencilControlReg *pState,
                                   GX2Boolean depthEnable,
                                   GX2Boolean depthWriteEnable,
                                   GX2CompareFunction depthFunc,
                                   GX2Boolean stencilTestEnable,
                                   GX2Boolean backStencilEnable,

                                   GX2CompareFunction frontStencilFunc,
                                   GX2StencilFunction frontStencilZPass,
                                   GX2StencilFunction frontStencilZFail,
                                   GX2StencilFunction frontStencilFail,

                                   GX2CompareFunction backStencilFunc,
                                   GX2StencilFunction backStencilZPass,
                                   GX2StencilFunction backStencilZFail,
                                   GX2StencilFunction backStencilFail);

/// \brief Function to get depth & stencil controls state.
///
/// \param pState             Pointer to GX2DepthStencilControlReg structure to unpack.
/// \param pDepthEnable       Pointer to store depth testing state.
/// \param pDepthWriteEnable  Pointer to store writing to the depth buffer state.
/// \param pDepthFunc         Pointer to store depth function state.
/// \param pStencilTestEnable Pointer to store stencil testing state.
/// \param pBackStencilEnable Pointer to store back stencil testing state.
/// \param pFrontStencilFunc  Pointer to store stencil func state.
/// \param pFrontStencilZPass Pointer to store stencil z pass state.
/// \param pFrontStencilZFail Pointer to store stencil z fail state.
/// \param pFrontStencilFail  Pointer to store stencil fail state.
/// \param pBackStencilFunc   Pointer to store back stencil func state.
/// \param pBackStencilZPass  Pointer to store back stencil z pass state.
/// \param pBackStencilZFail  Pointer to store back stencil z fail.
/// \param pBackStencilFail   Pointer to store back stencil fail state.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetDepthStencilControlReg(const GX2DepthStencilControlReg *pState,
                                   GX2Boolean *pDepthEnable,
                                   GX2Boolean *pDepthWriteEnable,
                                   GX2CompareFunction *pDepthFunc,
                                   GX2Boolean *pStencilTestEnable,
                                   GX2Boolean *pBackStencilEnable,
                                   GX2CompareFunction *pFrontStencilFunc,
                                   GX2StencilFunction *pFrontStencilZPass,
                                   GX2StencilFunction *pFrontStencilZFail,
                                   GX2StencilFunction *pFrontStencilFail,
                                   GX2CompareFunction *pBackStencilFunc,
                                   GX2StencilFunction *pBackStencilZPass,
                                   GX2StencilFunction *pBackStencilZFail,
                                   GX2StencilFunction *pBackStencilFail);

/// \brief Sets depth & stencil controls registers.
/// \param pState Pointer to GX2DepthStencilControlReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetDepthStencilControlReg(const GX2DepthStencilControlReg *pState);

/// \brief Function to update culling, front/back polygon modes, polygon offset enables state.
///
/// \param pState                Pointer to GX2PolygonControlReg structure to update.
/// \param frontFaceMode         front facing mode
/// \param cullFront             enables for front-face culling.
/// \param cullBack              enables for back-face culling.
/// \param enablePolygonModes    enables polygon mode.
/// \param polygonModeFront      mode to render front-facing polygons
/// \param polygonModeBack       mode to render back-facing polygons.
/// \param polyOffsetFrontEnable enables front facing polygon offset.
/// \param polyOffsetBackEnable  enables back facing polygon offset.
/// \param pointLineOffsetEnable enables polygon offset for non-triangle
///                              primitives.
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitPolygonControlReg(GX2PolygonControlReg *pState,
                                GX2FrontFaceMode frontFaceMode,
                                GX2Boolean cullFront,
                                GX2Boolean cullBack,

                                GX2Boolean     enablePolygonModes,
                                GX2PolygonMode polygonModeFront,
                                GX2PolygonMode polygonModeBack,

                                GX2Boolean polyOffsetFrontEnable,
                                GX2Boolean polyOffsetBackEnable,
                                GX2Boolean pointLineOffsetEnable);

/// \brief Function to get culling, front/back polygon modes, polygon offset enables state.
///
/// \param pState                 Pointer to GX2PolygonControlReg structure to update.
/// \param pFrontFaceMode         Pointer to store front facing mode.
/// \param pCullFront             Pointer to store front-face culling state.
/// \param pCullBack              Pointer to store back-face culling state.
/// \param pEnablePolygonModes    Pointer to store polygon mode.
/// \param pPolygonModeFront      Pointer to store mode to render front-facing polygons
/// \param pPolygonModeBack       Pointer to store mode to render back-facing polygons.
/// \param pPolyOffsetFrontEnable Pointer to store facing polygon offset state.
/// \param pPolyOffsetBackEnable  Pointer to store back facing polygon offset state.
/// \param pPointLineOffsetEnable Pointer to store polygon offset for non-triangle
///                               primitives state.
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetPolygonControlReg(const GX2PolygonControlReg *pState,
                                GX2FrontFaceMode *pFrontFaceMode,
                                GX2Boolean *pCullFront,
                                GX2Boolean *pCullBack,

                                GX2Boolean     *pEnablePolygonModes,
                                GX2PolygonMode *pPolygonModeFront,
                                GX2PolygonMode *pPolygonModeBack,

                                GX2Boolean *pPolyOffsetFrontEnable,
                                GX2Boolean *pPolyOffsetBackEnable,
                                GX2Boolean *pPointLineOffsetEnable);

/// \brief Sets culling, front/back polygon modes, polygon offset enables registers.
/// \param pState Pointer to GX2PolygonControlReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetPolygonControlReg(const GX2PolygonControlReg *pState);

/// \brief Function to update stencil mask state.
///
/// \param pState          Pointer to GX2StencilMaskReg structure to update.
/// \param preMaskFront    mask used with the reference and current stencil values
///                        prior to doing the stencil test for front-facing pixels
/// \param writeMaskFront  mask used when writing to the stencil buffer for
///                        front-facing pixels
/// \param refFront        reference stencil value for front-facing pixels
/// \param preMaskBack     the mask used with the reference and current stencil values
///                        prior to doing the stencil test for back-facing pixels
/// \param writeMaskBack   mask used when writing to the stencil buffer for
///                        back-facing pixels
/// \param refBack         reference stencil value for back-facing pixels
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitStencilMaskReg(GX2StencilMaskReg *pState,
                           u8 preMaskFront,
                           u8 writeMaskFront,
                           u8 refFront,
                           u8 preMaskBack,
                           u8 writeMaskBack,
                           u8 refBack);

/// \brief Function to get stencil mask state.
///
/// \param pState          Pointer to GX2StencilMaskReg structure to unpack.
/// \param pPreMaskFront   Pointer to store the stencil test state for front-facing pixels.
/// \param pWriteMaskFront Pointer to store mask state used when writing to the stencil buffer for
///                        front-facing pixels
/// \param pRefFront       Pointer to store reference stencil value for front-facing pixels
/// \param pPreMaskBack    Pointer to store mask state used with the reference and current stencil values
///                        prior to doing the stencil test for back-facing pixels
/// \param pWriteMaskBack  Pointer to store mask sate used when writing to the stencil buffer for
///                        back-facing pixels
/// \param pRefBack        Pointer to store reference stencil value for back-facing pixels
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetStencilMaskReg(const GX2StencilMaskReg *pState,
                           u8 *pPreMaskFront,
                           u8 *pWriteMaskFront,
                           u8 *pRefFront,
                           u8 *pPreMaskBack,
                           u8 *pWriteMaskBack,
                           u8 *pRefBack);

/// \brief Set stencil mask registers.
/// \param pState Pointer to GX2StencilMaskReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetStencilMaskReg(const GX2StencilMaskReg *pState);

/// \brief Function to update alpha-test-control state.
///
/// \param pState Pointer to GX2AlphaTestReg structure to update
/// \param alphaTestEnable Enable if GX2_ENABLE, Disable if GX2_DISABLE
/// \param alphaFunc Compare Function for alpha testing
/// \param ref Reference value for alpha testing
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitAlphaTestReg(GX2AlphaTestReg *pState,
                         GX2Boolean alphaTestEnable,
                         GX2CompareFunction alphaFunc,
                         f32 ref);

/// \brief Function to get alpha-test-control state.
///
/// \param pState Pointer to GX2AlphaTestReg structure to unpack
/// \param pAlphaTestEnable   Pointer to store alpha test state,
/// \param pAlphaFunc Compare Pointer to store function for alpha testing
/// \param pRef               Pointer to store reference value for alpha testing
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetAlphaTestReg(const GX2AlphaTestReg *pState,
                         GX2Boolean *pAlphaTestEnable,
                         GX2CompareFunction *pAlphaFunc,
                         f32 *pRef);

/// \brief Set alpha-test-control registers.
/// \param pState Pointer to GX2AlphaTestReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetAlphaTestReg(const GX2AlphaTestReg *pState);

/// \brief Function to update screen-door transparency state.
///
/// \param pState Pointer to GX2AlphaToMaskReg structure to update
/// \param alphaToMaskEnable if enabled, the sample mask is ANDed with a mask
///                          produced from the alpha value.
/// \param mode Mode for the alpha mask.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitAlphaToMaskReg(GX2AlphaToMaskReg *pState,
                           GX2Boolean alphaToMaskEnable,
                           GX2AlphaToMaskMode mode);

/// \brief Function to get screen-door transparency state.
///
/// \param pState Pointer to GX2AlphaToMaskReg structure to unpack
/// \param pAlphaToMaskEnable Pointer to store mask state.
/// \param pMode Pointer to store mode for the alpha mask.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetAlphaToMaskReg(const GX2AlphaToMaskReg *pState,
                           GX2Boolean *pAlphaToMaskEnable,
                           GX2AlphaToMaskMode *pMode);

/// \brief Set screen-door transparency registers.
/// \param pState Pointer to GX2AlphaToMaskReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetAlphaToMaskReg(const GX2AlphaToMaskReg *pState);

/// \brief Function to update polygon-offset state.
///
/// Please refer to \ref GX2PolygonOffsetInfo for more information.
///
/// \param pState       Pointer to GX2PolygonOffsetReg structure to update.
/// \param frontOffset  offset value for front-facing polygons
/// \param frontSlopeScale  slope scale value for front-facing polygons
/// \param backOffset   offset value for back-facing polygons
/// \param backSlopeScale   slope scale value for back-facing polygons
/// \param clamp        maximum (if positive) or minimum
///                         (if negative) value for the final offset, ignored if 0
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitPolygonOffsetReg(GX2PolygonOffsetReg *pState,
                             f32 frontOffset, f32 frontSlopeScale,
                             f32 backOffset,  f32 backSlopeScale,  f32 clamp);

/// \brief Function to get polygon-offset state.
///
/// \param pState       Pointer to GX2PolygonOffsetReg structure to unpack.
/// \param pFrontOffset Pointer to store offset value for front-facing polygons
/// \param pFrontSlopeScale Pointer to store offset scale value for front-facing polygons
/// \param pBackOffset  Pointer to store offset value for back-facing polygons
/// \param pBackSlopeScale  Pointer to store offset scale value for back-facing polygons
/// \param pClamp       Pointer to store maximum (if positive) or minimum
///                     (if negative) value for the final offset
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetPolygonOffsetReg(const GX2PolygonOffsetReg *pState,
                             f32 *pFrontOffset, f32 *pFrontSlopeScale,
                             f32 *pBackOffset,  f32 *pBackSlopeScale,  f32 *pClamp);

/// \brief Set polygon-offset registers.
/// \param pState Pointer to GX2PolygonOffsetReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetPolygonOffsetReg(const GX2PolygonOffsetReg *pState);

/// \brief Function to update color channels state.
///
/// \param pState  Pointer to GX2TargetChannelMaskReg structure to update.
/// \param target0 positive mask for writing to MRT 0 components.
/// \param target1 positive mask for writing to MRT 1 components.
/// \param target2 positive mask for writing to MRT 2 components.
/// \param target3 positive mask for writing to MRT 3 components.
/// \param target4 positive mask for writing to MRT 4 components.
/// \param target5 positive mask for writing to MRT 5 components.
/// \param target6 positive mask for writing to MRT 6 components.
/// \param target7 positive mask for writing to MRT 7 components.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitTargetChannelMasksReg(GX2TargetChannelMaskReg *pState,
                                   GX2ChannelMask target0,
                                   GX2ChannelMask target1,
                                   GX2ChannelMask target2,
                                   GX2ChannelMask target3,
                                   GX2ChannelMask target4,
                                   GX2ChannelMask target5,
                                   GX2ChannelMask target6,
                                   GX2ChannelMask target7);

/// \brief Function to get color channels state.
///
/// \param pState   Pointer to GX2TargetChannelMaskReg structure to unpack.
/// \param pTarget0 Pointer to store positive mask for writing to MRT 0 components.
/// \param pTarget1 Pointer to store positive mask for writing to MRT 1 components.
/// \param pTarget2 Pointer to store positive mask for writing to MRT 2 components.
/// \param pTarget3 Pointer to store positive mask for writing to MRT 3 components.
/// \param pTarget4 Pointer to store positive mask for writing to MRT 4 components.
/// \param pTarget5 Pointer to store positive mask for writing to MRT 5 components.
/// \param pTarget6 Pointer to store positive mask for writing to MRT 6 components.
/// \param pTarget7 Pointer to store positive mask for writing to MRT 7 components.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetTargetChannelMasksReg(const GX2TargetChannelMaskReg *pState,
                                   GX2ChannelMask *pTarget0,
                                   GX2ChannelMask *pTarget1,
                                   GX2ChannelMask *pTarget2,
                                   GX2ChannelMask *pTarget3,
                                   GX2ChannelMask *pTarget4,
                                   GX2ChannelMask *pTarget5,
                                   GX2ChannelMask *pTarget6,
                                   GX2ChannelMask *pTarget7);

/// \brief Set which color channels will be written to for each render target registers.
///
/// \note The set of enabled targets is controlled by both the number of
///       shader outputs as well as these values (and by multiwriteEnable,
///       \ref GX2SetColorControl).
///       It's probably a good idea to disable unused targets here.
///
/// \note Using MRTs is not compatible with dual-source blending
///       (see \ref GX2SetBlendControl).  For dual-source blending,
///       only target0 needs to be enabled.
///
/// \param pState Pointer to GX2TargetChannelMaskReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetTargetChannelMasksReg(const GX2TargetChannelMaskReg *pState);

/// \brief Function to update AA mask state.
///
/// \param pState  Pointer to GX2AAMaskReg structure to update.
/// \param upperLeftMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
/// \param upperRightMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
/// \param lowerLeftMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
/// \param lowerRightMask contains an 8-bit mask, LSB is Sample0, MSB is Sample7
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitAAMaskReg(GX2AAMaskReg *pState,
                             u8 upperLeftMask,
                             u8 upperRightMask,
                             u8 lowerLeftMask,
                             u8 lowerRightMask);

/// \brief Function to get AA mask state.
///
/// \param pState   Pointer to GX2AAMaskReg structure to unpack.
/// \param pUpperLeftMask Pointer to store 8-bit mask
/// \param pUpperRightMask Pointer to store 8-bit mask
/// \param pLowerLeftMask Pointer to store 8-bit mask
/// \param pLowerRightMask Pointer to store 8-bit mask
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetAAMaskReg(const GX2AAMaskReg *pState,
                            u8 *pUpperLeftMask,
                            u8 *pUpperRightMask,
                            u8 *pLowerLeftMask,
                            u8 *pLowerRightMask);

/// \brief Sets the 4 masks to be used for Multisample AA.  The masks are
/// applied to each set of 2x2 screen-aligned pixels.
///
/// \param pState Pointer to GX2AAMaskReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetAAMaskReg(const GX2AAMaskReg *pState);

/// \brief Function to update color-control state.
///
/// \param pState Pointer to GX2ColorControlReg structure.
/// \param lop  a logical operation that describes how source & dest are combined.
///      Logic op is mutually exclusive with blending.  The lop must be GX2_LOGIC_OP_COPY
///      if ANY blending is enabled (if blendEnableMask is not 0).
/// \param blendEnableMask   an 8-bit mask that enables blending per render target.
/// \param multiwriteEnable  if true, the output of MRT 0 is sent to all MRTs.
/// \param colorBufferEnable enables drawing to the color buffer.
///      The colorBufferEnable should be set to GX2_DISABLE for optimal performance when doing
///      Z only rendering.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitColorControlReg(GX2ColorControlReg *pState,
                             GX2LogicOp  lop,
                             u8          blendEnableMask,
                             GX2Boolean  multiwriteEnable,
                             GX2Boolean  colorBufferEnable);

/// \brief Function to get color-control state.
///
/// \param pState Pointer to GX2ColorControlReg structure.
/// \param pLop   Pointer to store a logical operation that describes how source & dest are combined.
/// \param pBlendEnableMask   Pointer to store an 8-bit mask that enables blending per render target.
/// \param pMultiwriteEnable  Pointer to store state for multi write.
/// \param pColorBufferEnable Pointer to store state for drawing to color buffer.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetColorControlReg(const GX2ColorControlReg *pState,
                             GX2LogicOp  *pLop,
                             u8          *pBlendEnableMask,
                             GX2Boolean  *pMultiwriteEnable,
                             GX2Boolean  *pColorBufferEnable);

/// \brief Set color-control registers.
///
/// \note Enabling multiwriteEnable is not compatible with dual-source blending
///       (see \ref GX2SetBlendControl).
///
/// \param pState Pointer to GX2ColorControlReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetColorControlReg(const GX2ColorControlReg *pState);

/// \brief Function to update blend-control state.
///
/// \param pState         Pointer to GX2BlendControlReg structure to update.
/// \param target         render target to set blend controls for
/// \param colorSrcBlend  source blend function for color components
/// \param colorDstBlend  destination blend function for color components
/// \param colorCombine   source/dest combination function for color components
/// \param separateAlphaBlend  if true, use the following fields for alpha blend.
///                            if false, use the color fields for alpha blend.
/// \param alphaSrcBlend  source blend function for alpha
/// \param alphaDstBlend  destination blend function for alpha
/// \param alphaCombine   source/dest combination function for alpha
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitBlendControlReg(GX2BlendControlReg *pState,
                             GX2RenderTarget target,
                             GX2BlendFunction colorSrcBlend,
                             GX2BlendFunction colorDstBlend,
                             GX2BlendCombine  colorCombine,
                             GX2Boolean       separateAlphaBlend,
                             GX2BlendFunction alphaSrcBlend,
                             GX2BlendFunction alphaDstBlend,
                             GX2BlendCombine  alphaCombine);

/// \brief Function to get blend-control state.
///
/// \param pState          Pointer to GX2BlendControlReg structure to unpack.
/// \param pTarget         Pointer to store render target
/// \param pColorSrcBlend  Pointer to store source blend function for color components
/// \param pColorDstBlend  Pointer to store destination blend function for color components
/// \param pColorCombine   Pointer to store source/dest combination function for color components
/// \param pSeparateAlphaBlend  Pointer to store separate alpha blend state.
/// \param pAlphaSrcBlend  Pointer to store source blend function for alpha
/// \param pAlphaDstBlend  Pointer to store destination blend function for alpha
/// \param pAlphaCombine   Pointer to store source/dest combination function for alpha
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetBlendControlReg(const GX2BlendControlReg *pState,
                             GX2RenderTarget *pTarget,
                             GX2BlendFunction *pColorSrcBlend,
                             GX2BlendFunction *pColorDstBlend,
                             GX2BlendCombine  *pColorCombine,
                             GX2Boolean       *pSeparateAlphaBlend,
                             GX2BlendFunction *pAlphaSrcBlend,
                             GX2BlendFunction *pAlphaDstBlend,
                             GX2BlendCombine  *pAlphaCombine);

/// \brief Set blend-control registers.
///
/// \note Using a blend function that includes source 1 implies dual-source blending.
///       This is mutually exclusive with MRTs.  It is also not compatible
///       with multiwriteEnable (\ref GX2SetColorControl).
///       It requires a pixel shader with 2 color output channels
///       (gl_FragData[0] and gl_FragData[1]).
///
/// \param pState Pointer to GX2BlendControlReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetBlendControlReg(const GX2BlendControlReg *pState);

/// \brief Function to update the components of the constant blend color.
///
/// \param pState Pointer to GX2BlendConstantColorReg structure to update.
/// \param red   red
/// \param green green
/// \param blue  blue
/// \param alpha alpha
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitBlendConstantColorReg(GX2BlendConstantColorReg *pState,
                                   f32 red, f32 green, f32 blue, f32 alpha);

/// \brief Function to get the components of the constant blend color.
///
/// \param pState Pointer to GX2BlendConstantColorReg structure to unpack.
/// \param pRed   Pointer to store red value
/// \param pGreen Pointer to store green value
/// \param pBlue  Pointer to store blue value
/// \param pAlpha Pointer to store alpha value
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetBlendConstantColorReg(const GX2BlendConstantColorReg *pState,
                                   f32 *pRed, f32 *pGreen, f32 *pBlue, f32 *pAlpha);

/// \brief Set the components of the constant blend color registers.
///
/// \param pState Pointer to GX2BlendConstantColorReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetBlendConstantColorReg(const GX2BlendConstantColorReg *pState);

/// \brief Function to update the point size.
///
/// Width and height are specified in pixels, with a precision of 1/8 pixel.
///
/// \param pState Pointer to GX2PointSizeReg structure to update.
/// \param width Width of points
/// \param height Height of points
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitPointSizeReg(GX2PointSizeReg *pState,
                          f32 width, f32 height);

/// \brief Function to get the point size.
///
/// \param pState Pointer to GX2PointSizeReg structure to unpack
/// \param pWidth Pointer to store width of points
/// \param pHeight Pointer to store height of points
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetPointSizeReg(const GX2PointSizeReg *pState,
                          f32 *pWidth, f32 *pHeight);

/// \brief Set the "diameter" of rasterized points registers.
///
/// \param pState Pointer to GX2PointSizeReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetPointSizeReg(const GX2PointSizeReg *pState);

/// \brief Function to update the minimum & maximum point sizes
/// (when specified by a shader, for instance).
///
/// Width and height are specified in pixels, with a precision of 1/8 pixel.
///
/// \param pState Pointer to GX2PointLimitsReg structure to update.
/// \param min limit min size of points
/// \param max limit max size of points
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitPointLimitsReg(GX2PointLimitsReg *pState,
                            f32 min, f32 max);

/// \brief Function to get the minimum & maximum point sizes
///
/// \param pState Pointer to GX2PointLimitsReg structure to unpack.
/// \param pMin Pointer to store limit min size of points
/// \param pMax Pointer to store limit max size of points
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetPointLimitsReg(const GX2PointLimitsReg *pState,
                            f32 *pMin, f32 *pMax);

/// \brief Set the minimum & maximum point sizes registers.
///
/// \param pState Pointer to GX2PointLimitsReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetPointLimitsReg(const GX2PointLimitsReg *pState);

/// \brief Function to update the width of rasterized lines.
///
/// Width is specified in pixels, with a precision of 1/8 pixel.
///
/// \param pState Pointer to GX2LineWidthReg structure to update.
/// \param width Width of lines.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitLineWidthReg(GX2LineWidthReg *pState,
                          f32 width);

/// \brief Function to get the width of rasterized lines.
///
/// \param pState Pointer to GX2LineWidthReg structure to unpack.
/// \param pWidth Pointer to store width of lines
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetLineWidthReg(const GX2LineWidthReg *pState,
                          f32 *pWidth);

/// \brief Set the width of rasterized lines registers
///
/// \param pState Pointer to GX2LineWidthReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetLineWidthReg(const GX2LineWidthReg *pState);

/// \brief Function to update viewport and depth range.
///
/// \param pState Pointer to GX2ViewportReg structure to update.
/// \param xOrig orig x point of viewport
/// \param yOrig orig y point of viewport
/// \param wd width of viewport
/// \param ht height of viewport
/// \param nearZ near range of depth (typically 0.0)
/// \param farZ far range of depth (typically 1.0)
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitViewportReg(GX2ViewportReg *pState,
                         f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32 nearZ, f32 farZ);

/// \brief Version of GX2InitViewportReg to call when Z output range is 0 < z < 1.
///
/// \param pState Pointer to GX2ViewportReg structure to update.
/// \param xOrig orig x point of viewport
/// \param yOrig orig y point of viewport
/// \param wd width of viewport
/// \param ht height of viewport
/// \param nearZ near range of depth (typically 0.0)
/// \param farZ far range of depth (typically 1.0)
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2InitViewportRegHalfZ(GX2ViewportReg *pState,
                         f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32 nearZ, f32 farZ)
{
    GX2InitViewportReg(pState, xOrig, yOrig, wd, ht, (2*nearZ-farZ), farZ);
}

/// \brief Function to get viewport and depth range.
///
/// \param pState Pointer to GX2ViewportReg structure to update.
/// \param pXOrig Pointer to store orig x point of viewport
/// \param pYOrig Pointer to store orig y point of viewport
/// \param pWd Pointer to store width of viewport
/// \param pHt Pointer to store height of viewport
/// \param pNearZ Pointer to store near range of depth
/// \param pFarZ Pointer to store far range of depth
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetViewportReg(const GX2ViewportReg *pState,
                         f32 *pXOrig, f32 *pYOrig, f32 *pWd, f32 *pHt, f32 *pNearZ, f32 *pFarZ);


// \brief Version of GX2GetViewportReg to call when Z output range is 0 < z < 1.
///
/// \param pState Pointer to GX2ViewportReg structure to update.
/// \param pXOrig Pointer to store orig x point of viewport
/// \param pYOrig Pointer to store orig y point of viewport
/// \param pWd Pointer to store width of viewport
/// \param pHt Pointer to store height of viewport
/// \param pNearZ Pointer to store near range of depth
/// \param pFarZ Pointer to store far range of depth
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2GetViewportRegHalfZ(const GX2ViewportReg *pState,
                        f32 *pXOrig, f32 *pYOrig, f32 *pWd, f32 *pHt, f32 *pNearZ, f32 *pFarZ)
{
    GX2GetViewportReg(pState, pXOrig, pYOrig, pWd, pHt, pNearZ, pFarZ);
    *pNearZ = (*pNearZ  + *pFarZ) * 0.5f;
}

/// \brief Set viewport and depth range registers.
///
/// \param pState Pointer to GX2ViewportReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetViewportReg(const GX2ViewportReg *pState);


// \brief Version of GX2SetViewportReg to call when Z output range is 0 < z < 1.
// \note  This is identical to GX2SetViewportReg.  Only created for naming consistency.
///
/// \param pState Pointer to GX2ViewportReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2SetViewportRegHalfZ(const GX2ViewportReg *pState) {
    GX2SetViewportReg(pState);
}

/// \brief Function to update scissor box.
///
/// \param pState Pointer to GX2ScissorReg structure to update.
/// \param xOrig orig x point of scissor box
/// \param yOrig orig y point of scissor box
/// \param wd width of scissor box
/// \param ht height of scissor box
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2InitScissorReg(GX2ScissorReg *pState,
                        u32 xOrig, u32 yOrig, u32 wd, u32 ht);

/// \brief Function to get scissor box.
///
/// \param pState Pointer to GX2ScissorReg structure to unpack.
/// \param pXOrig orig x point of scissor box
/// \param pYOrig orig y point of scissor box
/// \param pWd width of scissor box
/// \param pHt height of scissor box
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void GX2API GX2GetScissorReg(const GX2ScissorReg *pState,
                        u32 *pXOrig, u32 *pYOrig, u32 *pWd, u32 *pHt);

/// \brief Set scissor box registers.
///
/// \param pState Pointer to GX2ScissorReg structure.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2API GX2SetScissorReg(const GX2ScissorReg *pState);

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _CAFE_GX2_RENDERSTATE_REG_H_