cafe/gx2ut/gx2utResolve.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 _GX2UTRESOLVE_H_
#define _GX2UTRESOLVE_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 GX2UTResolveAAColorBuffer.
///
/// \param enable Enable or disable the state
///
/// This enables and disables the state used by \ref GX2UTResolveAAColorBuffer.
/// After finishing all resolve operations, it is necessary to call
/// this function to disable the resolve 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/gx2utResolve.cpp).
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetResolveAAColorState(GX2Boolean enable);

/// \brief Resolves a MSAA color buffer to a single-sampled surface.
///
/// \param cb  Pointer to color buffer surface structure
/// \param dstSurface Destination color/texture surface.
/// \param dstMip Destination mipmap level for dstSurface.
/// \param dstSlice Destination slice for dstSurface.
/// \param subRect Pointer to the region to resolve.
///
/// This function assumes \ref GX2UTSetResolveAAColorState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This resolves a MSAA color buffer to a single-sampled surface in the same
/// way as \ref GX2ResolveAAColorBuffer. It modifies the current GX2 state for
/// all shaders, GX2_RENDER_TARGET0, GX2_RENDER_TARGET1, and Scissor/Viewport
/// settings.
///
/// Resolves a region from one surface to a region of another surface. Setting
/// the rectangular regions to a top-left of (0,0) and a bottom-right of (width,
/// height) will resolve the entire surface without any flipping (the right and
/// bottom are exclusive).
///
/// The subRect dimensions should be relative to the mipmap level dimensions,
/// not the base level dimensions.  The subRect origin (left, top) must be
/// aligned on a 2x2 pixel boundary.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///       source/destination buffer. This is done internally.
///
/// \note This routine has the same limitations as \ref GX2ResolveAAColorBuffer.
///       \ref GX2IsResolveSupported can be used to determine if a source
///       GX2ColorBuffer can be resolved.
///
/// \note This resolve, 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.
///
/// \warning The color buffer must not be an AA buffer and the destination
///          surface must be a non-AA color/texture surface.
///
/// \clobberstate
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTResolveAAColorBufferRectOp(const GX2ColorBuffer *cb,
                                     GX2Surface *dstSurface,
                                     u32 dstMip, u32 dstSlice,
                                     GX2UTRect * subRect);

/// \brief Resolves a MSAA color buffer to a single-sampled surface.
///
/// \param cb  Pointer to color buffer surface structure
/// \param dstSurface Destination color/texture surface.
/// \param dstMip Destination mipmap level for dstSurface.
/// \param dstSlice Destination slice for dstSurface.
///
/// This function assumes \ref GX2UTSetResolveAAColorState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// This resolves a MSAA color buffer to a single-sampled surface in the same
/// way as \ref GX2ResolveAAColorBuffer. It modifies the current GX2 state for
/// all shaders, GX2_RENDER_TARGET0, GX2_RENDER_TARGET1, and Scissor/Viewport
/// settings.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///       source/destination buffer. This is done internally.
///
/// \note This routine has the same limitations as \ref GX2ResolveAAColorBuffer.
///       \ref GX2IsResolveSupported can be used to determine if a source
///       GX2ColorBuffer can be resolved.
///
/// \note This resolve, 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.
///
/// \warning The color buffer must not be an AA buffer and the destination
///          surface must be a non-AA color/texture surface.
///
/// \clobberstate
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTResolveAAColorBufferOp(const GX2ColorBuffer *cb,
                                            GX2Surface *dstSurface, u32 dstMip,
                                            u32 dstSlice)
{
    GX2UTRect subRect = {0};

    subRect.right = GX2Max(1, dstSurface->width >> dstMip);
    subRect.bottom = GX2Max(1, dstSurface->height >> dstMip);

    GX2UTDebugTagIndent(__func__);

    GX2UTResolveAAColorBufferRectOp(cb, dstSurface, dstMip, dstSlice, &subRect);

    GX2UTDebugTagUndent();
}


/// \brief Resolves a MSAA color buffer to a single-sampled surface.
///
/// \param cb  Pointer to color buffer surface structure
/// \param dstSurface Destination color/texture surface.
/// \param dstMip Destination mipmap level for dstSurface.
/// \param dstSlice Destination slice for dstSurface.
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2ResolveAAColorBuffer.
///
/// \note This API changes rendering states and disables state shadowing.
///       If you are using state shadowing, you must call
///       \ref GX2SetContextState() afterward.
///
/// \note This routine has the same limitations as \ref GX2ResolveAAColorBuffer.
///       \ref GX2IsResolveSupported can be used to determine if a source
///       GX2ColorBuffer can be resolved.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTResolveAAColorBuffer(const GX2ColorBuffer *cb,
                                          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 color resolve.
    GX2UTSetResolveAAColorState(GX2_ENABLE);

    // Setup parameter specific render state and color resolve.
    GX2UTResolveAAColorBufferOp(cb, dstSurface, dstMip, dstSlice);

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

    GX2UTDebugTagUndent();
}


/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _GX2UTRESOLVE_H_