cafe/gx2ut/gx2utCopy.h

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

  Copyright 2010-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 _GX2UTCOPY_H_
#define _GX2UTCOPY_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 Rectangular region
typedef struct _GX2UTRect {
    s32 left;
    s32 top;
    s32 right;
    s32 bottom;
} GX2UTRect;

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

/// \brief Copy the specified source surface rectangle to the dest surface rectangle.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \param srcRect     Pointer to the source region to copy.
/// \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 copy.
/// \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.
///
/// This function assumes \ref GX2UTSetCopyState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// Copies 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 blt the entire surface without any flipping (the
/// right and bottom are exclusive).
///
/// The srcRect/dstRect dimensions should be relative to the mipmap level
/// dimensions, not the base level dimensions.
///
/// \note Compressed textures must be copied on a 4x4 pixel alignment.
///       Coordinates are in terms of pixels, not blocks.
///       For compressed textures the source and destination formats must
///       match.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \note If the source is an AA buffer, you must call
///       \ref GX2ExpandAAColorBuffer or \ref GX2UTExpandAAColorBuffer first.
///
/// \note This copy, 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 Stretching is not supported for depth/stencil/compressed formats.
///
/// \clobberstate
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTCopySurfaceRectOp(const GX2Surface *srcSurface,
                            u32 srcMip, u32 srcSlice, GX2UTRect *srcRect,
                            GX2Surface *dstSurface,
                            u32 dstMip, u32 dstSlice, GX2UTRect *dstRect,
                            void* dstAuxPtr, u32 dstAuxSize);

/// \brief Copy the specified source surface to the dest surface.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \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 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.
///
/// This function assumes \ref GX2UTSetCopyState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// Copies 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 blt the entire surface without any flipping (the
/// right and bottom are exclusive).
///
/// \note Compressed textures must be copied on a 4x4 pixel alignment.
///       Coordinates are in terms of pixels, not blocks.
///       For compressed textures the source and destination formats must
///       match.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \note If the source is an AA buffer, you must call
///       \ref GX2ExpandAAColorBuffer or \ref GX2UTExpandAAColorBuffer first.
///
/// \note This copy, 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 Stretching is not supported for depth/stencil/compressed formats.
///
/// \clobberstate
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTCopySurfaceOp(const GX2Surface *srcSurface,
                                   u32 srcMip, u32 srcSlice,
                                   GX2Surface *dstSurface,
                                   u32 dstMip, u32 dstSlice,
                                   void* dstAuxPtr, u32 dstAuxSize)
{
    GX2UTRect srcRect = {0};
    GX2UTRect dstRect = {0};

    GX2UTDebugTagIndent(__func__);

    // This may be stretch copy so rectangles need to match
    // source and destination surfaces.
    srcRect.right = GX2Max(1, srcSurface->width >> srcMip);
    srcRect.bottom = GX2Max(1, srcSurface->height >> srcMip);
    dstRect.right = GX2Max(1, dstSurface->width >> dstMip);
    dstRect.bottom = GX2Max(1, dstSurface->height >> dstMip);

    GX2UTCopySurfaceRectOp(srcSurface, srcMip, srcSlice, &srcRect,
                           dstSurface, dstMip, dstSlice, &dstRect,
                           dstAuxPtr, dstAuxSize);
    GX2UTDebugTagUndent();
}

/// \brief Copy the specified source surface to the dest surface.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \param srcRect     Pointer to the source region to copy.
/// \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 copy.
/// \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.
///
/// This function assumes \ref GX2UTSetCopyState
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// Copies 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 blt the entire surface without any flipping (the
/// right and bottom are exclusive).
///
/// The srcRect/dstRect dimensions should be relative to the mipmap level
/// dimensions, not the base level dimensions.
///
/// \note Compressed textures must be copied on a 4x4 pixel alignment.
///       Coordinates are in terms of pixels, not blocks.
///       For compressed textures the source and destination formats must
///       match.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \note If the source is an AA buffer, you must call
///       \ref GX2ExpandAAColorBuffer or \ref GX2UTExpandAAColorBuffer first.
///
/// \note This copy, 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 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 GX2UTCopySurfaceRectOp instead.
///
/// \warning Stretching is not supported for depth/stencil/compressed formats.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTCopySurfaceRect(const GX2Surface *srcSurface,
                                     u32 srcMip, u32 srcSlice,
                                     GX2UTRect *srcRect,
                                     GX2Surface *dstSurface,
                                     u32 dstMip, u32 dstSlice,
                                     GX2UTRect *dstRect,
                                     void* dstAuxPtr, u32 dstAuxSize)
{
    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 copy.
    GX2UTSetCopyState(GX2_ENABLE);

    // Setup parameter specific render state and copy.
    GX2UTCopySurfaceRectOp(srcSurface, srcMip, srcSlice, srcRect,
                         dstSurface, dstMip, dstSlice, dstRect,
                         dstAuxPtr, dstAuxSize);

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


    GX2UTDebugTagUndent();
}

/// \brief Copy the specified source surface to the dest surface.
///
/// \deprecated This API has been deprecated and may not be available in future
///             releases. Please use \ref GX2UTCopySurfaceRect instead.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \param srcRect     Pointer to the source region to copy.
/// \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 copy.
/// \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.
///
/// This routine copys one surface to another in the same way as
/// \ref GX2CopySurfaceEx.
///
/// The source and destination rectangles are relative to the current miplevel.
///
/// \note Compressed textures must be copied on a 4x4 pixel alignment.
///       Coordinates are in terms of pixels, not blocks.
///       For compressed textures the source and destination formats must
///       match.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTSetAndCopySurfaceRect(const GX2Surface *srcSurface,
                                           u32 srcMip, u32 srcSlice,
                                           GX2UTRect *srcRect,
                                           GX2Surface *dstSurface,
                                           u32 dstMip, u32 dstSlice,
                                           GX2UTRect *dstRect,
                                           void* dstAuxPtr, u32 dstAuxSize)
{
    GX2UTDebugTagIndent(__func__);

    // Setup parameter specific render state and copy.
    GX2UTCopySurfaceRect(srcSurface, srcMip, srcSlice, srcRect,
                         dstSurface, dstMip, dstSlice, dstRect,
                         dstAuxPtr, dstAuxSize);

    GX2UTDebugTagUndent();
}

/// \brief Copy the specified source surface to the dest surface.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \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 numRects    Number of rectangles to copy
/// \param pSrcRects   Array of source rectangles to copy
/// \param pDstPoints  Array of destination points to copy the rectangles to.
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2CopySurfaceEx.
///
/// The rectangles in pSrcRects should be relative to the mip-level dimensions.
///
/// \note Compressed textures must be copied on a 4x4 pixel alignment.
///       Coordinates are in terms of pixels, not blocks.
///       For compressed textures the source and destination formats must
///       match.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTCopySurfaceEx(const GX2Surface *srcSurface,
                                   u32 srcMip, u32 srcSlice,
                                   GX2Surface *dstSurface,
                                   u32 dstMip, u32 dstSlice,
                                   u32 numRects,
                                   GX2RectInt* pSrcRects,
                                   GX2PointInt* pDstPoints)
{
    GX2UTRect srcRect;
    GX2UTRect dstRect;

    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 copy.
    GX2UTSetCopyState(GX2_ENABLE);

    for (int i = 0; i < numRects; i++)
    {
        // Setup the source rectangle
        srcRect.left = pSrcRects[i].left;
        srcRect.right = pSrcRects[i].right;
        srcRect.top = pSrcRects[i].top;
        srcRect.bottom = pSrcRects[i].bottom;

        // Setup the destination rectangle
        dstRect.left = pDstPoints[i].x;
        dstRect.right = pDstPoints[i].x + pSrcRects[i].right - pSrcRects[i].left;
        dstRect.top = pDstPoints[i].y + pSrcRects[i].top;
        dstRect.bottom = pDstPoints[i].y + pSrcRects[i].bottom - pSrcRects[i].top;
        //Setup parameter specific render state and copy.
        GX2UTCopySurfaceRectOp(srcSurface, srcMip, srcSlice, &srcRect,
                             dstSurface, dstMip, dstSlice, &dstRect,
                             NULL, 0);
    }

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

    GX2UTDebugTagUndent();
}

/// \brief Copy the specified source surface to the dest surface.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \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)
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2CopySurface.
///
/// This function assumes \ref GX2UTSetCopyState()
/// (or comparable state setup function) has been called to setup required
/// render state.
///
/// To specify the source and destination regions or to copy AA color
/// buffers, use  \ref GX2UTCopySurfaceRectOp instead.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \note This copy, 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 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 GX2UTCopySurfaceRectOp instead.
///
/// \warning Stretching is not supported for depth/stencil/compressed formats.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTCopySurface(const GX2Surface *srcSurface,
                                 u32 srcMip, u32 srcSlice,
                                 GX2Surface *dstSurface,
                                 u32 dstMip, u32 dstSlice)
{
    GX2UTRect srcRect;
    GX2UTRect dstRect;

    //We need to adjust rectangles based on the mip level
    srcRect.left = 0;
    srcRect.top  = 0;
    srcRect.right  = GX2Max(1, srcSurface->width  >> srcMip);
    srcRect.bottom = GX2Max(1, srcSurface->height >> srcMip);

    dstRect.left = 0;
    dstRect.top  = 0;
    dstRect.right  = GX2Max(1, dstSurface->width  >> dstMip);
    dstRect.bottom = GX2Max(1, dstSurface->height >> dstMip);

    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 copy.
    GX2UTSetCopyState(GX2_ENABLE);

    GX2UTCopySurfaceRectOp(srcSurface, srcMip, srcSlice, &srcRect,
                         dstSurface, dstMip, dstSlice, &dstRect,
                         NULL, 0);

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

    GX2UTDebugTagUndent();
}

/// \brief Copy the specified source surface to the dest surface.
///
/// \deprecated This API has been deprecated and may not be available in future
///             releases. Please use \ref GX2UTCopySurface instead.
///
/// \param srcSurface  Pointer to source surface structure
/// \param srcMip      Mip level of surface to read (0 typically)
/// \param srcSlice    Slice to read for array & 3D (0 typically)
/// \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)
///
/// This function mimics the behavior of GX2 and is intended to be an optimized
/// replacement for \ref GX2CopySurface.
///
/// \note It is not necessary to call \ref GX2Invalidate on the
///        source/destination buffers. This is done internally.
///
/// \warning Better performing alternatives exist. Please see
///          \ref GX2UTAdvancedGX2ReplacementAPISect.
///
/// \clobberstate
/// \disablesstateshadow
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \alwayswritesgpu
///
GX2_INLINE void GX2UTSetAndCopySurface(
    const GX2Surface *srcSurface, u32 srcMip, u32 srcSlice,
    GX2Surface *dstSurface, u32 dstMip, u32 dstSlice)
{
    GX2UTDebugTagIndent(__func__);

    //Setup parameter specific render state and copy.
    GX2UTCopySurface(srcSurface, srcMip, srcSlice,
                     dstSurface, dstMip, dstSlice);

    GX2UTDebugTagUndent();
}

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _GX2UTCOPY_H_