nngxAddB2LTransferCommand Function

NNGX_APICALL void NNGX_APIENTRY nngxAddB2LTransferCommand(
     const GLvoid * srcaddr,
     GLsizei srcwidth,
     GLsizei srcheight,
     GLenum srcformat,
     GLvoid * dstaddr,
     GLsizei dstwidth,
     GLsizei dstheight,
     GLenum dstformat,
     GLenum aamode,
     GLboolean yflip,
     GLsizei blocksize
);

	Name	Description
in	srcaddr	Transfer source block image address.
in	srcwidth	Transfer source image width.
in	srcheight	Transfer source image height.
in	srcformat	Transfer source image pixel format.
out	dstaddr	Transfer destination linear image storage address.
in	dstwidth	Transfer destination image width.
in	dstheight	Transfer destination image height.
in	dstformat	Transfer destination image pixel format.
in	aamode	Antialias filter mode.
in	yflip	Whether to flip vertically when transferring images.
in	blocksize	Block image block size (8 or 32).

There is no return value.

Adds a command request to convert from a block image to a linear image and then to transfer it.

This function converts a block image to a linear image. (In other words, it converts from the format used for rendering to the format used for display.) Although the nngxTransferRenderImage function provides equivalent functionality, this function has more general uses. Also, unlike nngxTransferRenderImage, this function only adds a transfer request command without adding a 3D split command.

Specify the start address of the transfer source block image using the srcaddr parameter. Specify the start address of the transfer destination linear image using the dstaddr parameter. Both srcaddr and dstaddr must be 16-byte aligned.

Specify the original image's width and height in pixels using srcwidth and srcheight. Specify the transferred image's width and height in pixels using dstwidth and dstheight. These dimensions must all be multiples of the block size. The block size is either 8 or 32. However, if the transferred image uses 24 bits per pixel and a block size of 8, both the original and transferred images must have widths that are multiples of 16. This function neither converts nor transfers if any of the image dimensions is 0. The width and height of the transferred image must be less than or equal to the width and height of the original image.

Specify the pixel format of the original and transferred images using srcformat and dstformat. Specify the pixel format with one of the following macros.

GL_RGBA8_OES	32-bit RGBA8
GL_RGB8_OES	24-bit RGB8
GL_RGBA4	16-bit RGBA4
GL_RGB5_A1	16-bit RGBA5551
GL_RGB565	16-bit RGB565

Conversions that increase the pixel size are not possible. For example, you cannot convert from a 24-bit format to a 32-bit format or from a 16-bit format to either a 24- or 32-bit format.

Specify the antialiasing filter mode with aamode. Specify the mode with one of the following macros.

NN_GX_ANTIALIASE_NOT_USED	No antialiasing
NN_GX_ANTIALIASE_2x1	Transfer with 2x1 antialiasing
NN_GX_ANTIALIASE_2x2	Transfer with 2x2 antialiasing

When antialiasing is enabled, the transferred image is shrunk in half in the filtering direction. Specifically, 2x2 antialiasing shrinks the image in half vertically and horizontally, and 2x1 antialiasing shrinks the image in half horizontally.

The transferred image is flipped vertically when yflip is GL_TRUE. It is not flipped when yflip is GL_FALSE. Nonzero values are considered to be GL_TRUE.

For blocksize, specify 8 or 32. When set to 8, the transfer source image is transferred using a block size of 8. When set to 32, the transfer source image is transferred using a block size of 32.

srcaddr and dstaddr must be stored in device memory or in VRAM. If they are not stored in these regions, the Development/Debug builds will stop on an assertion and the Release build will quit without the addition of a transfer command.
If the data of either srcaddr or dstaddr is stored in device memory and will be directly referenced and edited by the CPU, then you will need to use the nngxUpdateBuffer function to flush the cache before executing the transfer command.

The following errors occur with this function.

GL_ERROR_807C_DMP	0 is bound to the current command list or the command request queue is full.
GL_ERROR_807D_DMP	srcaddr or dstaddr is not 16-byte aligned.
GL_ERROR_807E_DMP	blocksize is neither 8 nor 32.
GL_ERROR_807F_DMP	aamode is an invalid value.
GL_ERROR_8080_DMP	srcformat and dstformat are invalid values.
GL_ERROR_8081_DMP	dstformat has a larger pixel size than srcformat.
GL_ERROR_8082_DMP	srcwidth, srcheight, dstwidth, or dstheight is an invalid value.
GL_ERROR_8083_DMP	The width or height of the transferred image is larger than the original image.

nngxAddL2BTransferCommand

2011/10/04

Added See Also section.

2011/06/21

Added mention of a restriction on srcaddr and the use of the nngxUpdateBuffer function to flush the cache.

2011/05/26

Made minor revision to the description of the difference with the nngxTransferRenderImage function (the presence/absence of split commands).

2010/09/15

Initial version.