kmCreateTextureSurface

Secures a texture surface.

KMSTATUS KMAPI
kmCreateTextureSurface(
OUT PKMSURFACEDESC pSurfaceDesc,
IN KMINT32 nWidth,
IN KMINT32 nHeight,
IN KMTEXTURETYPE nTextureType
)

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

Note: With the palette format texture (KM_TEXTURE_PALETTIZED4, KM_TEXTURE_PALETTIZED4_MM, KM_TEXTURE_PALETTIZED8, KM_TEXTURE_PALETTIZED8_MM), the pixel format cannot be specified. Specify the pixel format of the palette format texture by setting a palette (kmSetPaletteMode).

Return values:

Value | Explanation
--- | ---
KMSTATUS_SUCCESS | Success
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture type specified
KMSTATUS_NOT_ENOUGH_MEMORY | Insufficient memory

kmCreateTextureSurface