Inside Macintosh: /

QuickDraw 3D RAVE / QuickDraw 3D RAVE Reference

QuickDraw 3D RAVE Routines / Manipulating Textures and Bitmaps

QATextureNew

You can use the QATextureNew function to create a new texture map.

TQAError QATextureNew (
                       const TQAEngine *engine, 
                       unsigned long flags, 
                       TQAImagePixelType pixelType, 
                       const TQAImage images[], 
                       TQATexture **newTexture);

engine

A drawing engine.

flags

A set of bit flags specifying features of the new texture map. See "Texture Flags Masks" (page 1-64) for complete information.

pixelType

The type of pixels in the new texture map. See "Pixel Types" (page 1-35) for a description of the values you can pass in this parameter.

images

An array of pixel images to use for the new texture map. The values in the width and height fields of these structures must be an even power of 2.

newTexture

On entry, the address of a pointer variable. On exit, that variable points to a new texture map. If a new texture map cannot be created, *newTexture is set to the value NULL.

DESCRIPTION

The QATextureNew function returns, through the newTexture parameter, a new texture map associated with the drawing engine specified by the engine parameter. You can use the returned texture map to set the value of the kQATag_Texture state variable.

The flags parameter specifies a set of texture map features. If the kQATexture_Lock bit in that parameter is set but the drawing engine cannot guarantee that the texture will remain locked in memory, the QATextureNew function returns an error.

If the kQATexture_Mipmap bit of the flags parameter is clear, the images parameter points to a single pixel image that defines the texture map. If the kQATexture_Mipmap bit is set, the images parameter points to an array of pixel images of varying pixel depths. The first element in the array must be the mipmap page having the highest resolution, with a width and height that are even powers of 2. Each subsequent pixel image in the array should have a width and height that are half those of the previous image (with a minimum width and height of 1).

SPECIAL CONSIDERATIONS

QATextureNew does not automatically copy the pixmap data pointed to by the images parameter. As a result, you should not release or reuse the storage occupied by the pixel images until you've called QATextureDetach. Note, however, that QATextureNew does copy all of the information contained in the TQAImage structures in the array, so you can free or reuse that memory after QATextureNew completes successfully.