<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.11.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/MTLBlitCommandEncoder",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "Metal"
    ],
    "preciseIdentifier" : "c:objc(pl)MTLBlitCommandEncoder"
  },
  "title" : "MTLBlitCommandEncoder"
}
-->

# MTLBlitCommandEncoder

Encodes commands that copy and modify resources for a single blit pass.

```
protocol MTLBlitCommandEncoder : MTLCommandEncoder
```

## Overview

Create a blit encoder by calling one of the factory methods on an [`MTLCommandBuffer`](/documentation/Metal/MTLCommandBuffer) instance,
such as [`makeBlitCommandEncoder()`](/documentation/Metal/MTLCommandBuffer/makeBlitCommandEncoder()).

A blit command encoder adds commands to a command buffer that modify resources in various ways, including:

- Filling buffers with repeating bytes
- Generating mipmaps for textures
- Copying data between buffers
- Copying data between textures
- Copying data between a texture and a buffer
- Managing the contents of indirect command buffers
- Synchronizing buffers, textures, and other resources between the CPU and GPU
- Improving runtime performance for resources by optimizing their memory layout for the GPU or CPU

You typically use these commands to move data between a resource that uses private storage and another resource that uses CPU-accessible storage.
Some apps also use them to apply image-processing and texture effects, such as blurring or reflections, or to render and work with offscreen image data.

When you finish encoding blit commands, finalize the blit pass into the command buffer
by calling the encoder’s [`endEncoding()`](/documentation/Metal/MTLCommandEncoder/endEncoding()) method.

### Command stages

Most blit commands apply to one stage within a pass.
The following table shows which stages apply to each command:

|Function                                                                                                                                                                                                    |MTLStages                                                   |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/fill(buffer:range:value:)``                                                                                                               |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/generateMipmaps(for:)``                                                                                                                   |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:to:destinationOffset:size:)``                                                                                      |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:to:)``                                                                                                                          |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:to:destinationSlice:destinationLevel:sliceCount:levelCount:)``                                          |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)``                      |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOrigin:sourceDimensions:to:destinationOrigin:destinationDimensions:)``                                                    |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)``        |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:options:)``|``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:)``        |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)``|``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForGPUAccess(texture:)``                                                                                                  |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForGPUAccess(texture:slice:level:)``                                                                                      |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForCPUAccess(texture:)``                                                                                                  |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForCPUAccess(texture:slice:level:)``                                                                                      |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/synchronize(resource:)``                                                                                                                  |None                                                        |
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/synchronize(texture:slice:level:)``                                                                                                       |None                                                        |
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/copyIndirectCommandBuffer(_:sourceRange:destination:destinationIndex:)``                                                                  |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/resetCommandsInBuffer(_:range:)``                                                                                                         |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/optimizeIndirectCommandBuffer(_:range:)``                                                                                                 |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/sampleCounters(sampleBuffer:sampleIndex:barrier:)``                                                                                       |None                                                        |
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/resolveCounters(_:range:destinationBuffer:destinationOffset:)``                                                                           |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/getTextureAccessCounters(_:region:mipLevel:slice:resetCounters:countersBuffer:countersBufferOffset:)``                                    |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|
|``doc://com.apple.metal/documentation/Metal/MTLBlitCommandEncoder/resetTextureAccessCounters(_:region:mipLevel:slice:)``                                                                                    |``doc://com.apple.metal/documentation/Metal/MTLStages/blit``|

For more information about stages and synchronization, see [`MTLStages`](/documentation/Metal/MTLStages) and [Resource synchronization](/documentation/Metal/resource-synchronization).

## Topics

### Filling buffers

Write repeating byte values to buffer memory.

[`fill(buffer:range:value:)`](/documentation/Metal/MTLBlitCommandEncoder/fill(buffer:range:value:))

Encodes a command that fills a buffer with a constant value for each byte.

[`fillBuffer:range:value:`](/documentation/Metal/MTLBlitCommandEncoder/fillBuffer:range:value:)

Encodes a command that fills a buffer with a constant value for each byte.

### Generating texture mipmaps

Create mipmap levels from a texture’s base layer.

[`generateMipmaps(for:)`](/documentation/Metal/MTLBlitCommandEncoder/generateMipmaps(for:))

Encodes a command that generates mipmaps for a texture from the base mipmap level up to the highest mipmap level.

### Copying buffer data to another buffer

Transfer data between Metal buffers.

[`copy(from:sourceOffset:to:destinationOffset:size:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:to:destinationOffset:size:))

Encodes a command that copies data from one buffer into another.

### Copying texture data to another texture

Transfer data between Metal textures.

[`copy(from:to:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:to:))

Encodes a command that copies data from one texture to another.

[`copy(from:sourceSlice:sourceLevel:to:destinationSlice:destinationLevel:sliceCount:levelCount:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:to:destinationSlice:destinationLevel:sliceCount:levelCount:))

Encodes a command that copies slices of a texture to another texture’s slices.

[`copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:))

Encodes a command that copies image data from a texture’s slice into another slice.

[`copy(from:sourceOrigin:sourceDimensions:to:destinationOrigin:destinationDimensions:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOrigin:sourceDimensions:to:destinationOrigin:destinationDimensions:))

Encodes a command to copy data from a slice of the data plane of a tensor into a slice of the data plane of
another tensor.

### Copying buffer data to a texture

Transfer data from a Metal buffer to a Metal texture.

[`copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:))

Encodes a command to copy image data from a source buffer into a destination texture.

[`copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:options:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:to:destinationSlice:destinationLevel:destinationOrigin:options:))

Encodes a command to copy image data from a source buffer into a destination texture.

### Copying texture data to a buffer

Transfer data from a Metal texture to a Metal buffer.

[`copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:))

Encodes a command that copies image data from a texture slice to a buffer.

[`copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:)`](/documentation/Metal/MTLBlitCommandEncoder/copy(from:sourceSlice:sourceLevel:sourceOrigin:sourceSize:to:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:))

Encodes a command that copies image data from a texture slice to a buffer, and provides options for special texture formats.

### Optimizing textures for GPU access

Improve GPU access times by altering a texture’s memory layout.

[`optimizeContentsForGPUAccess(texture:)`](/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForGPUAccess(texture:))

Encodes a command that improves the performance of GPU memory operations with a texture.

[`optimizeContentsForGPUAccess(texture:slice:level:)`](/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForGPUAccess(texture:slice:level:))

Encodes a command that improves the performance of GPU memory operations with a specific portion of a texture.

### Optimizing textures for CPU access

Improve CPU access times by altering a texture’s memory layout.

[`optimizeContentsForCPUAccess(texture:)`](/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForCPUAccess(texture:))

Encodes a command that improves the performance of CPU memory operations with a texture.

[`optimizeContentsForCPUAccess(texture:slice:level:)`](/documentation/Metal/MTLBlitCommandEncoder/optimizeContentsForCPUAccess(texture:slice:level:))

Encodes a command that improves the performance of CPU memory operations with a specific portion of a texture.

### Synchronizing managed resources

Update the CPU’s copy of a managed resource to match the GPU’s copy.

[`synchronize(resource:)`](/documentation/Metal/MTLBlitCommandEncoder/synchronize(resource:))

Encodes a command that synchronizes the CPU’s copy of a managed resource, such as a buffer or texture, so that it matches the GPU’s copy.

[`synchronize(texture:slice:level:)`](/documentation/Metal/MTLBlitCommandEncoder/synchronize(texture:slice:level:))

Encodes a command that synchronizes a part of the CPU’s copy of a texture so that it matches the GPU’s copy.

### Preventing resource access conflicts

Address hazards for untracked resources with fences.

[`waitForFence(_:)`](/documentation/Metal/MTLBlitCommandEncoder/waitForFence(_:))

Encodes a command that instructs the GPU to pause the blit pass until another pass updates a fence.

[`updateFence(_:)`](/documentation/Metal/MTLBlitCommandEncoder/updateFence(_:))

Encodes a command that instructs the GPU to update a fence after the blit pass completes.

### Managing indirect command buffers

Modify commands within an indirect command buffer.

[`copyIndirectCommandBuffer(_:sourceRange:destination:destinationIndex:)`](/documentation/Metal/MTLBlitCommandEncoder/copyIndirectCommandBuffer(_:sourceRange:destination:destinationIndex:))

Encodes a command that copies commands from one indirect command buffer into another.

[`resetCommandsInBuffer(_:range:)`](/documentation/Metal/MTLBlitCommandEncoder/resetCommandsInBuffer(_:range:))

Encodes a command that resets a range of commands in an indirect command buffer.

[`optimizeIndirectCommandBuffer(_:range:)`](/documentation/Metal/MTLBlitCommandEncoder/optimizeIndirectCommandBuffer(_:range:))

Encodes a command that can improve the performance of a range of commands within an indirect command buffer.

[`copyIndirectCommandBuffer:sourceRange:destination:destinationIndex:`](/documentation/Metal/MTLBlitCommandEncoder/copyIndirectCommandBuffer:sourceRange:destination:destinationIndex:)

Encodes a command that copies commands from one indirect command buffer into another.

[`resetCommandsInBuffer:withRange:`](/documentation/Metal/MTLBlitCommandEncoder/resetCommandsInBuffer:withRange:)

Encodes a command that resets a range of commands in an indirect command buffer.

[`optimizeIndirectCommandBuffer:withRange:`](/documentation/Metal/MTLBlitCommandEncoder/optimizeIndirectCommandBuffer:withRange:)

Encodes a command that can improve the performance of a range of commands within an indirect command buffer.

### Sampling counters

Capture runtime data from GPU hardware counters.

[`sampleCounters(sampleBuffer:sampleIndex:barrier:)`](/documentation/Metal/MTLBlitCommandEncoder/sampleCounters(sampleBuffer:sampleIndex:barrier:))

Encodes a command that samples the GPU’s hardware counters during a blit pass and stores the data in a counter sample buffer.

[`resolveCounters(_:range:destinationBuffer:destinationOffset:)`](/documentation/Metal/MTLBlitCommandEncoder/resolveCounters(_:range:destinationBuffer:destinationOffset:))

Encodes a command that resolves the data from the samples in a sample counter buffer and stores the results into a buffer.

[`resolveCounters:inRange:destinationBuffer:destinationOffset:`](/documentation/Metal/MTLBlitCommandEncoder/resolveCounters:inRange:destinationBuffer:destinationOffset:)

Encodes a command that resolves the data from the samples in a sample counter buffer and stores the results into a buffer.

### Managing sparse texture access counters

Retrieve and reset access counters for sparse textures.

[`getTextureAccessCounters(_:region:mipLevel:slice:resetCounters:countersBuffer:countersBufferOffset:)`](/documentation/Metal/MTLBlitCommandEncoder/getTextureAccessCounters(_:region:mipLevel:slice:resetCounters:countersBuffer:countersBufferOffset:))

Encodes a command that retrieves a sparse texture’s access data for a specific region, mipmap level, and slice.

[`resetTextureAccessCounters(_:region:mipLevel:slice:)`](/documentation/Metal/MTLBlitCommandEncoder/resetTextureAccessCounters(_:region:mipLevel:slice:))

Encodes a command that resets a sparse texture’s access data for a specific region, mipmap level, and slice.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)