Instance Method

replaceRegion:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:

Copies pixel data into a section of a texture slice.

Required.

Declaration

- (void)replaceRegion:(MTLRegion)region mipmapLevel:(NSUInteger)level slice:(NSUInteger)slice withBytes:(const void *)pixelBytes bytesPerRow:(NSUInteger)bytesPerRow bytesPerImage:(NSUInteger)bytesPerImage;

Parameters

region

The location of a block of pixels in the texture slice. The region must be within the dimensions of the slice.

level

A zero-based value that specifies which mipmap level is the destination. If the texture doesn't have mipmaps, use 0.

slice

A zero-based value that specifies which texture slice is the destination.

For a cube texture, slice is a value between 0 and 5, inclusive, that defines which cube face is the destination.

For a texture array, slice is the index for the array element.

For a cube texture array, slice is a value that defines both a cube face and an array index. The general equation for determining the correct value of slice is:

slice=cubeFace+arrayIndex*6

For example, the third face of a fifth cube is equal to (3-1) + (5-1)*6 = 26.

If the texture type is neither an array nor a cube, use 0.

pixelBytes

A pointer to the bytes in memory to copy.

bytesPerRow

For an ordinary or packed pixel format, the stride, in bytes, between rows of source data. For a compressed pixel format, the stride is the number of bytes from the beginning of one row of blocks to the beginning of the next.

Specify a nonzero value when you copy pixels to texture types other than MTLTextureType1D or MTLTextureType1DArray. Specify a value greater than or equal to the the width of one row (the size of one pixel, in bytes, multiplied by the pixel width of one row) and less than or equal to 32767 multiplied by the size of one pixel. For an ordinary or packed pixel format, use a multiple of the size of one pixel. For a compressed pixel format, use a multiple of the compressed block size. If you specify a nonzero value that is smaller than the width of the texture or is not a multiple of the size of the pixel format or compressed block size, an error occurs.

When you copy pixels to a MTLTextureType1D or MTLTextureType1DArray texture, use 0.

bytesPerImage

The stride, in bytes, between images in the source data. Supply a nonzero value only when you copy data to a MTLTextureType3D type texture. For an ordinary or packed pixel format, bytesPerImage must be a multiple of the size of one pixel. You can't use a compressed pixel format with a MTLTextureType3D texture. If you specify a nonzero value that isn't a multiple of the pixel size or the compressed block size, an error occurs.

If you're copying data to a type of texture other than MTLTextureType3D, use 0.

Discussion

This method immediately copies the pixel data into the texture. It doesn't synchronize against any GPU accesses to the texture. For example, if a command buffer includes read or write operations on a given texture, you must ensure that these operations complete before calling the replaceRegion:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage: method on the given texture. You can use the addCompletedHandler: method, waitUntilCompleted method, or custom semaphores to signal that a command buffer has completed execution.

If the texture image has a compressed pixel format, then only block-aligned regions can be written. If the size of a dimension of region is not a multiple of the block size, then bytesPerRow in system memory must include the full edge block, and the size of that dimension less than or equal to the texture dimensions.

This method is supported if you're copying to an entire texture with a PowerVR Texture Compression (PVRTC) pixel format; in which case, bytesPerRow and bytesPerImage must both be set to 0. This method isn't supported for copying to a subregion of a texture that has a PVRTC pixel format.

For all other pixel formats, compressed or uncompressed, set the bytesPerRow and bytesPerImage properties to 0 if they are not applicable.

Don't use this method for textures with a private storage mode. To copy data to a private texture, copy that data to a texture that has a non-private storage mode, and then use a MTLBlitCommandEncoder to copy the data to the private texture.

See Also

Copying Data into a Texture Image

- replaceRegion:mipmapLevel:withBytes:bytesPerRow:

Copies a block of pixels into a section of texture slice 0.

Required.