/*---------------------------------------------------------------------------* Copyright (C) 2010-2011 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. *---------------------------------------------------------------------------*/ // gx2RenderState.h // // Declares gx2RenderState-related types & functions for gx2 library. #ifndef _CAFE_GX2_RENDERSTATE_H_ #define _CAFE_GX2_RENDERSTATE_H_ #ifdef __cplusplus extern "C" { #endif // __cplusplus /// @addtogroup GX2RenderStateGroup /// @{ /// @addtogroup GX2RenderStateDepthStencilGroup /// @{ // ----------------- // GX2RenderState.h /// \brief Sets depth & stencil controls. /// /// \param depthEnable enables depth testing. if depthEnable is false, /// then all depth operations are disabled /// (depthWriteEnable is ignored), and color writes /// will not be affected 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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetDepthStencilControl(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 An alternate API to set depth-buffer controls and disable stencil. /// /// This function may be used to set the depth-buffer controls when stencil /// is not present or not needed. It always disables the stencil functions. /// If stencil control is needed, use \ref GX2SetDepthStencilControl. /// /// \note *Disables stencil*, sets depth control as specified. /// /// \param depthEnable enables depth testing. if depthEnable is false, /// then all depth operations are disabled /// (depthWriteEnable is ignored), and color writes /// will not be affected 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. /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetDepthOnlyControl(GX2Boolean depthEnable, GX2Boolean depthWriteEnable, GX2CompareFunction depthFunc); /// @} /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup /// @{ /// \brief Sets culling, front/back polygon modes, polygon offset enables. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetPolygonControl(GX2FrontFaceMode frontFaceMode, GX2Boolean cullFront, GX2Boolean cullBack, GX2Boolean enablePolygonModes, GX2PolygonMode polygonModeFront, GX2PolygonMode polygonModeBack, GX2Boolean polyOffsetFrontEnable, GX2Boolean polyOffsetBackEnable, GX2Boolean pointLineOffsetEnable); /// \brief An alternate API to set culling and disable offsets & front/back mode. /// /// \note *Disables offsets*, *disables front/back mode*, sets culling as specified. /// /// \param frontFaceMode front facing mode /// \param cullFront enables for front-face culling. /// \param cullBack enables for back-face culling. /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetCullOnlyControl(GX2FrontFaceMode frontFaceMode, GX2Boolean cullFront, GX2Boolean cullBack); /// @} /// @addtogroup GX2RenderStateDepthStencilGroup /// @{ /// \brief Set stencil mask, write mask, and reference values. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetStencilMask(u8 preMaskFront, u8 writeMaskFront, u8 refFront, u8 preMaskBack, u8 writeMaskBack, u8 refBack); /// @} /// @addtogroup GX2RenderStateRenderTargetGroup /// @{ /// \brief Set the hardware state to perform special accelerated operations. /// /// \param state Select special hardware state to enable/disable /// \param enable Enable/disable special hardware state /// /// \note Disabling \p GX2_SPECIAL_STATE_EXPAND_COLOR or /// \p GX2_SPECIAL_STATE_RESOLVE_COLOR also sets /// \ref GX2SetColorControl to the GX2 default state. /// /// \note Disabling \p GX2_SPECIAL_STATE_CLEAR also sets /// \ref GX2SetRasterizerClipControl to the GX2 default state. /// /// \warning Special states must be disabled to return the hardware /// to a normal rendering state. /// /// \warning Only a single special hardware state may be enabled at a time /// unless otherwise noted. The enabled state must be disabled /// in order to return to normal rendering operations. /// /// \clobberstate /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetSpecialState(GX2SpecialState state, GX2Boolean enable); /// \brief Set alpha test controls. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetAlphaTest(GX2Boolean alphaTestEnable, GX2CompareFunction alphaFunc, f32 ref); /// \brief Set the alpha to mask controls (used for screen-door transparency). /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetAlphaToMask(GX2Boolean alphaToMaskEnable, GX2AlphaToMaskMode mode); /// @} /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup /// @{ /// \brief Set polygon offset values (z-bias). /// /// Please refer to \ref GX2PolygonOffsetInfo for more information. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetPolygonOffset(f32 frontOffset, f32 frontSlopeScale, f32 backOffset, f32 backSlopeScale, f32 clamp); /// @} /// @addtogroup GX2RenderStateRenderTargetGroup /// @{ /// \brief Defines the color channels that will be written to for each render target. /// /// \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 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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetTargetChannelMasks(GX2ChannelMask target0, GX2ChannelMask target1, GX2ChannelMask target2, GX2ChannelMask target3, GX2ChannelMask target4, GX2ChannelMask target5, GX2ChannelMask target6, GX2ChannelMask target7); /// \brief Sets the quad-pipe (2x2) masks to be used for Multisample AA. /// /// \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 /// /// This affects how MSAA buffers are written by the quad-pipe. Each /// 2x2 region of screen aligned pixels has a separate 8-bit mask. /// /// Setting the mask disables writing to the given sample in the output /// MSAA buffer. This can be used for performance reasons. The default /// mask is 0xFF (enabled) for all quadrants. /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetAAMask(u8 upperLeftMask, u8 upperRightMask, u8 lowerLeftMask, u8 lowerRightMask); /// \brief Set logic ops, blend enables, color enable, and multi-write enable. /// /// \note Enabling multiwriteEnable is not compatible with dual-source blending /// (see \ref GX2SetBlendControl). /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetColorControl(GX2LogicOp lop, u8 blendEnableMask, GX2Boolean multiwriteEnable, GX2Boolean colorBufferEnable); /// \brief Set color and alpha blending controls (src, dst, etc.). /// /// \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 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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetBlendControl(GX2RenderTarget target, GX2BlendFunction colorSrcBlend, GX2BlendFunction colorDstBlend, GX2BlendCombine colorCombine, GX2Boolean separateAlphaBlend, GX2BlendFunction alphaSrcBlend, GX2BlendFunction alphaDstBlend, GX2BlendCombine alphaCombine); /// \brief Set the components of the constant blend color. /// /// \param red red /// \param green green /// \param blue blue /// \param alpha alpha /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetBlendConstantColor(f32 red, f32 green, f32 blue, f32 alpha); /// @} /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup /// @{ /// \brief Set the "diameter" of rasterized points (when not specified by a shader). /// /// Width and height are specified in pixels, with a precision of 1/8 pixel. /// /// \param width width of points /// \param height height of points /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetPointSize(f32 width, f32 height); /// \brief Set 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. /// /// \note the per-vertex point size or the value set by \ref GX2SetPointSize /// is clamped to the limits provided by this API. /// /// \param min limit min size of points /// \param max limit max size of points /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetPointLimits(f32 min, f32 max); /// \brief Set the width of rasterized lines. /// /// Width is specified in pixels, with a precision of 1/8 pixel. /// /// \param width width of lines /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetLineWidth(f32 width); /// \brief Set viewport and depth range. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetViewport(f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32 nearZ, f32 farZ); /// \brief Version of GX2SetViewport to call when Z output range is 0 < z < 1. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// GX2_INLINE void GX2SetViewportHalfZ(f32 xOrig, f32 yOrig, f32 wd, f32 ht, f32 nearZ, f32 farZ) { GX2SetViewport(xOrig, yOrig, wd, ht, (2*nearZ-farZ), farZ); } /// \brief Set scissor box. /// /// \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 \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetScissor(u32 xOrig, u32 yOrig, u32 wd, u32 ht); /// @} /// @addtogroup GX2RenderStatePrimitiveAssemblyGroup /// @{ /// \brief Enables the rasterizer and clipping /// /// \note If the rasterizer is disabled all operations after the geometry shader (or vertex shader /// if the geometry shader is not used) are disabled. This includes viewport transform and /// clipping. /// /// \param rasterizerEnable Enable for the rasterizer /// \param zClipEnable Enable ZNear and ZFar clipping /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetRasterizerClipControl(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable); /// \brief Enables the rasterizer and clipping options /// /// \note If the rasterizer is disabled all operations after the geometry shader (or vertex shader /// if the geometry shader is not used) are disabled. This includes viewport transform and /// clipping. /// /// \param rasterizerEnable Enable for the rasterizer /// \param zClipEnable Enable ZNear and ZFar clipping /// \param enableHalfSizeClipSpace Set normalized device coordinates to [0,1] for Z /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// void GX2API GX2SetRasterizerClipControlEx(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable, GX2Boolean enableHalfSizeClipSpace); /// \brief Deprecated synonym for \ref GX2SetRasterizerClipControlEx /// /// \deprecated This API name is deprecated. Please use \ref /// GX2SetRasterizerClipControlEx instead. /// /// \donotcall \gx2_typical \enddonotcall /// /// \writesgpu /// \alwayswritesgpu /// /// void GX2API GX2SetRasterizerClipControlHalfZ(GX2Boolean rasterizerEnable, GX2Boolean zClipEnable, GX2Boolean enableHalfSizeClipSpace); /// @} /// @} #ifdef __cplusplus } #endif // __cplusplus #endif // _CAFE_GX2_RENDERSTATE_H_