kmCreateTextureSurface
Secures a texture surface.
Description:
This function secures a texture surface in texture memory.
This API can allocate texture surfaces in all formats.
Use the kmFreeTexture function to release the area secured by this function.
Whenever possible, KAMUI aligns the texture address with a 2 KB boundary so as to
quicken memory access. Therefore, no texture surface may be created even if the total
of the free frame buffer capacities is larger than the capacity to be allocated to
the texture. In this case, it is necessary to perform garbage collection, using kmGarbageCollectTexture.
KAMUI aligns the first texture surface address and size with a 32-byte boundary.
Caution:
This function must be executed after kmSetSystemConfiguration is called.
Efficient use of texture memory
Secure/release as many texture surfaces as possible at the same time.
Call the creation of a frame buffer area or native data area before the creation
of a texture surface, and avoid releasing and re-creating these until AP ends.
Parameters:
pSurfaceDesc(output)
This parameter is a pointer to the KMSURFACEDESC-type structure.
Surface information is returned to the structure using the pointer.
It becomes undefined if KMSTATUS is responded with KMSTATUS_NOT_ENOUGH_MEMORY.
nWidth, nHeight(input)
These parameters specify the horizontal and vertical texture sizes.
If MIPMAP is used, the top-level texture size must be specified.
The value specified for nWidth or nHeight must be 8, 16, 32, 64, 128, 256, 512, or 1,024.
nTextureType(input)
This parameter specifies a texture format.
The texture format is specified by ORing a category code and pixel format code selected from those listed below.
Category codes | Meaning |
---|---|
KM_TEXTURE_TWIDDLED | Twiddled format |
KM_TEXTURE_TWIDDLED_RECTANGLE | Rectangular Twiddled format |
KM_TEXTURE_TWIDDLED_MM | Twiddled format with a mipmap |
KM_TEXTURE_VQ | VQ compression format |
KM_TEXTURE_VQ_MM | VQ compression format with a mipmap |
KM_TEXTURE_SMALLVQ | Small VQ compression format |
KM_TEXTURE_SMALLVQ_MM | Small VQ compression format with a mipmap |
KM_TEXTURE_PALETTIZE4 | 4-bpp palette format |
KM_TEXTURE_PALETTIZE4_MM | 4-bpp palette format with a mipmap |
KM_TEXTURE_PALETTIZE8 | 8-bpp palette format |
KM_TEXTURE_PALETTIZE8_MM | 8-bpp palette format with a mipmap |
KM_TEXTURE_RECTANGLE | Rectangle |
KM_TEXTURE_STRIDE | Rectangle (stride specification) |
Pixel format codes | Meaning |
---|---|
KM_TEXTURE_1555 | ARGB-1555 format |
KM_TEXTURE_565 | RGB-565 format |
KM_TEXTURE_4444 | ARGB-4444 format |
KM_TEXTURE_YUV422 | YUV-422 format |
KM_TEXTURE_BUMP | Bump map |
Return values:
Value | Explanation |
---|---|
KMSTATUS_SUCCESS | Success |
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture type specified |
KMSTATUS_NOT_ENOUGH_MEMORY | Insufficient memory |
kmCreateTextureSurface