Contents

makeTexture(descriptor:offset:bytesPerRow:)

Creates a texture that shares its storage with the buffer.

Declaration

func makeTexture(descriptor: MTLTextureDescriptor, offset: Int, bytesPerRow: Int) -> (any MTLTexture)?

Parameters

  • descriptor:

    The descriptor that contains the properties of the texture.

  • offset:

    The offset, in bytes, from the base address for the first row of texture data.

  • bytesPerRow:

    The stride, in bytes, from one row of texture data to the next.

Mentioned in

Return Value

A new texture that shares the buffer’s underlying storage.

Discussion

This method creates a new MTLTexture instance that uses the same data as the buffer’s. Modifying the buffer also modifies the new texture because they share the same underlying memory.

The texture’s resource data is coherent between multiple render passes. However, that data may not be coherent within a single render pass due to caching at runtime. For example, a texture you create from the method may not be able to immediately reflect changes to the underlying buffer that come from a render or kernel function.

If this buffer’s storageMode is MTLStorageMode.managed, and a render or kernel function modifies it, the CPU can access the new values through a texture after calling the synchronize(resource:) method. CPU memory operations are only coherent between command buffer boundaries. GPU barriers guard its memory operations to buffers and textures so that each operation finishes running before the next one begins.

You can create multiple, nonoverlapping textures that use the same buffer; however, the GPU serializes memory operations to those textures.

To create a linear texture, you need to:

  • Align the offset and bytesPerRow parameters to the value that the minimumLinearTextureAlignment(for:) method returns.

  • Set the bytesPerRow parameter to a value greater than or equal to the number of bytes in one row of pixels — the product of the row’s width, in pixels, and the size of one pixel, in bytes.

Additionally, creating a linear texture from this method adds the following restrictions for the descriptor parameter’s properties:

Property

Acceptable values for a linear texture

Texturetype

Type2d or Typetexturebuffer

Depth

1

Arraylength

1

Mipmaplevelcount

1

Samplecount

1

Usage

The Rendertarget value if the Mtldevice instance supports Apple1 (see Supportsfamily(_:)), or any other Mtltextureusage value

Storagemode

The same value as this buffer’s Storagemode property (see Resource Fundamentals)

Pixelformat

Any ordinary or packed color Mtlpixelformat, except Gbgr422 and Bgrg422

Samplers can use any MTLSamplerAddressMode to sample linear textures from this method on any device that supports the MTLGPUFamily.apple2 feature family or later.