cafe/gx2ut/gx2utClear.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.

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

#ifndef _GX2UTCLEAR_H_
#define _GX2UTCLEAR_H_

// Note: Currently this header depends on gx2.h being included first to define
// types like s32 and structures like GX2Surface.

// Need GX2UTRect struct; this pulls in gx2.h also
#include "gx2utCopy.h"

#ifdef __cplusplus
extern "C" {
#endif

/// @addtogroup GX2UTClearSurfaceGroup
/// @{

/// \brief Setup all of the constant render state needed for GX2UT clears
///
/// \param enable Enable or disable the state
///
/// This enables and disables the state used by \ref GX2UTClearRectOp and
/// \ref GX2UTClearRectOp. After finishing all clear operations, it is
/// necessary to call this function to disable the clear state and set any
/// changed state to the GX2 default state. A smaller yet equivalent routine
/// can be written using knowledge of the application's desired state. To
/// customize the state that is restored, refer to the library source
/// (src/lib/gx2ut/gx2utClear.cpp).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetClearState(GX2Boolean enable);

/// \brief Performs a sub-rectangle clear operation on the buffers.
///
/// \param colorBuffer Color buffer to clear (can be NULL).
/// \param depthBuffer Depth buffer to clear (can be NULL).
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
/// \param dstRect     Pointer to the destination region to clear.
///
/// This function assumes \ref GX2UTSetClearState()
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// Clears a region of a surface as specified by dstRect. The rect dimensions
/// should be relative to the mipmap level dimensions, not the base level
/// dimensions.
///
/// This clears a color/depth buffer in the same way as \ref GX2ClearColor
/// and \ref GX2ClearDepthStencil. It changes the currently bound VS/PS
/// shaders, GX2_RENDER_TARGET0, depth buffer, and Scissor/Viewport
/// settings. In addition it overwrites VS uniform locations 0-3 and PS uniform
/// location 0, and it changes the \ref GX2SetShaderMode to
/// \ref GX2_SHADER_MODE_UNIFORM_REGISTER.
///
/// \note It is not necessary to call \ref GX2Invalidate on the color/depth
///       buffer being cleared. This is done internally.
///
/// \note This clear, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init() time. To avoid this,
///       call this clear function from a separate state context with
///       profiling disabled. See \ref GX2SetupContextStateEx() for more
///       information.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTClearRectOp(GX2ColorBuffer *colorBuffer, GX2DepthBuffer *depthBuffer,
                      f32 r, f32 g, f32 b, f32 a, f32 depthClear, u8 stencilClear,
                      GX2ClearMode clearFlags, GX2HiStencilInfo *hiStencil, GX2UTRect *dstRect);

/// \brief Performs a clear operation on the buffers.
///
/// \param colorBuffer Color buffer to clear (can be NULL).
/// \param depthBuffer Depth buffer to clear (can be NULL).
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
///
/// This function assumes \ref GX2UTSetClearState()
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This clears a color/depth buffer in the same way as \ref GX2ClearColor
/// and \ref GX2ClearDepthStencil. It modifies the currently bound VS/PS
/// shaders, GX2_RENDER_TARGET0, depth buffer, and Scissor/Viewport
/// settings. In addition it overwrites VS uniform locations 0-3 and PS uniform
/// location 0, and it changes the \ref GX2SetShaderMode to
/// \ref GX2_SHADER_MODE_UNIFORM_REGISTER.
///
/// \note It is not necessary to call \ref GX2Invalidate on the color/depth
///       buffer being cleared. This is done internally.
///
/// \note This clear, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init() time. To avoid this,
///       call this clear function from a separate state context with
///       profiling disabled. See \ref GX2SetupContextStateEx() for more
///       information.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearOp(GX2ColorBuffer *colorBuffer,
                             GX2DepthBuffer *depthBuffer,
                             f32 r, f32 g, f32 b, f32 a,
                             f32 depthClear, u8 stencilClear,
                             GX2ClearMode clearFlags,
                             GX2HiStencilInfo *hiStencil)
{
    GX2UTRect dstRect = {0};

    ASSERT(colorBuffer || depthBuffer);

    if (colorBuffer)
    {
        dstRect.right = GX2Max(1, colorBuffer->surface.width >> colorBuffer->viewMip);
        dstRect.bottom = GX2Max(1, colorBuffer->surface.height >> colorBuffer->viewMip);
    }
    else
    {
        dstRect.right = GX2Max(1, depthBuffer->surface.width >> depthBuffer->viewMip);
        dstRect.bottom = GX2Max(1, depthBuffer->surface.height >> depthBuffer->viewMip);
    }

    GX2UTDebugTagIndent(__func__);

    GX2UTClearRectOp(colorBuffer, depthBuffer, r, g, b, a,
                     depthClear, stencilClear, clearFlags, hiStencil, &dstRect);

    GX2UTDebugTagUndent();
}

/// \brief Setup parameter specific render state and clear the specified dest surface.
///
/// \param dstSurface  Pointer to destination surface structure
/// \param dstMip      Mip level of dest surface to write (0 typically)
/// \param dstSlice    Slice to write for array & 3D (0 typically)
/// \param dstRect     Pointer to the destination region to clear.
/// \param dstAuxPtr   Destination MSAA auxPtr for AA buffer or NULL for non-AA buffers.
/// \param dstAuxSize  Destination MSAA auxSize for AA buffers or NULL for non-AA buffers.
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
///
/// This function assumes \ref GX2UTSetClearState()
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// Clears a region of a surface as specified by dstRect. The rect dimensions
/// should be relative to the mipmap level dimensions, not the base level
/// dimensions.
///
/// This clears a color/depth buffer in the same way as \ref GX2ClearColor
/// and \ref GX2ClearDepthStencil. It modifies the currently bound VS/PS
/// shaders, GX2_RENDER_TARGET0, depth buffer, and Scissor/Viewport
/// settings. In addition it overwrites VS uniform locations 0-3 and PS uniform
/// location 0, and it changes the \ref GX2SetShaderMode to
/// \ref GX2_SHADER_MODE_UNIFORM_REGISTER.
///
/// \note It is not necessary to call \ref GX2Invalidate on the color/depth
///       buffer being cleared. This is done internally.
///
/// \note This clear, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init() time. To avoid this,
///       call this clear function from a separate state context with
///       profiling disabled. See \ref GX2SetupContextStateEx() for more
///       information.
///
/// \warning The behavior of this routine has changed from SDK 2.12.00!
///          It now disables state shadowing and requires
///          \ref GX2SetContextState afterward. To avoid this, please use
///          \ref GX2UTClearRectOp instead.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearSurfaceRect(GX2Surface *dstSurface, u32 dstMip, u32 dstSlice,
                                      GX2UTRect *dstRect, void* dstAuxPtr, u32 dstAuxSize,
                                      f32 r, f32 g, f32 b, f32 a,
                                      GX2DepthBuffer *depthBuffer, f32 depthClear,
                                      u8 stencilClear, GX2ClearMode clearFlags,
                                      GX2HiStencilInfo *hiStencil)
{
    GX2ColorBuffer *cbPtr = NULL;
    GX2DepthBuffer *dbPtr = NULL;
    GX2ColorBuffer cb;
    GX2DepthBuffer db;

    GX2UTDebugTagIndent(__func__);

    if ( dstSurface )
    {
        cb.viewMip = dstMip;
        cb.viewFirstSlice = dstSlice;
        cb.viewNumSlices = 1;
        cb.auxPtr = dstAuxPtr;
        cb.auxSize = dstAuxSize;
        cb.surface = *dstSurface;
        GX2InitColorBufferRegs(&cb);
        cbPtr = &cb;
    }

    if ( depthBuffer )
    {
        db = *depthBuffer;
        db.viewMip = dstMip;
        db.viewFirstSlice = dstSlice;
        db.viewNumSlices = 1;
        GX2InitDepthBufferRegs(&db);

        dbPtr = &db;
    }

    // Disable state shadowing
    GX2SetContextState(NULL);

    // Setup clear
    GX2UTSetClearState(GX2_ENABLE);

    // Just clear a single slice at the given mip level
    GX2UTClearRectOp(cbPtr, dbPtr, r, g, b, a, depthClear, stencilClear,
                     clearFlags, hiStencil, dstRect);

    // Disable clear state
    GX2UTSetClearState(GX2_DISABLE);

    GX2UTDebugTagUndent();
}

/// \brief Clear a color and/or depth/stencil surface with Hi-Stencil.
///
/// \deprecated This API has been deprecated and may not be available in future
///             releases. Please use \ref GX2UTClearSurfaceRect instead.
///
/// \param dstSurface  Pointer to destination surface structure
/// \param dstMip      Mip level of dest surface to write (0 typically)
/// \param dstSlice    Slice to write for array & 3D (0 typically)
/// \param dstRect     Pointer to the destination region to clear.
/// \param dstAuxPtr   Destination MSAA auxPtr for AA buffer or NULL for non-AA buffers.
/// \param dstAuxSize  Destination MSAA auxSize for AA buffers or NULL for non-AA buffers.
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
/// \disablesstateshadow
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTSetAndClearSurfaceRect(
    GX2Surface *dstSurface, u32 dstMip, u32 dstSlice, GX2UTRect *dstRect,
    void* dstAuxPtr, u32 dstAuxSize, f32 r, f32 g, f32 b, f32 a,
    GX2DepthBuffer *depthBuffer, f32 depthClear, u8 stencilClear,
    GX2ClearMode clearFlags, GX2HiStencilInfo *hiStencil)
{
    GX2UTDebugTagIndent(__func__);

    // Setup parameter specific render state and clear.
    GX2UTClearSurfaceRect(dstSurface, dstMip, dstSlice, dstRect,
                          dstAuxPtr, dstAuxSize, r, g, b, a,
                          depthBuffer, depthClear, stencilClear,
                          clearFlags, hiStencil);

    GX2UTDebugTagUndent();
}

/// \brief Setup parameter specific render state and clear the specified dest surface.
///
/// \param dstSurface  Pointer to destination surface structure
/// \param dstMip      Mip level of dest surface to write (0 typically)
/// \param dstSlice    Slice to write for array & 3D (0 typically)
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
///
/// This routine is a convenience function for \ref GX2UTClearOp.
///
/// Clears a region of a surface as specified by dstRect. The rect dimensions
/// should be relative to the mipmap level dimensions, not the base level
/// dimensions.
///
/// This clears a color/depth buffer in the same way as \ref GX2ClearColor
/// and \ref GX2ClearDepthStencil. It modifies the currently bound VS/PS
/// shaders, GX2_RENDER_TARGET0, depth buffer, and Scissor/Viewport
/// settings. In addition it overwrites VS uniform locations 0-3 and PS uniform
/// location 0, and it changes the \ref GX2SetShaderMode to
/// \ref GX2_SHADER_MODE_UNIFORM_REGISTER.
///
/// To specify a region within the surface to be cleared, use
/// \ref GX2UTClearSurfaceRect instead.
///
/// \note It is not necessary to call \ref GX2Invalidate on the color/depth
///       buffer being cleared. This is done internally.
///
/// \note This clear, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init() time. To avoid this,
///       call this clear function from a separate state context with
///       profiling disabled. See \ref GX2SetupContextStateEx() for more
///       information.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \warning This routine does not work when dstSurface.aa != GX2_AA_MODE_1X.
///          Use \ref GX2UTClearSurfaceRect instead. Otherwise memory corruption
///          will occur.
///
/// \warning The behavior of this routine has changed from SDK 2.12.00!
///          It now disables state shadowing and requires
///          \ref GX2SetContextState afterward. To avoid this, please use
///          \ref GX2UTClearOp instead.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearSurface(GX2Surface *dstSurface, u32 dstMip, u32 dstSlice,
                                  f32 r, f32 g, f32 b, f32 a,
                                  GX2DepthBuffer *depthBuffer,
                                  f32 depthClear, u8 stencilClear,
                                  GX2ClearMode clearFlags,
                                  GX2HiStencilInfo *hiStencil)
{
    GX2UTRect dstRect;

    GX2UTDebugTagIndent(__func__);

    ASSERT(dstSurface != NULL || depthBuffer != NULL);

    if (dstSurface)
    {
        //We need to adjust rectangles based on the mip level
        dstRect.left = 0;
        dstRect.top  = 0;
        dstRect.right  = GX2Max(1, dstSurface->width  >> dstMip);
        dstRect.bottom = GX2Max(1, dstSurface->height >> dstMip);
    }
    else
    {
        //Use depthBuffer for dimensions
        dstRect.left = 0;
        dstRect.top  = 0;
        dstRect.right  = GX2Max(1, depthBuffer->surface.width);
        dstRect.bottom = GX2Max(1, depthBuffer->surface.height);
    }

    GX2UTClearSurfaceRect(dstSurface, dstMip, dstSlice, &dstRect,
                            NULL, 0, r, g, b, a,
                            depthBuffer, depthClear, stencilClear, clearFlags, hiStencil);

    GX2UTDebugTagUndent();
}

/// \brief Clears the given render target and depth/stencil surface.
///
/// \param colorBuffer   pointer to color buffer to clear
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param r             Red color component of clear value
/// \param g             Green color component of clear value
/// \param b             Blue color component of clear value
/// \param a             Alpha color component of clear value
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
/// \param stencilValue  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ClearBuffersEx.
///
/// \note This clear, as it is, will be impacted by the toss stage (GX2TossStage)
///       setup at GX2Init() time. To avoid this, call this clear function from
///       a separate state context with profiling disabled.  See
///       \ref GX2SetupContextStateEx() for more information.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearBuffersEx(GX2ColorBuffer *colorBuffer,
                                    GX2DepthBuffer *depthBuffer,
                                    f32 r, f32 g, f32 b, f32 a,
                                    f32 depthValue, u8 stencilValue,
                                    GX2ClearMode clearFlags)
{
    GX2UTRect dstRect;

    ASSERT(colorBuffer || depthBuffer);

    GX2UTDebugTagIndent(__func__);

    if ( colorBuffer )
    {
        // We need to adjust rectangles based on the mip level
        dstRect.left = 0;
        dstRect.top  = 0;
        dstRect.right  = GX2Max(1, colorBuffer->surface.width  >> colorBuffer->viewMip);
        dstRect.bottom = GX2Max(1, colorBuffer->surface.height >> colorBuffer->viewMip);
    }
    else
    {
        // We need to adjust rectangles based on the mip level
        dstRect.left = 0;
        dstRect.top  = 0;
        dstRect.right  = GX2Max(1, depthBuffer->surface.width  >> depthBuffer->viewMip);
        dstRect.bottom = GX2Max(1, depthBuffer->surface.height >> depthBuffer->viewMip);
    }

    //Disable state shadowing.  If your app is using state shadowing,
    //you will need to restore the context after calling this function.
    GX2SetContextState(NULL);

    // Setup all of the constant render state needed for the clear.
    GX2UTSetClearState(GX2_ENABLE);

    // Clear the rectangle
    GX2UTClearRectOp(colorBuffer, depthBuffer, r, g, b, a,
                     depthValue, stencilValue, clearFlags,
                     NULL, &dstRect);

    // Disable special hardware state and set state back to GX2 default
    GX2UTSetClearState(GX2_DISABLE);

    GX2UTDebugTagUndent();
}

/// \brief Clears the given render target to the specified color.
///
/// \param colorBuffer pointer to color buffer to clear
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ClearColor.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \note This function clears only the single miplevel specified by
///       colorBuffer->viewMip. This function clears the number of slices
///       specified by colorBuffer->viewNumSlices starting with slice number
///       colorBuffer->viewFirstSlice.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearColor(GX2ColorBuffer *colorBuffer,
                                f32 r, f32 g, f32 b, f32 a)
{
    GX2UTDebugTagIndent(__func__);

    GX2UTClearBuffersEx(colorBuffer, NULL, r, g, b, a, 0.0f, 0u, GX2_CLEAR_NONE);

    GX2UTDebugTagUndent();
}

/// \brief Clear the depth/stencil surface with saved depth and stencil values.
///
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ClearDepthStencil.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward
///       (when (clearFlags & (GX2_CLEAR_DEPTH|GX2_CLEAR_STENCIL)) != 0).
///
/// \note This API will use the current clearDepth and clearStencil values
///       from the \ref GX2DepthBuffer.
///
/// \note This function clears only the single miplevel specified by
///       depthBuffer->viewMip. This function clears the number of slices
///       specified by depthBuffer->viewNumSlices starting with slice number
///       depthBuffer->viewFirstSlice.
///
/// \note To generate valuable HiStencil pretest results while clearing the
///       stencil buffer, please see \ref GX2UTClearRectOp.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearDepthStencil(GX2DepthBuffer *depthBuffer, GX2ClearMode clearFlags)
{
    ASSERT(depthBuffer);

    GX2UTDebugTagIndent(__func__);

    GX2UTClearBuffersEx(NULL, depthBuffer, 0.0f, 0.0f, 0.0f, 0.0f, depthBuffer->clearDepth, depthBuffer->clearStencil, clearFlags);

    GX2UTDebugTagUndent();
}

/// \brief Clear the depth/stencil surface with given depth and stencil values.
///
/// \param depthBuffer   pointer to depth/stencil buffer to clear
/// \param depthValue    Depth clear value (from 0.0 to 1.0)
/// \param stencilValue  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ClearDepthStencilEx.
///
/// \note This function clears only the single miplevel specified by
///       depthBuffer->viewMip. This function clears the number of slices
///       specified by depthBuffer->viewNumSlices starting with slice number
///       depthBuffer->viewFirstSlice.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearDepthStencilEx(GX2DepthBuffer *depthBuffer,
                                         f32 depthValue, u8 stencilValue,
                                         GX2ClearMode clearFlags)
{
    GX2UTDebugTagIndent(__func__);

    GX2UTClearBuffersEx(NULL, depthBuffer, 0.0f, 0.0f, 0.0f, 0.0f, depthValue, stencilValue, clearFlags);

    GX2UTDebugTagUndent();
}

/// \brief Clears the given render target and depth/stencil surface.
///
/// \param colorBuffer pointer to color buffer to clear
/// \param depthBuffer pointer to depth/stencil buffer to clear
/// \param r Red color component of clear value
/// \param g Green color component of clear value
/// \param b Blue color component of clear value
/// \param a Alpha color component of clear value
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ClearBuffers.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTClearBuffers(GX2ColorBuffer *colorBuffer, GX2DepthBuffer *depthBuffer,
                                  f32 r, f32 g, f32 b, f32 a, GX2ClearMode clearFlags)
{
    ASSERT(depthBuffer);

    GX2UTDebugTagIndent(__func__);

    GX2UTClearBuffersEx(colorBuffer, depthBuffer, r, g, b, a, depthBuffer->clearDepth, depthBuffer->clearStencil, clearFlags);

    GX2UTDebugTagUndent();
}

/// \brief Clear a color and/or depth/stencil surface with Hi-Stencil.
///
/// \deprecated This API has been deprecated and may not be available in future
///             releases. Please use \ref GX2UTCopySurfaceEx instead.
///
/// \param dstSurface  Pointer to destination surface structure
/// \param dstMip      Mip level of dest surface to write (0 typically)
/// \param dstSlice    Slice to write for array & 3D (0 typically)
/// \param r           Red color component of clear value
/// \param g           Green color component of clear value
/// \param b           Blue color component of clear value
/// \param a           Alpha color component of clear value
/// \param depthBuffer Pointer to depth buffer to clear
/// \param depthClear  Depth clear value (from 0.0 to 1.0)
/// \param stencilClear  Stencil clear value (from 0 to 255)
/// \param clearFlags    Indicates if depth and/or stencil buffer should be cleared
/// \param hiStencil     pointer to HiStencil pretest states
///
/// \note It is not necessary to call \ref GX2Invalidate on the color/depth
///       buffer being cleared. This is done internally.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTSetAndClearSurface(GX2Surface *dstSurface, u32 dstMip, u32 dstSlice,
                                        f32 r, f32 g, f32 b, f32 a,
                                        GX2DepthBuffer *depthBuffer, f32 depthClear, u8 stencilClear,
                                        GX2ClearMode clearFlags, GX2HiStencilInfo *hiStencil)
{
    GX2UTDebugTagIndent(__func__);

    // Setup parameter specific render state and clear.
    GX2UTClearSurface(dstSurface, dstMip, dstSlice, r, g, b, a, depthBuffer,
                      depthClear, stencilClear, clearFlags, hiStencil);

    GX2UTDebugTagUndent();
}

/// \brief A function to invalidate the HiStencil pretest results.
///
/// \param dstRect     Pointer to the destination region to clear.
/// \param depthBuffer Pointer to depth buffer to clear
///
/// This routine clears the HiStencil pretest results without clearing the
/// actual stencil buffer. This should be invoked if the HiStencil pretest
/// states need to be changed during a frame. This is faster than clearing
/// and regenerating the actual stencil buffer.
///
/// \note Must be invoked when changing the HiStencil state within a frame. In
///       other words, always invoke this function in combination with
///       \ref GX2SetHiStencilInfo. Never invoke one without the other or
///       HiStencil buffer corruption will occur.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTInvalidateHiStencilRect(GX2UTRect *dstRect, GX2DepthBuffer *depthBuffer);

/// \brief Clears the MSAA color buffer auxPtr.
///
/// This clears the \ref GX2ColorBuffer.auxPtr to
/// \ref GX2_AUX_BUFFER_CLEAR_VALUE using the graphics pipeline.
///
/// \param colorBuffer MSAA Color buffer to clear
///
/// \clobberstate
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetupColorAuxBufferOp(GX2ColorBuffer *colorBuffer);

/// \brief Clears the MSAA color buffer auxPtr.
///
/// This clears the \ref GX2ColorBuffer.auxPtr to
/// \ref GX2_AUX_BUFFER_CLEAR_VALUE using the graphics pipeline.
///
/// \param colorBuffer MSAA Color buffer to clear
///
/// \warning Better performing alternative exists. Please see
///          \ref GX2UTSetupColorAuxBufferOp and \ref GX2UTSetClearState.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTSetupColorAuxBuffer(GX2ColorBuffer *colorBuffer)
{
    // Disable state shadowing
    GX2SetContextState(NULL);

    // Setup clear
    GX2UTSetClearState(GX2_ENABLE);

    // Just clear a single slice at the given mip level
    GX2UTSetupColorAuxBufferOp(colorBuffer);

    // Disable clear state
    GX2UTSetClearState(GX2_DISABLE);


}

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _GX2UTCLEAR_H_