1 /*---------------------------------------------------------------------------*
2
3 Copyright (C) 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_SURFACE_H_
14 #define _CAFE_GX2R_SURFACE_H_
15
16
17
18 #ifdef __cplusplus
19 extern "C"
20 {
21 #endif // __cplusplus
22
23
24 /// @addtogroup GX2RGroup
25 /// @{
26
27
28 /// \brief \ref GX2RDestroySurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
29 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \userheap \devonly \enddonotcall
30 ///
31 void GX2API GX2RDestroySurfaceEx(GX2Surface* gx2Surface, GX2RResourceFlags optionFlags);
32
33 /// \brief \ref GX2RLockSurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
34 ///
35 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
36 ///
37 void* GX2API GX2RLockSurfaceEx(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);
38
39 /// \brief \ref GX2RUnlockSurface but with GX2R_OPTION flags (see \ref GX2RResourceFlags)
40 ///
41 /// \donotcall \gx2_typical \enddonotcall
42 ///
43 /// \writesgpu
44 /// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
45 ///
46 void GX2API GX2RUnlockSurfaceEx(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);
47
48 /// \brief Create a surface.
49 ///
50 /// \param gx2Surface Address of a filled-in \ref GX2Surface struct.
51 /// \param resourceFlags Type, usage and options for the surface.
52 /// \return GX2_TRUE if creation succeeds, GX2_FALSE otherwise
53 ///
54 /// \note This function will allocate the memory via the allocator callback (see \ref GX2RSetAllocator).
55 /// See \ref GX2RCreateBufferUserMemory for cache behavior and notes.
56 ///
57 /// \donotcall \gx2_typical \userheap \enddonotcall
58 ///
59 GX2Boolean GX2API GX2RCreateSurface(GX2Surface* gx2Surface, GX2RResourceFlags resourceFlags);
60
61 /// \brief Create a surface from user supplied memory.
62 ///
63 /// \param gx2Surface Address of a filled-in \ref GX2Surface struct.
64 /// \param imagePtr Pointer to existing memory for the surface main image.
65 /// \param mipPtr Pointer to existing memory for the surface mip chain, or NULL.
66 /// \param resourceFlags Type, usage and options for the surface.
67 /// \return GX2_TRUE if creation succeeds, GX2_FALSE otherwise
68 ///
69 /// \note This function will perform any necessary cache invalidation.
70 /// \ref GX2RCreateSurface should be used in preference to this version except where absolutely necessary.
71 /// \ref GX2RDestroySurface must still be called for user memory surfaces.
72 ///
73 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
74 ///
75 GX2Boolean GX2API GX2RCreateSurfaceUserMemory(GX2Surface* gx2Surface, void* imagePtr, void* mipPtr, GX2RResourceFlags resourceFlags);
76
77 /// \brief Destroy a surface.
78 ///
79 /// \param gx2Surface Address of a \ref GX2Surface struct.
80 ///
81 /// \note Memory will be freed via the default allocator or user callback.
82 /// If the buffer was created from user memory via \ref GX2RCreateSurfaceUserMemory this function is
83 /// still necessary to mark the buffer as deleted.
84 /// Destroying a surface that was never created or has already been destroyed is not an error.
85 ///
86 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \userheap \devonly \enddonotcall
87 ///
GX2RDestroySurface(GX2Surface * gx2Surface)88 GX2_INLINE void GX2RDestroySurface(GX2Surface* gx2Surface)
89 {
90 GX2RDestroySurfaceEx(gx2Surface, GX2R_OPTION_NONE);
91 }
92
93 /// \brief Lock a surface and return a pointer to the memory.
94 ///
95 /// \param gx2Surface Address of a \ref GX2Surface struct.
96 /// \param mipLevel 0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
97 /// \return Memory address of the start of the buffer
98 ///
99 /// \note The surface memory may be read or written by the CPU or via DMA transfer (or even the GPU),
100 /// however it is imperative the correct usage GX2RUsageFlags are set.
101 /// \ref GX2RUnlockSurface must be called before the surface is used by any other GX2R APIs.
102 ///
103 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
104 ///
GX2RLockSurface(const GX2Surface * gx2Surface,s32 mipLevel)105 GX2_INLINE void* GX2RLockSurface(const GX2Surface* gx2Surface, s32 mipLevel)
106 {
107 return GX2RLockSurfaceEx(gx2Surface, mipLevel, GX2R_OPTION_NONE);
108 }
109
110 /// \brief Unlock a surface.
111 ///
112 /// \param gx2Surface Address of a \ref GX2Surface struct.
113 /// \param mipLevel 0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
114 ///
115 /// \note This function will perform any necessary cache invalidation.
116 /// The memory pointer must not be used after the surface is unlocked.
117 ///
118 /// \donotcall \gx2_typical \enddonotcall
119 ///
120 /// \writesgpu
121 /// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
122 ///
GX2RUnlockSurface(const GX2Surface * gx2Surface,s32 mipLevel)123 GX2_INLINE void GX2RUnlockSurface(const GX2Surface* gx2Surface, s32 mipLevel)
124 {
125 GX2RUnlockSurfaceEx(gx2Surface, mipLevel, GX2R_OPTION_NONE);
126 }
127
128 /// \brief Returns true if the surface has memory allocated, that is, created but not yet destroyed
129 /// \param gx2Surface Address of a \ref GX2Surface struct.
130 ///
131 /// \donotcall \threadsafe \devonly \enddonotcall
132 ///
133 GX2Boolean GX2API GX2RSurfaceExists(const GX2Surface* gx2Surface);
134
135 /// \brief Give the surface a meaningful name for debug and profiling.
136 //
137 /// \param gx2Surface Address of a \ref GX2Surface struct.
138 /// \param name Name string. Copied into the API.
139 ///
140 /// \note Ignored in release builds.
141 /// Surface must have memory allocated (i.e. \ref GX2RSurfaceExists is true) when this is called.
142 ///
143 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
144 ///
145 void GX2API GX2RSetSurfaceName(const GX2Surface* gx2Surface, const char* name);
146
147 /// \brief Get surface debug name - see \ref GX2RSetSurfaceName
148 ///
149 /// \param gx2Surface Address of a \ref GX2Surface struct.
150 ///
151 /// \donotcall \fgonly \notthreadsafe \notinterrupt \notexception \devonly \enddonotcall
152 ///
153 const char* GX2API GX2RGetSurfaceName(const GX2Surface* gx2Surface);
154
155
156 /// \brief Utility function to perform correct cache invalidation for the given surface
157 ///
158 /// \param gx2Surface Address of a \ref GX2Surface struct.
159 /// \param mipLevel 0 for main image, >=1 for mip, GX2R_SURFACE_ALL_MIPS for entire mipmap chain
160 /// \param optionFlags The OPTION values are used instead of surface resourceFlags (i.e. surface NO_INVALIDATE flags will be ignored)
161 ///
162 /// \note Typically when using the GX2R APIs this will not be necessary, however it is useful when using \ref GX2RResourceFlags
163 /// to suppress invalidation within the API.
164 /// See also \ref GX2RInvalidateMemory
165 ///
166 /// \donotcall \gx2_typical \enddonotcall
167 ///
168 /// \writesgpu
169 /// \writesgpu{if the buffer resource usage is any GPU usable type (e.g. \ref GX2R_BIND_VERTEX_BUFFER)}
170 ///
171 void GX2API GX2RInvalidateSurface(const GX2Surface* gx2Surface, s32 mipLevel, GX2RResourceFlags optionFlags);
172
173
174 /// \brief Test if the surface resourceFlags indicate it was created with \ref GX2RCreateSurface
175 ///
176 /// \donotcall \threadsafe \devonly \enddonotcall
177 ///
178 GX2Boolean GX2RIsGX2RSurface(GX2RResourceFlags resourceFlags);
179
180
181 /// @}
182
183 #ifdef __cplusplus
184 }
185 #endif // __cplusplus
186
187 #endif
188