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

  Copyright 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.

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

#ifndef _GX2UT_H_
#define _GX2UT_H_

#include <cafe/gx2ut/gx2utInline.h>
#include <cafe/gx2ut/gx2utCopy.h>
#include <cafe/gx2ut/gx2utClear.h>
#include <cafe/gx2ut/gx2utExpand.h>
#include <cafe/gx2ut/gx2utResolve.h>


#ifdef __cplusplus
extern "C" {
#endif

/// @addtogroup GX2UTHelperGroup
/// @{

/// \brief Sets up common state parameters needed by various GX2UT functions.
///
/// This routine sets the default state used by the \ref GX2UTGX2ReplacementsSect.
/// 
/// It attempts to restore the minimum state needed to guarantee that
/// the function works as expected.
///
/// \note This function does not restore state that has been changed by
///       \ref GX2DisablesStateShadowingPage "GX2 Functions Which Disable State Shadowing".
///       If any of these routines are called before this function, it is
///       necessary to call \ref GX2SetContextState to restore the state first.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \clobberstate
///
/// \writesgpu
/// \alwayswritesgpu
///
void GX2UTSetCommonState();

/// @}

/// @addtogroup GX2UTSurfaceHelperGroup
/// @{

/// \brief Returns the pointer to a given slice in the mip-map chain.
///
/// \param pSurf Surface to find the swizzle for.
/// \param mipLevel Mipmap level
/// \param slice Slice
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
void* GX2UTGetSurfaceMipSlicePtr(const GX2Surface* pSurf, u32 mipLevel, u32 slice);

/// \brief Determine the swizzle value of a given slice and mipmap level in a surface.
///
/// \param pSurf Surface to find the swizzle for.
/// \param mipLevel Mipmap level
/// \param slice Slice
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
u32 GX2UTGetSurfaceMipSliceSwizzle(const GX2Surface* pSurf, u32 mipLevel, u32 slice);

/// \brief Determine the size of a given mipmap level.
///
/// \param pSurf Surface to find the mipmap size of
/// \param mipLevel Mipmap level
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
u32 GX2UTGetSurfaceMipSize(const GX2Surface* pSurf, u32 mipLevel);

/// \brief Determine the tiling mode of a mipmap level.
/// 
/// \param pSurf Surface to select the tiling mode from
/// \param mipLevel Mip-map level to select
///
/// This function determines the \ref GX2Surface.tileMode for the given
/// \p mipLevel. This is based on the tiling mode of \p pSurf.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2TileMode GX2UTGetSurfaceMipSliceTileMode(const GX2Surface* pSurf, u32 mipLevel);

/// \brief Determines if the tiling mode of a surface is *_THICK.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2UTIsTileModeThick(const GX2Surface* pSurf);

/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _GX2UT_H_