--- title: MTLTexture framework: metal role: symbol role_heading: Protocol path: metal/mtltexture --- # MTLTexture A resource that holds formatted image data. ## Declaration ```swift protocol MTLTexture : MTLResource ``` ## Mentioned in Understanding the Metal 4 core API Improving CPU performance by using argument buffers Setting resource storage modes Synchronizing a managed resource in macOS Choosing a resource storage mode for Apple GPUs Creating a mipmapped texture Simplifying GPU resource management with residency sets ## Overview Overview Don’t implement this protocol yourself; instead, use one of the following methods to create an MTLTexture instance: Create an MTLTextureDescriptor instance to describe the texture’s properties and then call the makeTexture(descriptor:) method of the MTLDevice protocol to create the texture. To create a texture that uses an existing IOSurface to hold the texture data, create an MTLTextureDescriptor instance to describe the image data in the surface. Call the makeTexture(descriptor:iosurface:plane:) method to create the texture. To create a texture that reinterprets another texture’s data as if it has a different format, call one of the following texture methods: makeTextureView(pixelFormat:) makeTextureView(pixelFormat:textureType:levels:slices:) (Swift) newTextureViewWithPixelFormat:textureType:levels:slices: (Objective-C) You need to choose a pixel format for the new texture compatible with the source texture’s pixel format. The new texture shares the same storage allocation as the source texture. If you make changes to the new texture, the source texture reflects those changes, and vice versa. To create a texture that uses an MTLBuffer instance’s contents to hold pixel data, create an MTLTextureDescriptor instance to describe the texture’s properties. Then call the makeTexture(descriptor:offset:bytesPerRow:) method on the buffer instance. The new texture instance shares the storage allocation of the source buffer instance. If you make changes to the texture, the buffer reflects those changes, and vice versa. After you create an MTLTexture instance, most of its characteristics, such as its size, type, and pixel format are all immutable. Only the texture’s pixel data is mutable. To copy pixel data from system memory into the texture, call replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:) or replace(region:mipmapLevel:withBytes:bytesPerRow:). To copy pixel data back to system memory, call getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:) or getBytes(_:bytesPerRow:from:mipmapLevel:). ## Topics ### Copying data into a texture image - [replace(region:mipmapLevel:slice:withBytes:bytesPerRow:bytesPerImage:)](metal/mtltexture/replace(region:mipmaplevel:slice:withbytes:bytesperrow:bytesperimage:).md) - [replace(region:mipmapLevel:withBytes:bytesPerRow:)](metal/mtltexture/replace(region:mipmaplevel:withbytes:bytesperrow:).md) ### Copying data from a texture image - [getBytes(_:bytesPerRow:bytesPerImage:from:mipmapLevel:slice:)](metal/mtltexture/getbytes(_:bytesperrow:bytesperimage:from:mipmaplevel:slice:).md) - [getBytes(_:bytesPerRow:from:mipmapLevel:)](metal/mtltexture/getbytes(_:bytesperrow:from:mipmaplevel:).md) ### Creating textures by reinterpreting existing texture data - [makeTextureView(pixelFormat:)](metal/mtltexture/maketextureview(pixelformat:).md) - [makeTextureView(pixelFormat:textureType:levels:slices:)](metal/mtltexture/maketextureview(pixelformat:texturetype:levels:slices:).md) - [makeTextureView(pixelFormat:textureType:levels:slices:swizzle:)](metal/mtltexture/maketextureview(pixelformat:texturetype:levels:slices:swizzle:).md) ### Querying texture attributes - [textureType](metal/mtltexture/texturetype.md) - [pixelFormat](metal/mtltexture/pixelformat.md) - [width](metal/mtltexture/width.md) - [height](metal/mtltexture/height.md) - [depth](metal/mtltexture/depth.md) - [mipmapLevelCount](metal/mtltexture/mipmaplevelcount.md) - [arrayLength](metal/mtltexture/arraylength.md) - [sampleCount](metal/mtltexture/samplecount.md) - [isFramebufferOnly](metal/mtltexture/isframebufferonly.md) - [usage](metal/mtltexture/usage.md) - [allowGPUOptimizedContents](metal/mtltexture/allowgpuoptimizedcontents.md) - [isShareable](metal/mtltexture/isshareable.md) - [swizzle](metal/mtltexture/swizzle.md) - [MTLTextureType](metal/mtltexturetype.md) - [MTLTextureUsage](metal/mtltextureusage.md) ### Getting information about the IOSurface the texture was created from - [iosurface](metal/mtltexture/iosurface.md) - [iosurfacePlane](metal/mtltexture/iosurfaceplane.md) ### Getting information about ancestor resources - [parent](metal/mtltexture/parent.md) - [parentRelativeLevel](metal/mtltexture/parentrelativelevel.md) - [parentRelativeSlice](metal/mtltexture/parentrelativeslice.md) - [buffer](metal/mtltexture/buffer.md) - [bufferOffset](metal/mtltexture/bufferoffset.md) - [bufferBytesPerRow](metal/mtltexture/bufferbytesperrow.md) - [rootResource](metal/mtltexture/rootresource.md) ### Creating a shared texture handle - [makeSharedTextureHandle()](metal/mtltexture/makesharedtexturehandle().md) ### Creating views of textures on other GPUs - [makeRemoteTextureView(_:)](metal/mtltexture/makeremotetextureview(_:).md) - [remoteStorageTexture](metal/mtltexture/remotestoragetexture.md) ### Querying sparse properties - [isSparse](metal/mtltexture/issparse.md) - [firstMipmapInTail](metal/mtltexture/firstmipmapintail.md) - [tailSizeInBytes](metal/mtltexture/tailsizeinbytes.md) ### Instance Properties - [compressionType](metal/mtltexture/compressiontype.md) - [gpuResourceID](metal/mtltexture/gpuresourceid.md) - [sparseTextureTier](metal/mtltexture/sparsetexturetier.md) ### Instance Methods - [newTextureView(with:)](metal/mtltexture/newtextureview(with:).md) ## Relationships ### Inherits From - [MTLAllocation](metal/mtlallocation.md) - [MTLResource](metal/mtlresource.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) ## See Also ### Texture basics - [Understanding color-renderable pixel format sizes](metal/understanding-color-renderable-pixel-format-sizes.md) - [Optimizing texture data](metal/optimizing-texture-data.md) - [MTLTextureCompressionType](metal/mtltexturecompressiontype.md) - [MTLTextureDescriptor](metal/mtltexturedescriptor.md) - [MTKTextureLoader](metalkit/mtktextureloader.md) - [MTLSharedTextureHandle](metal/mtlsharedtexturehandle.md) - [MTLPixelFormat](metal/mtlpixelformat.md)