cafe/gx2ut/gx2utExpand.h

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

  Copyright 2014 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 _GX2UTEXPAND_H_
#define _GX2UTEXPAND_H_

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

#ifdef __cplusplus
extern "C" {
#endif

/// @addtogroup GX2UTCopyAndConvertGroup
/// @{

/// \brief Setup all of the constant render state needed for \ref GX2UTExpandAAColorBuffer.
///
/// \param enable Enable or disable the state
///
/// This enables and disables the state used by \ref GX2UTExpandAAColorBufferOp
/// After finishing all expand 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/gx2utExpandColor.cpp).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetExpandAAColorState(GX2Boolean enable);

/// \brief Expand MSAA color buffer for use as a texture.
///
/// \param cb MSAA color buffer to expand
///
/// This function assumes \ref GX2UTSetExpandAAColorState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This expands a compressed color buffer in the same way as
/// \ref GX2ExpandAAColorBuffer. It modifies the current GX2 state for
/// all shaders, GX2_RENDER_TARGET0, and Scissor/Viewport settings.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        color buffer. This is done internally.
///
/// \note This expand, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init time. To avoid this, call
///       this function from a separate state context with profiling disabled.
///       See \ref GX2SetupContextStateEx for more information.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTExpandAAColorBufferOp(GX2ColorBuffer *cb);


/// \brief Expands a MSAA color buffer so it can be used as a texture.
///
/// \param db Compressed (HiZ) depth buffer to expand
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ExpandAAColorBuffer.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        color buffer. 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 GX2UTExpandAAColorBuffer(GX2ColorBuffer *db)
{
    GX2UTDebugTagIndent(__func__);

    // 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 color expand.
    GX2UTSetExpandAAColorState(GX2_ENABLE);

    // Setup parameter specific render state and color expand.
    GX2UTExpandAAColorBufferOp(db);

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

    GX2UTDebugTagUndent();
}

/// \brief Setup all of the constant render state needed for \ref GX2UTExpandDepthBuffer.
///
/// \param enable Enable or disable the state
///
/// This enables and disables the state used by \ref GX2UTExpandDepthBuffer.
/// After finishing all expand operations, it is necessary to call
/// this function to disable the expand state and set any changed state
/// back 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/gx2utExpandDepth.cpp).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetExpandDepthState(GX2Boolean enable);

/// \brief Expand compressed depth buffer for use as a texture.
///
/// \param db Compressed (HiZ) depth buffer to expand
///
/// This function assumes \ref GX2UTSetExpandDepthState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This expands a compressed (HiZ) depth buffer in the same way as
/// \ref GX2ExpandDepthBuffer. It modifies the curent GX2 state for all
/// shaders, depth buffer, and Scissor/Viewport settings
///
/// \warning Subsequent draw calls to this buffer will undo the expand, so this
/// must be called between drawing to the buffer and texturing from it.
///
/// \warning The depth buffer must not be an AA buffer or
///          \ref GX2_SURFACE_FORMAT_D_D24_S8_UNORM. Please use
///          \ref GX2UTConvertDepthBufferToTextureSurface instead.
///
/// \clobberstate
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///       depth buffer. This is done internally.
///
/// \note This expand, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init time. To avoid this, call
///       this function from a separate state context with profiling disabled.
///       See \ref GX2SetupContextStateEx for more information.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTExpandDepthBufferOp(GX2DepthBuffer *db);


/// \brief Expands a compressed depth buffer (HiZ enabled) so it can be used
/// as a texture.
///
/// \param db Compressed (HiZ) depth buffer to expand
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ExpandDepthBuffer.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        color buffer. 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 GX2UTExpandDepthBuffer(GX2DepthBuffer *db)
{
    GX2UTDebugTagIndent(__func__);

    // 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 depth expand.
    GX2UTSetExpandDepthState(GX2_ENABLE);

    // Setup parameter specific render state and depth expand.
    GX2UTExpandDepthBufferOp(db);

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

    GX2UTDebugTagUndent();
}

/// \brief Setup all of the constant render state needed for \ref GX2UTConvertDepthBufferToTextureSurface.
///
/// \param enable Enable or disable the state
///
/// This enables and disables the state used by
/// \ref GX2UTConvertDepthBufferToTextureSurface. After fnishing all convert
/// operations, it is necessary to call this function to disable the convert
/// 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/gx2utConvertDepth.cpp).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetConvertDepthState(GX2Boolean enable);

/// \brief Copy and Convert a depth buffer so it a format readable as a texture.
///
/// \param srcBuffer  Pointer to depth buffer surface structure
/// \param dstSurface Pointer to destination surface structure
/// \param dstMip Mip level of the destination surface to write
/// \param dstSlice Slice to begin writing source slices to
///
/// This function assumes \ref GX2UTSetConvertDepthState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This copies a depth buffer to another surface while changing from
/// format-tiling to texture/color-format tiling. This is only necessary
/// for depth formats that cannot be read by the texture unit (MSAA or
/// \ref GX2_SURFACE_FORMAT_D_D24_S8_UNORM format). This routine behaves the
/// same as \ref GX2ConvertDepthBufferToTextureSurface. See this API for more
/// details.
///
/// This routine modifies the current GX2 state for all shaders,
/// GX2_RENDER_TARGET0, depth buffer, and Scissor/Viewport Settings.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///       source/destination buffer. This is done internally.
///
/// \note This convert, as it is, will be impacted by the toss stage
///       (\ref GX2TossStageSect) setup at GX2Init time. To avoid this, call
///       this function from a separate state context with profiling disabled.
///       See \ref GX2SetupContextStateEx for more information.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTConvertDepthBufferToTextureSurfaceOp(const GX2DepthBuffer* srcBuffer,
                                               GX2Surface* dstSurface,
                                               u32 dstMip, u32 dstSlice);


/// \brief Copy and Convert a depth buffer so it a format readable as a texture.
///
/// \param srcBuffer  Pointer to depth buffer surface structure
/// \param dstSurface Pointer to destination surface structure
/// \param dstMip Mip level of the destination surface to write
/// \param dstSlice Slice to begin writing source slices to
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ConvertDepthBufferToTextureSurface.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///       source/destination buffer. 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 GX2UTConvertDepthBufferToTextureSurface(
                                               const GX2DepthBuffer* srcBuffer,
                                               GX2Surface* dstSurface,
                                               u32 dstMip, u32 dstSlice)
{
    GX2UTDebugTagIndent(__func__);

    // 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 depth expand.
    GX2UTSetConvertDepthState(GX2_ENABLE);

    // Setup parameter specific render state and depth convert.
    GX2UTConvertDepthBufferToTextureSurfaceOp(srcBuffer, dstSurface, dstMip, dstSlice);

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

    GX2UTDebugTagUndent();
}


/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _GX2UTEXPAND_H_