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

  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 _CAFE_GX2R_SURFACE_H_
#define _CAFE_GX2R_SURFACE_H_



#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus


/// @addtogroup GX2RGroup
/// @{


/// \brief \ref GX2RDestroySurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \userheap \devonly \enddonotcall
///
void GX2API GX2RDestroySurfaceEx(GX2Surface* gx2Surface, GX2RResourceFlags optionFlags);

/// \brief \ref GX2RLockSurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
void* GX2API GX2RLockSurfaceEx(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);

/// \brief \ref GX2RUnlockSurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
///
void GX2API GX2RUnlockSurfaceEx(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);

/// \brief Create a surface.
///
/// \param gx2Surface       Address of a filled-in \ref GX2Surface struct.
/// \param resourceFlags    Type, usage and options for the surface.
/// \return GX2_TRUE if creation succeeds, GX2_FALSE otherwise
///
/// \note This function will allocate the memory via the allocator callback (see \ref GX2RSetAllocator).
/// See \ref GX2RCreateBufferUserMemory for cache behavior and notes.
///
/// \donotcall \gx2_typical \userheap \enddonotcall
///
GX2Boolean GX2API GX2RCreateSurface(GX2Surface* gx2Surface, GX2RResourceFlags resourceFlags);

/// \brief Create a surface from user supplied memory.
///
/// \param gx2Surface       Address of a filled-in \ref GX2Surface struct.
/// \param imagePtr         Pointer to existing memory for the surface main image.
/// \param mipPtr           Pointer to existing memory for the surface mip chain, or NULL.
/// \param resourceFlags    Type, usage and options for the surface.
/// \return GX2_TRUE if creation succeeds, GX2_FALSE otherwise
///
/// \note This function will perform any necessary cache invalidation.
/// \ref GX2RCreateSurface should be used in preference to this version except where absolutely necessary.
/// \ref GX2RDestroySurface must still be called for user memory surfaces.
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
GX2Boolean GX2API GX2RCreateSurfaceUserMemory(GX2Surface* gx2Surface, void* imagePtr, void* mipPtr, GX2RResourceFlags resourceFlags);

/// \brief Destroy a surface.
///
/// \param gx2Surface Address of a \ref GX2Surface struct.
///
/// \note Memory will be freed via the default allocator or user callback.
/// If the buffer was created from user memory via \ref GX2RCreateSurfaceUserMemory this function is
/// still necessary to mark the buffer as deleted.
/// Destroying a surface that was never created or has already been destroyed is not an error.
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \userheap \devonly \enddonotcall
///
GX2_INLINE void GX2RDestroySurface(GX2Surface* gx2Surface)
{
    GX2RDestroySurfaceEx(gx2Surface, GX2R_OPTION_NONE);
}

/// \brief  Lock a surface and return a pointer to the memory.
///
/// \param gx2Surface   Address of a \ref GX2Surface struct.
/// \param mipLevel     0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
/// \return Memory address of the start of the buffer
///
/// \note   The surface memory may be read or written by the CPU or via DMA transfer (or even the GPU),
/// however it is imperative the correct usage GX2RUsageFlags are set.
/// \ref GX2RUnlockSurface must be called before the surface is used by any other GX2R APIs.
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
GX2_INLINE void* GX2RLockSurface(const GX2Surface* gx2Surface, s32 mipLevel)
{
    return GX2RLockSurfaceEx(gx2Surface, mipLevel, GX2R_OPTION_NONE);
}

/// \brief Unlock a surface.
///
/// \param gx2Surface   Address of a \ref GX2Surface struct.
/// \param mipLevel     0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
///
/// \note This function will perform any necessary cache invalidation.
/// The memory pointer must not be used after the surface is unlocked.
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
///
GX2_INLINE void GX2RUnlockSurface(const GX2Surface* gx2Surface, s32 mipLevel)
{
    GX2RUnlockSurfaceEx(gx2Surface, mipLevel, GX2R_OPTION_NONE);
}

/// \brief Returns true if the surface has memory allocated, that is, created but not yet destroyed
/// \param gx2Surface Address of a \ref GX2Surface struct.
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2API GX2RSurfaceExists(const GX2Surface* gx2Surface);

/// \brief Give the surface a meaningful name for debug and profiling.
//
/// \param gx2Surface Address of a \ref GX2Surface struct.
/// \param name Name string. Copied into the API.
///
/// \note Ignored in release builds.
/// Surface must have memory allocated (i.e. \ref GX2RSurfaceExists is true) when this is called.
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
void GX2API GX2RSetSurfaceName(const GX2Surface* gx2Surface, const char* name);

/// \brief Get surface debug name - see \ref GX2RSetSurfaceName
///
/// \param gx2Surface Address of a \ref GX2Surface struct.
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
const char* GX2API GX2RGetSurfaceName(const GX2Surface* gx2Surface);


/// \brief Utility function to perform correct cache invalidation for the given surface
///
/// \param gx2Surface   Address of a \ref GX2Surface struct.
/// \param mipLevel     0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
/// \param optionFlags  The OPTION values are used instead of surface resourceFlags (i.e. surface NO_INVALIDATE flags will be ignored)
///
/// \note Typically when using the GX2R APIs this will not be necessary, however it is useful when using \ref GX2RResourceFlags
/// to suppress invalidation within the API.
/// See also \ref GX2RInvalidateMemory
///
/// \donotcall \gx2_typical \enddonotcall
///
/// \writesgpu
/// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
///
void GX2API GX2RInvalidateSurface(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);


/// \brief Test if the surface resourceFlags indicate it was created with \ref GX2RCreateSurface
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2RIsGX2RSurface(GX2RResourceFlags resourceFlags);


/// @}

#ifdef __cplusplus
}
#endif // __cplusplus

#endif