1 /*---------------------------------------------------------------------------*
2
3 Copyright (C) 2010-2011 Nintendo. All rights reserved.
4
5 These coded instructions, statements, and computer programs contain
6 proprietary information of Nintendo of America Inc. and/or Nintendo
7 Company Ltd., and are protected by Federal copyright law. They may
8 not be disclosed to third parties or copied or duplicated in any form,
9 in whole or in part, without the prior written consent of Nintendo.
10
11 *---------------------------------------------------------------------------*/
12
13 #ifndef _CAFE_GX2R_RESOURCE_H_
14 #define _CAFE_GX2R_RESOURCE_H_
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20
21 #if defined(_DEBUG) && !defined(WIN32) && !defined(WIN64)
22 #define _GX2_ENABLE_RESOURCE_TRACKER 1
23 #endif
24
25
26 /// @addtogroup GX2RGroup
27 /// @{
28
29
30 #define GX2R_SURFACE_ALL_MIPS -1 /// used to indicate entire mipchain
31
32
33 /// \brief Flags to control GX2R debug options
34 typedef enum _GX2RDebugOptions
35 {
36 /// Resource tracking is completely disabled (default)
37 GX2R_DEBUG_NONE = 0,
38 /// Add guard bands to allocations, check in major operations like Unlock() and Destroy()
39 GX2R_DEBUG_GUARD_BANDS_ENABLED = (1<<0),
40 /// Aggressively check guard bands in all GX2R APIs (GX2R_DEBUG_GUARD_BANDS_ENABLED must be on also)
41 GX2R_DEBUG_GUARD_BANDS_CHECK_ALWAYS = (1<<1),
42 /// At shutdown dump out any resources not destroyed
43 GX2R_DEBUG_LEAK_CHECK = (1<<2),
44 /// Check if resources are modified or destroyed before or during being read/written by in-flight GPU operations
45 GX2R_DEBUG_CHECK_GPU_CONTENTION = (1<<3),
46 } GX2RDebugOptions;
47
48
49 /// \brief Flags to describe the type, semantics and options of a \ref GX2RBuffer object.
50 /// \note These flags extend the \ref GX2SurfaceUse enum.
51 typedef enum _GX2RResourceFlags
52 {
53 GX2R_RESOURCE_FLAGS_NONE = 0,
54
55 /// Buffer type flags. Note \ref GX2RBuffer cannot be a surface type, but these flags are also in \ref GX2Surface.
56 GX2R_BIND_NONE = 0,
57 GX2R_BIND_TEXTURE = GX2_SURFACE_USE_TEXTURE,
58 GX2R_BIND_COLOR_BUFFER = GX2_SURFACE_USE_COLOR_BUFFER,
59 GX2R_BIND_DEPTH_BUFFER = GX2_SURFACE_USE_DEPTH_BUFFER,
60 GX2R_BIND_SCAN_BUFFER = GX2_SURFACE_USE_SCAN_BUFFER,
61 GX2R_BIND_VERTEX_BUFFER = (1<<4),
62 GX2R_BIND_INDEX_BUFFER = (1<<5),
63 GX2R_BIND_UNIFORM_BLOCK = (1<<6),
64 GX2R_BIND_SHADER_PROGRAM = (1<<7),
65 GX2R_BIND_STREAM_OUTPUT = (1<<8),
66 GX2R_BIND_DISPLAY_LIST = (1<<9),
67 GX2R_BIND_GS_RING = (1<<10),
68
69 /// Usage semantics, helps determine correct cache invalidation
70 GX2R_USAGE_NONE = 0,
71 GX2R_USAGE_CPU_READ = (1<<11),
72 GX2R_USAGE_CPU_WRITE = (1<<12),
73 GX2R_USAGE_GPU_READ = (1<<13),
74 GX2R_USAGE_GPU_WRITE = (1<<14),
75 GX2R_USAGE_DMA_READ = (1<<15),
76 GX2R_USAGE_DMA_WRITE = (1<<16),
77 GX2R_USAGE_FORCE_MEM1 = (1<<17),
78 GX2R_USAGE_FORCE_MEM2 = (1<<18),
79 /// Convenience
80 /// If no FORCE_MEM flag is specified, let the allocator decide based on the type
81 GX2R_USAGE_MEM_DEFAULT = 0,
82 GX2R_USAGE_CPU_READWRITE = GX2R_USAGE_CPU_READ | GX2R_USAGE_CPU_WRITE,
83 GX2R_USAGE_GPU_READWRITE = GX2R_USAGE_GPU_READ | GX2R_USAGE_GPU_WRITE,
84 GX2R_USAGE_NON_CPU_WRITE = GX2R_USAGE_GPU_WRITE | GX2R_USAGE_DMA_WRITE,
85
86 /// Flags to override default behaviour in GX2R APIs. If specified at creation
87 /// they are the default for that buffer, or can be passed to some functions
88 /// to override on a per-call basis.
89 /// Generally these flags should be avoided except in special cases, e.g. batching up GPU invalidation in high volume
90 /// cases such as uniform blocks.
91 GX2R_OPTION_NONE = 0,
92 /// Don't check for CPU-GPU synchronization problems
93 GX2R_OPTION_IGNORE_IN_USE = (1<<19),
94 GX2R_OPTION_FIRST = GX2R_OPTION_IGNORE_IN_USE,
95 /// Skip CPU cache invalidation
96 GX2R_OPTION_NO_CPU_INVALIDATE = (1<<20),
97 /// Skip GPU cache invalidation
98 GX2R_OPTION_NO_GPU_INVALIDATE = (1<<21),
99 /// Lock the buffer for read-only access.
100 /// Only valid in optionFlags to \ref GX2RLockBuffer, \ref GX2RLockBufferEx, \ref GX2RLockBufferRegion, \ref GX2RLockSurface.
101 GX2R_OPTION_LOCK_READONLY = (1<<22),
102 /// Don't touch the memory when destroying the buffer.
103 /// Only valid in optionFlags to \ref GX2RDestroyBuffer.
104 GX2R_OPTION_NO_TOUCH_DESTROY = (1<<23),
105 // NOTE: make sure FIRST/LAST are correct if you add/delete - must be lowest/highest values!
106 GX2R_OPTION_LAST = GX2R_OPTION_NO_TOUCH_DESTROY,
107 /// Convenience
108 GX2R_OPTION_NO_INVALIDATE = GX2R_OPTION_NO_CPU_INVALIDATE | GX2R_OPTION_NO_GPU_INVALIDATE,
109 GX2R_OPTION_MASK = ((GX2R_OPTION_LAST | (GX2R_OPTION_LAST-1)) & ~(GX2R_OPTION_FIRST-1)),
110
111 GX2R_RESOURCE_FLAG_RESERVED2 = (1<<28),
112 GX2R_RESOURCE_FLAG_RESERVED1 = (1<<29),
113 GX2R_RESOURCE_FLAG_RESERVED0 = (1<<30),
114 //GX2_SURFACE_USE_FTV = (1<<31), // modifier, designates a final TV render target
115 } GX2RResourceFlags;
116
117
118 /// \brief This is the main buffer object representing various resource types within GX2.
119 ///
120 /// \note For most types the buffer is treated as array-of-structs to allow for debug range checking.
121 /// Surfaces (textures, color buffers, depth buffers) are described by \ref GX2Surface.
122 /// See \ref GX2ResourceManagementPage for more info.
123 typedef struct _GX2RBuffer
124 {
125 /// buffer type, semantics and options (see \ref GX2RResourceFlags)
126 GX2RResourceFlags resourceFlags;
127 /// size of each element
128 u32 elementSize;
129 /// number of elements
130 u32 elementCount;
131
132 //private:
133 /// internal - must be initialised to 0
134 u32 reserved[1];
135 } GX2RBuffer;
136
137 /// As per \ref GX2SetBitFlags but with \ref GX2RResourceFlags
138 ///
139 /// \donotcall \threadsafe \devonly \enddonotcall
140 ///
GX2RSetResourceFlags(GX2RResourceFlags * pFlags,u32 bits)141 GX2_INLINE void GX2RSetResourceFlags(GX2RResourceFlags* pFlags, u32 bits) { *pFlags = (GX2RResourceFlags)((u32)(*pFlags) | bits); }
142
143 /// As per \ref GX2ClearBitFlags but with \ref GX2RResourceFlags
144 ///
145 /// \donotcall \threadsafe \devonly \enddonotcall
146 ///
GX2RClearResourceFlags(GX2RResourceFlags * pFlags,u32 bits)147 GX2_INLINE void GX2RClearResourceFlags(GX2RResourceFlags* pFlags, u32 bits) { *pFlags = (GX2RResourceFlags)(*pFlags & ~bits); }
148
149 /// As per \ref GX2MaskBitFlags but with \ref GX2RResourceFlags
150 ///
151 /// \donotcall \threadsafe \devonly \enddonotcall
152 ///
GX2RMaskResourceFlags(GX2RResourceFlags * pFlags,u32 bits)153 GX2_INLINE void GX2RMaskResourceFlags(GX2RResourceFlags* pFlags, u32 bits) { *pFlags = (GX2RResourceFlags)(*pFlags & bits); }
154
155 /// As per \ref GX2ReplaceBitFlags but with \ref GX2RResourceFlags
156 ///
157 /// \donotcall \threadsafe \devonly \enddonotcall
158 ///
GX2RReplaceResourceFlags(GX2RResourceFlags * pFlags,u32 mask,u32 bits)159 GX2_INLINE void GX2RReplaceResourceFlags(GX2RResourceFlags* pFlags, u32 mask, u32 bits) { *pFlags = (GX2RResourceFlags)((*pFlags & ~mask) | (bits & mask)); }
160
161
162 /// \brief Returns GX2_TRUE if the flags say the resource was created via user memory, GX2_FALSE if it was via the allocator callback
163 ///
164 /// \donotcall \threadsafe \devonly \enddonotcall
165 ///
166 GX2Boolean GX2API GX2RIsUserMemory(GX2RResourceFlags resourceFlags);
167
168
169
170 /// \brief Allocator callback type. Called from GX2RCreateBuffer()
171 ///
172 /// \param resourceFlags GX2RResourceFlags passed to GX2RCreateBuffer
173 /// \param byteCount Size in bytes of the memory required for the buffer allocation
174 /// \param alignment Alignment requirement of the memory for the buffer allocation
175 typedef void* (*GX2RAllocateFunc)(GX2RResourceFlags resourceFlags, u32 byteCount, u32 alignment);
176
177 /// \brief Free callback type.
178 ///
179 /// \param resourceFlags resourceFlags of the buffer or surface being freed
180 /// \param pMem The memory block to be freed
181 typedef void (*GX2RFreeFunc)(GX2RResourceFlags resourceFlags, void* pMem);
182
183 /// \brief Set an allocator callback for \ref GX2RCreateBuffer.
184 ///
185 /// \param pfnAlloc Pointer to a user-supplied allocation function
186 /// \param pfnFree Pointer to a user-supplied free function
187 ///
188 /// \note The DEMO library allocation/free function source is available for reference in the
189 /// SDK source or the \ref GX2ResourceManagementPage
190 ///
191 /// \donotcall \gx2_typical \enddonotcall
192 ///
193 void GX2API GX2RSetAllocator(GX2RAllocateFunc pfnAlloc, GX2RFreeFunc pfnFree);
194
195
196 /// \brief Set global debug options, see \ref GX2RDebugOptions
197 ///
198 /// \param debugOptions Bit-field of GX2R debugging options
199 ///
200 /// \note You can still set and get the debug options in release builds, so code behaviour
201 /// doesn't change, however they will have no effect.
202 /// If you call this from more than one place you can query with \ref GX2RGetDebugOptions
203 /// and set/clear existing flags.
204 ///
205 /// \note The default GX2R option is GX2R_DEBUG_NONE which disables
206 /// resource tracking. When resource tracking is required, make sure
207 /// to enable debugging before allocating buffers using GX2R.
208 ///
209 /// \warning Once resource tracking is enabled it cannot be turned off.
210 ///
211 ///
212 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
213 ///
214 void GX2API GX2RSetDebugOptions(GX2RDebugOptions debugOptions);
215
216
217 /// \brief Get global debug options, see \ref GX2RDebugOptions
218 ///
219 /// \donotcall \threadsafe \devonly \enddonotcall
220 ///
221 GX2RDebugOptions GX2API GX2RGetDebugOptions(void);
222
223
224
225 /// @}
226
227 #ifdef __cplusplus
228 }
229 #endif
230
231 #endif
232