Instance Method

newTextureViewWithPixelFormat:textureType:levels:slices:

Creates a new texture object that shares the texture's storage allocation, reinterpreting the texture image data using a different pixel format.

Required.

Declaration

- (id<MTLTexture>)newTextureViewWithPixelFormat:(MTLPixelFormat)pixelFormat textureType:(MTLTextureType)textureType levels:(NSRange)levelRange slices:(NSRange)sliceRange;

Parameters

pixelFormat

A new pixel format, which must be compatible with the original pixel format.

textureType

A new texture type, which can be cast according to the original texture type as listed in Table 1.

levelRange

A new base level range that restricts which mipmap levels are visible in the new texture.

sliceRange

A new base slice range that restricts which array slices are visible in the new texture.

Return Value

A new texture object that shares the same storage allocation of the calling texture object.

Discussion

Not all pixel formats are compatible with one another; for example, you can't use this method between color pixel formats of different sizes. Reinterpretation of image data between pixel formats is supported within the following groups:

This method doesn't change the original texture image data in any way, but it may drastically change how the data is interpreted. For example, given a texture with the MTLPixelFormatRG16Uint pixel format that contains image data for Red 0xFFFE and Green 0x0001, this method would reinterpret that data in an MTLPixelFormatR32Uint format as Red 0x0001FFFE.

Some format reinterpretations are supported but may not be useful. For example, this method considers the 32-bit packed color formats MTLPixelFormatA2BGR10Uint and MTLPixelFormatB10GR11Float to be compatible, but it's unlikely that the same data can be interpreted by both formats in a meaningful way.

The texture type can be cast between the targets listed in Table 1.

Table 1

Texture type compatibility

Original texture type

New texture type

MTLTextureType1D

MTLTextureType1D

MTLTextureType2D

MTLTextureType2D or MTLTextureType2DArray

MTLTextureType2DArray, MTLTextureTypeCube, or MTLTextureTypeCubeArray

MTLTextureType2D, MTLTextureType2DArray, MTLTextureTypeCube, or MTLTextureTypeCubeArray

MTLTextureType3D

MTLTextureType3D

The length value of the sliceRange parameter must be 6 if the new texture type value is MTLTextureTypeCube, or a multiple of 6 if the new texture type value is MTLTextureTypeCubeArray.

See Also

Creating Textures by Reusing Image Data

- newTextureViewWithPixelFormat:

Creates a new texture object that shares the texture's storage allocation, reinterpreting the data using a different pixel format.

Required.

- newTextureViewWithPixelFormat:textureType:levels:slices:swizzle:

Creates a new texture object that shares the texture's storage allocation, reinterpreting the texture image data with a different pixel format and sampling pattern.

Required.