kmLoadYUVTexture

Reads the YUV-format texture data.

KMSTATUS KMAPI
kmLoadYUVTexture(
IN PKMSURFACEDESC pSurfaceDesc,
IN PKMDWORD pTexture,
IN KMUINT32 nWidth,
IN KMUINT32 nHeight,
IN KMUINT32 nFormat,
IN KMBOOLEAN bWaitEndOfDMA
)

Description:

This function converts the YUV420-data/YUV422-data in main memory specified by pTexture into Non-Twiddled YUV422 texture and reads it into a texture memory area allocated by kmCreateTextureSurface/kmCreateCombinedTextureSurface/kmCreateContiguousTextureSurface/ kmCreateFixedTextureArea.
In doing so, the YUV-data converter built into tiling accelerator of the CLX1/2 is used. Because the output of the YUV-data converter is Non-Twiddled, the texture surface at the read destination specified by this API must be in either of the following formats:

KM_TEXTURE_RECTANGLE | | | KM_TEXTURE_YUV422 | //Rectangular
KM_TEXTURE_STRIDE | | | KM_TEXTURE_YUV422 | //Rectangular (with stride specification)

If two or more YUV-data are read successively at one time (when addressing mode of nFormat is KM_TEXTURE_YUV_MULTI), the size of each texture must be 16 x 16 texels. Exercise care in specifying the size of texture surface at the read destination specified by this function. In this case, texture surface at read destination must be allocated to contiguous addresses in the frame buffer. Specify the texture surface allocated by kmCreateContiguousTextureSurface function.
To read in one set of YUV-data (when the addressing mode of nFormat is KM_TEXTURE_YUV_SINGLE), nHeight must be 16, 32, 64, 128, 256, 512, or 1024. Also, nWidth must be multiples of 32 and between 32 and 992. However, if the texture surface to read in is KM_TEXTURE_RECTANGLE, nWidth must also be 16, 32, 64, 128, 256, 512, or 1024.
If the CPU directly rewrites texture data into main memory before it is loaded, it is necessary to purge the cache before executing the load function in order to maintain cache coherency. (Specifically, execute the SH4 ocbwb instruction.)

Parameters:

ppSurfaceDesc(input)
Texture surface allocated by kmCreateTextureSurface/kmCreateCombinedTextureSurface/ kmCreateContiguousTextureSurface/kmCreateFixedTextureArea. This parameter is a pointer to KMSURFACEDESC-type structure.
pTexture(input)
This parameter is a pointer indicating YUV420-data/YUV422-data in main memory. Specify an address aligned with a 32-byte boundary. If the address is not on a 32-byte boundary, the YUV converter cannot operate because of hardware constraints. In this case, KMSTATUS_INVALID_ADDRESS is returned.
nWidth, nHeight(input)

When the addressing mode of nFormat is KM_TEXTURE_YUV_MULTI:
  This parameter specifies the amount of texture to read in continuously, in number of micro blocks. The valid value of nWidth and nheight can be from 1 to 64. One micro block equals 16 x 16 texels.
When the addressing mode of nFormat is KM_TEXTURE_YUV_SINGLE:
  This parameter specifies the size of texture to read in texel.
  -If output is in the Rectangle format:
    Both nWidth and nHeight must be 16, 32, 64, 128, 256, 512, or 1024.
  -If output is in the Stride format:
    nHeight must be 16, 32, 64, 128, 256, 512, or 1024. nWidth must be multiples of 32 and between 32 and 992.

nFormat(input)
This parameter specifies the format of the data to read in. One from each of the following categories can be selected and combined logically.
Color mode

Color mode | Description
--- | ---
KM_TEXTURE_YUV420 | Indicates that the input data is YUV420-data.
KM_TEXTURE_YUV422 | Indicates that the input data is YUV422-data.

Addressing Mode

Addressing Mode | Description
--- | ---
KM_TEXTURE_YUV_MULTI | The input data consists of multiple 16x16 YUV-data.
KM_TEXTURE_YUV_SINGLE | The input data consists of one nWidth x nHeight YUV-data.

bWaitEndOfDMA(input)
If TRUE is specified, the function waits until the DMA transfer of data to the YUV converter has been completed. This API does not end until DMA transfer ends.
If FALSE is specified, the function does not wait until DMA transfer ends. To detect the end of DMA transfer, use the kmSetEndOfYUVCallback function.

Return values:

Value | Explanation
--- | ---
KMSTATUS_SUCCESS | Success
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture specified.
KMSTATUS_INVALID_ADDRESS | pTexture not on a 32-byte boundary.

kmLoadYUVTexture