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

  Copyright (C) 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 _CAFE_GX2R_RESOURCE_H_
#define _CAFE_GX2R_RESOURCE_H_

#ifdef __cplusplus
extern "C" {
#endif


#if defined(_DEBUG) && !defined(WIN32) && !defined(WIN64)
#define _GX2_ENABLE_RESOURCE_TRACKER    1
#endif


/// @addtogroup GX2RGroup
/// @{


#define GX2R_SURFACE_ALL_MIPS       -1 /// used to indicate entire mipchain


/// \brief Flags to control GX2R debug options
typedef enum _GX2RDebugOptions
{
    /// Resource tracking is completely disabled (default)
    GX2R_DEBUG_NONE                         = 0,
    /// Add guard bands to allocations, check in major operations like Unlock() and Destroy()
    GX2R_DEBUG_GUARD_BANDS_ENABLED          = (1<<0),
    /// Aggressively check guard bands in all GX2R APIs (GX2R_DEBUG_GUARD_BANDS_ENABLED must be on also)
    GX2R_DEBUG_GUARD_BANDS_CHECK_ALWAYS     = (1<<1),
    /// At shutdown dump out any resources not destroyed
    GX2R_DEBUG_LEAK_CHECK                   = (1<<2),
    /// Check if resources are modified or destroyed before or during being read/written by in-flight GPU operations
    GX2R_DEBUG_CHECK_GPU_CONTENTION         = (1<<3),
} GX2RDebugOptions;


/// \brief Flags to describe the type, semantics and options of a \ref GX2RBuffer object.
/// \note These flags extend the \ref GX2SurfaceUse enum.
typedef enum _GX2RResourceFlags
{
    GX2R_RESOURCE_FLAGS_NONE        = 0,

    /// Buffer type flags. Note \ref GX2RBuffer cannot be a surface type, but these flags are also in \ref GX2Surface.
    GX2R_BIND_NONE                  = 0,
    GX2R_BIND_TEXTURE               = GX2_SURFACE_USE_TEXTURE,
    GX2R_BIND_COLOR_BUFFER          = GX2_SURFACE_USE_COLOR_BUFFER,
    GX2R_BIND_DEPTH_BUFFER          = GX2_SURFACE_USE_DEPTH_BUFFER,
    GX2R_BIND_SCAN_BUFFER           = GX2_SURFACE_USE_SCAN_BUFFER,
    GX2R_BIND_VERTEX_BUFFER         = (1<<4),
    GX2R_BIND_INDEX_BUFFER          = (1<<5),
    GX2R_BIND_UNIFORM_BLOCK         = (1<<6),
    GX2R_BIND_SHADER_PROGRAM        = (1<<7),
    GX2R_BIND_STREAM_OUTPUT         = (1<<8),
    GX2R_BIND_DISPLAY_LIST          = (1<<9),
    GX2R_BIND_GS_RING               = (1<<10),

    /// Usage semantics, helps determine correct cache invalidation
    GX2R_USAGE_NONE                 = 0,
    GX2R_USAGE_CPU_READ             = (1<<11),
    GX2R_USAGE_CPU_WRITE            = (1<<12),
    GX2R_USAGE_GPU_READ             = (1<<13),
    GX2R_USAGE_GPU_WRITE            = (1<<14),
    GX2R_USAGE_DMA_READ             = (1<<15),
    GX2R_USAGE_DMA_WRITE            = (1<<16),
    GX2R_USAGE_FORCE_MEM1           = (1<<17),
    GX2R_USAGE_FORCE_MEM2           = (1<<18),
    /// Convenience
    /// If no FORCE_MEM flag is specified, let the allocator decide based on the type
    GX2R_USAGE_MEM_DEFAULT          = 0,
    GX2R_USAGE_CPU_READWRITE        = GX2R_USAGE_CPU_READ | GX2R_USAGE_CPU_WRITE,
    GX2R_USAGE_GPU_READWRITE        = GX2R_USAGE_GPU_READ | GX2R_USAGE_GPU_WRITE,
    GX2R_USAGE_NON_CPU_WRITE        = GX2R_USAGE_GPU_WRITE | GX2R_USAGE_DMA_WRITE,

    /// Flags to override default behaviour in GX2R APIs. If specified at creation
    /// they are the default for that buffer, or can be passed to some functions
    /// to override on a per-call basis.
    /// Generally these flags should be avoided except in special cases, e.g. batching up GPU invalidation in high volume
    /// cases such as uniform blocks.
    GX2R_OPTION_NONE                = 0,
    /// Don't check for CPU-GPU synchronization problems
    GX2R_OPTION_IGNORE_IN_USE       = (1<<19),
    GX2R_OPTION_FIRST               = GX2R_OPTION_IGNORE_IN_USE,
    /// Skip CPU cache invalidation
    GX2R_OPTION_NO_CPU_INVALIDATE   = (1<<20),
    /// Skip GPU cache invalidation
    GX2R_OPTION_NO_GPU_INVALIDATE   = (1<<21),
    /// Lock the buffer for read-only access.
    /// Only valid in optionFlags to \ref GX2RLockBuffer, \ref GX2RLockBufferEx, \ref GX2RLockBufferRegion, \ref GX2RLockSurface.
    GX2R_OPTION_LOCK_READONLY       = (1<<22),
    /// Don't touch the memory when destroying the buffer.
    /// Only valid in optionFlags to \ref GX2RDestroyBuffer.
    GX2R_OPTION_NO_TOUCH_DESTROY    = (1<<23),
    // NOTE: make sure FIRST/LAST are correct if you add/delete - must be lowest/highest values!
    GX2R_OPTION_LAST               = GX2R_OPTION_NO_TOUCH_DESTROY,
    /// Convenience
    GX2R_OPTION_NO_INVALIDATE       = GX2R_OPTION_NO_CPU_INVALIDATE | GX2R_OPTION_NO_GPU_INVALIDATE,
    GX2R_OPTION_MASK                = ((GX2R_OPTION_LAST | (GX2R_OPTION_LAST-1)) & ~(GX2R_OPTION_FIRST-1)),

    GX2R_RESOURCE_FLAG_RESERVED2    = (1<<28),
    GX2R_RESOURCE_FLAG_RESERVED1    = (1<<29),
    GX2R_RESOURCE_FLAG_RESERVED0    = (1<<30),
    //GX2_SURFACE_USE_FTV                      = (1<<31), // modifier, designates a final TV render target
} GX2RResourceFlags;


/// \brief This is the main buffer object representing various resource types within GX2.
///
/// \note For most types the buffer is treated as array-of-structs to allow for debug range checking.
/// Surfaces (textures, color buffers, depth buffers) are described by \ref GX2Surface.
/// See \ref GX2ResourceManagementPage for more info.
typedef struct _GX2RBuffer
{
    /// buffer type, semantics and options (see \ref GX2RResourceFlags)
    GX2RResourceFlags   resourceFlags;
    /// size of each element
    u32                 elementSize;
    /// number of elements
    u32                 elementCount;

//private:
    /// internal - must be initialised to 0
    u32                 reserved[1];
} GX2RBuffer;

/// As per \ref GX2SetBitFlags but with \ref GX2RResourceFlags
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2RSetResourceFlags(GX2RResourceFlags* pFlags, u32 bits)               { *pFlags = (GX2RResourceFlags)((u32)(*pFlags) | bits); }

/// As per \ref GX2ClearBitFlags but with \ref GX2RResourceFlags
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2RClearResourceFlags(GX2RResourceFlags* pFlags, u32 bits)             { *pFlags = (GX2RResourceFlags)(*pFlags & ~bits); }

/// As per \ref GX2MaskBitFlags but with \ref GX2RResourceFlags
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2RMaskResourceFlags(GX2RResourceFlags* pFlags, u32 bits)              { *pFlags = (GX2RResourceFlags)(*pFlags & bits); }

/// As per \ref GX2ReplaceBitFlags but with \ref GX2RResourceFlags
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2_INLINE void GX2RReplaceResourceFlags(GX2RResourceFlags* pFlags, u32 mask, u32 bits) { *pFlags = (GX2RResourceFlags)((*pFlags & ~mask) | (bits & mask)); }


/// \brief Returns GX2_TRUE if the flags say the resource was created via user memory, GX2_FALSE if it was via the allocator callback
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2Boolean GX2API GX2RIsUserMemory(GX2RResourceFlags resourceFlags);



/// \brief Allocator callback type. Called from GX2RCreateBuffer()
///
/// \param resourceFlags    GX2RResourceFlags passed to GX2RCreateBuffer
/// \param byteCount        Size in bytes of the memory required for the buffer allocation
/// \param alignment        Alignment requirement of the memory for the buffer allocation
typedef void* (*GX2RAllocateFunc)(GX2RResourceFlags resourceFlags, u32 byteCount, u32 alignment);

/// \brief Free callback type.
///
/// \param resourceFlags    resourceFlags of the buffer or surface being freed
/// \param pMem             The memory block to be freed
typedef void (*GX2RFreeFunc)(GX2RResourceFlags resourceFlags, void* pMem);

/// \brief Set an allocator callback for \ref GX2RCreateBuffer.
///
/// \param pfnAlloc Pointer to a user-supplied allocation function
/// \param pfnFree  Pointer to a user-supplied free function
///
/// \note The DEMO library allocation/free function source is available for reference in the
/// SDK source or the \ref GX2ResourceManagementPage
///
/// \donotcall \gx2_typical \enddonotcall
///
void GX2API GX2RSetAllocator(GX2RAllocateFunc pfnAlloc, GX2RFreeFunc pfnFree);


/// \brief Set global debug options, see \ref GX2RDebugOptions
///
/// \param debugOptions Bit-field of GX2R debugging options
///
/// \note You can still set and get the debug options in release builds, so code behaviour
/// doesn't change, however they will have no effect.
/// If you call this from more than one place you can query with \ref GX2RGetDebugOptions
/// and set/clear existing flags.
///
/// \note The default GX2R option is GX2R_DEBUG_NONE which disables
/// resource tracking. When resource tracking is required, make sure
/// to enable debugging before allocating buffers using GX2R.
///
/// \warning Once resource tracking is enabled it cannot be turned off.
///
///
/// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
///
void GX2API GX2RSetDebugOptions(GX2RDebugOptions debugOptions);


/// \brief Get global debug options, see \ref GX2RDebugOptions
///
/// \donotcall \threadsafe \devonly \enddonotcall
///
GX2RDebugOptions GX2API GX2RGetDebugOptions(void);



/// @}

#ifdef __cplusplus
}
#endif

#endif