In general, the nn::gd::Resource
class defines functions that handle resource objects.
The nn::gd::Resource
class can create and release resource objects. It can also get detailed information and data pointers for overwriting data.
3.1. Texture 2D Resources
Texture 2D resources are resources that have a width and height, such as texture images and color buffers. These resources are handled by Texture2DResource
objects.
3.1.1. Creating a Texture2DResource Object
You can use the nn::gd::Resource::CreateTexture2DResource()
function to create Texture2DResource
objects.
static nnResult nn::gd::Resource::CreateTexture2DResource( const nn::gd::Texture2DResourceDescription* description, const void* initialData, gdBool autoGenerateMipMapsFromData, nn::gd::Texture2DResource** texture2DResource, gdBool copyInitialData = GD_TRUE);
Set resource information in a descriptor object (Texture2DResourceDescription
) specified by the description
parameter. Further details on descriptor class settings are provided in 3.1.1.2. Descriptor Class for Texture2DResource Objects.
If you are creating a resource that has initial data, such as texture data loaded from a file, specify the starting address of that data in the initialData
parameter. If you specify GD_TRUE
for the copyInitialData
parameter, the initial data is copied to the memory specified by the descriptor class when the resource is created. Because this function adds a DMA transfer command request to the command list when the resource data is allocated in VRAM, do not overwrite or deallocate the memory region that contains the initial data until the command list finishes executing. If you specify GD_FALSE
for copyInitialData
, the address specified in initialData
is used as the resource. Note that if a resource contains mipmap data, you must allocate enough memory to store all of it. You also need to pay attention to memory alignment. Applications are responsible for deallocating resource memory.
Specify NULL
for initialData
when you create resources that do not have initial data. A memory region large enough to hold the resource data will be allocated from the memory specified in the descriptor class.
Specify GD_TRUE
for the autoGenerateMipMapsFromData
parameter if you want texture mipmaps to be automatically generated from the initial data. For more information about generating mipmaps automatically, see 3.1.7. Generating Mipmaps Automatically.
Use the pointer that the function sets in texture2DResource
to access the Texture2DResource
object that you have created.
3.1.1.1. Helper Functions for Converting Textures Into the Native Format
You must specify initial data in the native 3DS format when you create Texture2DResource
objects to be pasted as textures on 3D models. The nn::gd::Resource::Helper
class provides helper functions for converting standard textures, such as those used by OpenGL, into the native 3DS format. However, these helper functions have a high processing load and are not well-suited for runtime processing.
There are different helper functions for converting compressed and uncompressed textures, but with the exception of the source pixel format they accept the same arguments.
static nnResult nn::gd::Resource::Helper::ConvertTextureResourceToNativeFormat( nn::gd::Resource::Format format, u32 width, u32 height, const u8* dataSrc, u8* dataDst, nn::gd::Resource::NativeFormat* pnativeFormat = NULL); static nnResult nn::gd::Resource::Helper::ConvertCompressedTextureResourceToNativeFormat( nn::gd::Resource::CompressedFormat format, u32 width, u32 height, u8* dataSrc, u8* dataDst, nn::gd::Resource::NativeFormat* pnativeFormat = NULL);
Specify the original pixel format in the format
parameter.
You can specify the following pixel formats to the ConvertTextureResourceToNativeFormat()
function.
FORMAT_RGBA_8888
FORMAT_RGB_888
FORMAT_RGBA_5551
FORMAT_RGB_565
FORMAT_RGBA_4444
FORMAT_LUMINANCE_ALPHA_88
FORMAT_HILO_88
FORMAT_LUMINANCE_8
FORMAT_ALPHA_8
FORMAT_LUMINANCE_ALPHA_44
FORMAT_LUMINANCE_4
FORMAT_ALPHA_4
You can specify the following pixel format in the ConvertCompressedTextureResourceToNativeFormat()
function.
FORMAT_ETC1_RGB8
Depending on the pixel format, a buffer large enough to hold the data to convert is temporarily allocated from device memory. A temporary buffer is always allocated when the same address is specified for both dataSrc
and dataDst
.
For more information about the differences between the standard and native texture formats, see the 3DS Programming Manual: Basic Graphics.
3.1.1.2. Descriptor Class for Texture2DResource Objects
This section introduces the member variables of the descriptor class (Texture2DResourceDescription
) for Texture2DResource
objects, and describes setting-related cautions and information.
class nn::gd::Texture2DResourceDescription { u32 m_Width; u32 m_Height; u32 m_CountMipLevels; nn::gd::Resource::NativeFormat m_Format; nn::gd::Memory::MemoryLayout m_MemLayout; nn::gd::Memory::MemoryLocation m_MemLocation; };
Width (m_Width)
Sets the width of the resource data in pixels. Specify the width of the top-level texture data for any texture that has mipmaps.
Height (m_Height)
Sets the height of the resource data in pixels. Specify the height of the top-level texture data for any texture that has mipmaps.
Mipmap Levels (m_CountMipLevels)
Sets the number of mipmap levels in resource data that has mipmaps. Specify a value of 1
for any texture that does not have mipmaps. Specifying a value of 0
is the same as specifying the maximum number of mipmap levels possible for the resource data's width and height.
Pixel Format (m_Format)
The pixel formats that you can specify for a resource depend upon how you plan to use it.
The following table shows which pixel formats can be specified for texture data (Texture2D
or TextureCube
objects), color buffers (RenderTarget
objects), and depth stencil buffers (DepthStencilTarget
objects).
Pixel Formats | Texture2D | TextureCube | RenderTarget | DepthStencilTarget |
---|---|---|---|---|
Resource::NATIVE_FORMAT_RGBA_8888 1 |
○ | ○ | ○ | Error |
Resource::NATIVE_FORMAT_RGB_888 1 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_RGBA_5551 1 |
○ | ○ | ○ | Error |
Resource::NATIVE_FORMAT_RGB_565 1 |
○ | ○ | ○ | Error |
Resource::NATIVE_FORMAT_RGBA_4444 1 |
○ | ○ | ○ | Error |
Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_88 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_HILO_88 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_LUMINANCE_8 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_ALPHA_8 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_44 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_LUMINANCE_4 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_ALPHA_4 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_ETC1_RGB8 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_ETC1_A4 |
○ | ○ | Error | Error |
Resource::NATIVE_FORMAT_GAS 2 |
○ | Error | ○ | Error |
Resource::NATIVE_FORMAT_SHADOW 2 |
○ | ○ | ○ | Error |
Resource::NATIVE_FORMAT_DEPTH_16 |
○ | ○ | Error | ○ |
Resource::NATIVE_FORMAT_DEPTH_24 |
○ | ○ | Error | ○ |
Resource::NATIVE_FORMAT_DEPTH_24_STENCIL_8 |
○ | ○ | Error | ○ |
Note 1: Supports automatic mipmap generation.
Note 2: Does not support mipmaps.
Memory Layout (m_MemLayout)
You must specify Memory::LAYOUT_BLOCK_8
as the memory layout for (1) resource objects that are used to create Texture2D
and TextureCube
objects, or (2) resource objects that you create with initial data specified.
You can specify Memory::LAYOUT_BLOCK_8
or Memory::LAYOUT_BLOCK_32
as the memory layout for resource objects that are used to create RenderTarget
and DepthStencilTarget
objects.
You can specify Memory::LAYOUT_LINEAR
as the memory layout for any other resource objects.
Memory to Allocate for Resource Data (m_MemLocation)
Specifies the memory that will hold the resource data. You cannot create a RenderTarget
or DepthStencilTarget
object using a resource object created with Memory::FCRAM
(device memory) specified.
Memory Used to Hold Resource Data | Texture2D | TextureCube | RenderTarget | DepthStencilTarget |
---|---|---|---|---|
Memory::FCRAM (device memory) |
○ | ○ | Error | Error |
Memory::VRAMA (VRAM-A) |
○ | ○ | ○ | ○ |
Memory::VRAMB (VRAM-B) |
○ | ○ | ○ | ○ |
3.1.2. Releasing a Texture2DResource Object
Call the nn::gd::Resource::ReleaseTexture2DResource()
function to release a Texture2DResource
object. The memory region allocated to create the object is deallocated when the object is released.
static nnResult nn::gd::Resource::ReleaseTexture2DResource( nn::gd::Texture2DResource* texture2DResource);
3.1.3. Getting Detailed Information About a Texture2DResource Object
You can use the nn::gd::Resource::GetTexture2DResourceProperties()
function to get detailed information (using the Texture2DResourceProperties
class) stored in a Texture2DResource
object.
static nnResult nn::gd::Resource::GetTexture2DResourceProperties( const nn::gd::Texture2DResource* texture2DResource, nn::gd::Texture2DResourceProperties* properties);
When the function returns, the properties
parameter contains a pointer to the detailed information stored in the Texture2DResource
object that was specified in the texture2DResource
parameter. Ensure that you do not modify the content of the Texture2DResource
object through the pointer that is returned.
3.1.3.1. Detailed Information About a Texture2DResource Object
An object's detailed information (the Texture2DResourceProperties
class) has nearly the same settings as the descriptor class that was specified when the object was created.
class nn::gd::Texture2DResourceProperties { u32 m_Width; u32 m_Height; u32 m_CountMipLevels; u32 m_PixelSize; nn::gd::Resource::NativeFormat m_Format; nn::gd::Memory::MemoryLayout m_MemLayout; nn::gd::Memory::MemoryLocation m_MemLocation; u8* m_MemAddr; nn::gd::MipmapResourceInfo GetMipmapAddress(u32 mipmapLevel); };
The following member variables include only those that could differ from settings in the descriptor class or those that exist only in this class.
Mipmap Levels (m_CountMipLevels)
If a value of 0 is specified in the descriptor, this variable is configured with the maximum number of mipmap levels possible for the resource data's width and height.
Pixel Size (m_PixelSize)
This variable is configured with the number of bits in the resource data's pixel format.
Starting Address of Resource Data (m_MemAddr)
This variable specifies the physical starting address of the resource data.
Getting Address Information for Mipmap Data (GetMipMapAddress)
This variable defines a helper function that, given a mipmap level, gets address information (using the MipmapResourceInfo
class) for the mipmap data.
class nn::gd::MipmapResourceInfo { u32 m_Width; u32 m_Height; u8* m_MemAddr; };
This variable defines the width (m_Width
), height (m_Height
), and the data’s starting address (m_MemAddr
) of the mipmap data.
3.1.4. Getting a Data Pointer in a Texture2DResource Object
You can use the nn::gd::Resource::MapTexture2DResource()
function to get a data pointer for accessing resource data.
static nnResult nn::gd::Resource::MapTexture2DResource( nn::gd::Texture2DResource* texture2DResource, s32 mipLevelIndex, nn::gd::Resource::MapUsage usage, void** data); static nnResult nn::gd::Resource::UnmapTexture2DResource( nn::gd::Texture2DResource* texture2DResource);
This function returns a memory address in the data
parameter that indicates the starting address of the texture data, at the mipmap level specified by the mipLevelIndex
parameter, within the resource data of the Texture2DResource
object specified by the texture2DResource
parameter. Specify the following mapping methods (types of resource data access) in usage
.
Definition | Mapping Method | Device Memory | VRAM |
---|---|---|---|
Resource::MAP_READ_ONLY |
Read-only | ○ | ○ |
Resource::MAP_WRITE_ONLY |
Write-only | ○ | Error |
Resource::MAP_READ_WRITE |
Read/write | ○ | Error |
The mapping method is only checked when you get a data pointer. Although writing to the resource data in device memory obtained by MAP_READ_ONLY
does not result in an error, the cache is not flushed when the mapping is removed.
You cannot directly access resource data in VRAM. Use a DMA transfer or some other means to copy the data to memory that can be directly accessed by the CPU.
After you have finished accessing the resource data, remove the mapping using the nn::gd::Resource::UnmapTexture2DResource()
function. If you get a data pointer to resource data in device memory using a mapping method that includes writes, the cache is flushed when the mapping is removed.
3.1.5. Clearing Resource Data (Texture2DResource Objects)
You can clear resource data using a specified value. You can also specify a range of mipmap levels to clear in resources that have mipmap data. However, you cannot clear resource data allocated in device memory.
static nnResult nn::gd::Memory::ClearTexture2DResource( const nn::gd::Texture2DResource* tex2DResource, s32 mipLevelIndexStart, s32 mipLevelIndexEnd, const u8 Components[4]); static nnResult nn::gd::Memory::ClearTexture2DResource( const nn::gd::Texture2DResource* tex2DResource, s32 mipLevelIndexStart, s32 mipLevelIndexEnd, u32 value);
This function attempts to clear any resource when the value
parameter is specified, but it is limited to the following pixel formats when the Components
parameter is specified. The right side of the following figure shows how values specified to Components
are applied to the data to be cleared.
3.1.6. Partially Copying Resource Data (Texture2DResource Objects)
You can specify a mipmap level and rectangular region to create a partial copy of resource data. Its format is not converted because this function calls the nngxAddBlockImageCopyCommand()
function. Data is actually copied when the command list is executed.
static nnResult nn::gd::Memory::CopyTextureSubResource( const nn::gd::Texture2DResource* source, s32 srcMipLevelIndex, const nn::gd::Memory::Rect& rect, const nn::gd::Texture2DResource* dest, s32 dstMipLevelIndex, s32 destPosX, s32 destPosY);
The resource data and the viewport (LCD) use different origins, which this function takes into account. Specify the rectangular region (rect
) and the coordinates to copy to (destPosX
and destPosY
), based on the viewport's origin.
An error (the ResultInvalidTextureFormat()
function) is returned when the source and destination have different pixel sizes.
3.1.7. Generating Mipmaps Automatically
You can automatically generate mipmap data for Texture2DResource
objects.
static nnResult nn::gd::Memory::GenerateMipMaps( const nn::gd::Texture2DResource* tex2DResource, u32 mipLevelSourceIndex, s32 mipLevelLastDestinationIndex);
The Texture2DResource
object specified for tex2DResource
must be created so that it can hold the resource data generated for the mipmap levels. You can only generate mipmap data automatically for Texture2DResource
objects created in the following formats.
nn::gd::Resource::NATIVE_FORMAT_RGBA_8888
nn::gd::Resource::NATIVE_FORMAT_RGBA_5551
nn::gd::Resource::NATIVE_FORMAT_RGBA_4444
nn::gd::Resource::NATIVE_FORMAT_RGB_888
nn::gd::Resource::NATIVE_FORMAT_RGB_565
You can use the nn::gd::Resource::CreateTexture2DResourceCastFrom()
function to convert an object from a format that is not in this list to a format such as NATIVE_FORMAT_RGBA_8888
, which generates mipmap data. This method is not guaranteed to produce proper mipmap data, however, because pixels comprise different bits in each format.
Mipmap data is automatically generated from the level specified by the mipLevelSourceIndex
parameter to the level specified by the mipLevelLastDestinationIndex
parameter. To specify the maximum number of mipmap levels for that resource, specify a value of -1
for mipLevelLastDestinationIndex
.
3.1.7.1. Using the CPU to Generate Mipmaps Automatically
You can also call the nn::gd::Resource::Helper::GenerateMipMapsCPU()
function to generate mipmap data automatically. This function uses the CPU to generate mipmaps and is slower than nn::gd::Memory::GenerateMipMaps
, which uses the GPU, but it has the advantage of supporting more formats and allowing you to generate mipmap data with a minimum width and height of 8 pixels. (The minimum width and height is either 32 or 64 pixels, depending on the format, when the GPU is used.)
static nnResult nn::gd::Resource::Helper::GenerateMipMapsCPU( nn::gd::Resource::NativeFormat format, u32 width, u32 height, const u8* dataSrc, u8* dataDst, u32 countMipLevelToGenerate);
You can specify the following formats for the format
parameter.
nn::gd::Resource::NATIVE_FORMAT_RGBA_8888
nn::gd::Resource::NATIVE_FORMAT_RGBA_5551
nn::gd::Resource::NATIVE_FORMAT_RGBA_4444
nn::gd::Resource::NATIVE_FORMAT_RGB_888
nn::gd::Resource::NATIVE_FORMAT_RGB_565
nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_88
nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_44
nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_8
nn::gd::Resource::NATIVE_FORMAT_ALPHA_8
nn::gd::Resource::NATIVE_FORMAT_HILO_88
Specify the width and height of the original resource data in width
and height
, respectively. Both the width and height must be at least 8 and a power of 2.
Specify the starting address of the resource data in the dataSrc
parameter, and specify the address to store the mipmap data in the dataDst
parameter. Allocate enough memory to store all of the generated mipmap data.
For the countMipLevelToGenerate
parameter, specify the number of mipmap levels to generate.
3.1.8. Converting a Texture2DResource Object to Another Format
You can use the following function to convert an existing Texture2DResource
object to another format. This allows the resource data for RenderTarget
objects that were used for rendering (such as gas textures, shadow textures, and depth buffers) to be reused as texture data (resource data for Texture2D
objects).
static nnResult nn::gd::Resource::CreateTexture2DResourceCastFrom( const nn::gd::Texture2DResource* initialTexture2DResource, nn::gd::Resource::NativeFormat format, nn::gd::Memory::MemoryLayout layout, nn::gd::Texture2DResource** texture2DResource);
The object returned in the texture2DResource
parameter has the pixel format and memory layout of the Texture2DResource
object specified for the initialTexture2DResource
parameter changed to the values specified by the format
and layout
parameters, respectively. An error is returned if the two pixel formats are not compatible (if they have different pixel sizes).
This function creates a new Texture2DResource
object that contains modified format information. However, the data is not actually converted from one format to another, nor is data actually copied. The original object remains unchanged. All information other than the pixel format and memory layout, such as the location at which data is stored, remains unchanged. If you overwrite resource data using the object created by this function, you also overwrite the resource data of the original object.
3.2. Vertex Buffer Resources
Vertex buffer resources are vertex coordinates, vertex indices, and other resources that are used as vertex buffers. These resources are handled by VertexBufferResource
objects.
3.2.1. Creating a VertexBufferResource Object
You can use the nn::gd::Resource::CreateVertexBufferResource()
function to create VertexBufferResource
objects.
static nnResult nn::gd::Resource::CreateVertexBufferResource( const nn::gd::VertexBufferResourceDescription* description, const void* initialData, nn::gd::VertexBufferResource** buffer, gdBool copyInitialData = GD_TRUE);
Set resource information in a descriptor object (VertexBufferResourceDescription
) specified by the description
parameter. For more information about descriptor class settings, see 3.2.1.1. Descriptor Class for VertexBufferResource Objects.
If you are creating a resource that has initial data, such as vertex data loaded from a file, specify the starting address of that data in the initialData
parameter. If you specify GD_TRUE
for the copyInitialData
parameter, the initial data is copied to the memory specified by the descriptor class when the resource is created. Because this function adds a DMA transfer command request to the command list when the resource data is allocated in VRAM, do not overwrite or deallocate the memory region that contains the initial data until the command list finishes executing. Pay attention to the memory alignment of the address specified in initialData
, because it is used as the resource if you specify GD_FALSE
for copyInitialData
. Applications are responsible for deallocating resource memory.
Specify NULL
for initialData
when you create resources that do not have initial data. A memory region large enough to hold the resource data is allocated from the memory specified in the descriptor class.
The function sets a pointer in the buffer
parameter that you can use to access the VertexBufferResource
that it just created.
3.2.1.1. Descriptor Class for VertexBufferResource Objects
This section introduces the member variables of the descriptor class (VertexBufferResourceDescription
) for VertexBufferResource
objects and provides setting-related cautions and information.
class nn::gd::VertexBufferResourceDescription { u32 m_ByteSize; nn::gd::Memory::MemoryLocation m_MemLocation; };
Vertex Buffer Size (m_ByteSize)
Sets the number of bytes in the vertex buffer (resource data).
Memory to Allocate for Resource Data (m_MemLocation)
Specifies the memory that will hold the resource data.
The memory to be specified can be selected from Memory::FCRAM
(device memory), Memory::VRAMA
(VRAM-A), or Memory::VRAMB
(VRAM-B).
3.2.2. Releasing a VertexBufferResource Object
Call the nn::gd::Resource::ReleaseVertexBufferResource()
function to release a VertexBufferResource
object. The memory region allocated to create the object is deallocated when the object is released.
static nnResult nn::gd::Resource::ReleaseVertexBufferResource( nn::gd::VertexBufferResource *buffer);
3.2.3. Getting Detailed Information About a VertexBufferResource Object
You can use the nn::gd::Resource::GetVertexBufferResourceProperties()
function to get detailed information (using the VertexBufferResourceProperties
class) stored in a VertexBufferResource
object.
static nnResult nn::gd::Resource::GetVertexBufferResourceProperties( const nn::gd::VertexBufferResource* buffer, nn::gd::VertexBufferResourceProperties* properties);
This function sets a pointer in the properties
parameter that points to the detailed information stored in the VertexBufferResource
object specified in the buffer
parameter. Ensure that you do not modify the content of the VertexBufferResource
object using the pointer that you get.
3.2.3.1. Detailed Information About a VertexBufferResource Object
An object's detailed information (the VertexBufferResourceProperties
class) has nearly the same settings as the descriptor class that was specified when the object was created.
class nn::gd::VertexBufferResourceProperties { u32 m_ByteSize; nn::gd::Memory::MemoryLocation m_MemLocation; u8* m_MemAddr; };
The rest of this section describes member variables that only exist in this class.
Starting Address of Resource Data (m_MemAddr)
This variable specifies the physical starting address of the resource data.
3.2.4. Getting a Pointer to the Data in a VertexBufferResource Object
You can use the nn::gd::Resource::MapVertexBufferResource()
function to get a data pointer for accessing resource data.
static nnResult nn::gd::Resource::MapVertexBufferResource( nn::gd::VertexBufferResource* buffer, nn::gd::Resource::MapUsage usage, void** data); static nnResult nn::gd::Resource::UnmapVertexBufferResource( nn::gd::VertexBufferResource* buffer);
The starting address of the resource data for the VertexBufferResource
object specified by the buffer
parameter is returned in the data
parameter. Specify the following mapping methods (types of resource data access) in usage
.
Definition | Mapping Method | Device Memory | VRAM |
---|---|---|---|
Resource::MAP_READ_ONLY |
Read-only | ○ | ○ |
Resource::MAP_WRITE_ONLY |
Write-only | ○ | Error |
Resource::MAP_READ_WRITE |
Read/write | ○ | Error |
The mapping method is only checked when you get a data pointer. Although writing to the resource data in device memory obtained by MAP_READ_ONLY
does not result in an error, the cache is not flushed when the mapping is removed.
You cannot directly access resource data in VRAM. Use a method such as DMA transfer to copy the data to memory that can be directly accessed by the CPU.
After you have finished accessing the resource data, remove the mapping using the nn::gd::Resource::UnmapVertexBufferResource()
function. If you get a data pointer to resource data in device memory using a mapping method that includes writes, the cache is flushed when the mapping is removed.
3.2.5. Partially Copying Resource Data (VertexBufferResource Objects)
You can create a partial copy of resource data. Data is actually copied when the command list is executed because this function calls the nngxAddBlockImageCopyCommand()
function.
static nnResult nn::gd::Memory::CopyVertexBufferSubResource( const nn::gd::VertexBufferResource* source, u32 sourceOffset, u32 size, const nn::gd::VertexBufferResource* dest, u32 destOffset);
Data is not copied if the arguments passed to the sourceOffset
, size
, and destOffset
parameters are not all multiples of 16.