apple.metal.protocol

Interface MTLBlitCommandEncoder

All Superinterfaces:

MTLCommandEncoder

public interface MTLBlitCommandEncoder
extends MTLCommandEncoder

[@protocol] MTLBlitCommandEncoder

A command encoder that performs basic copies and blits between buffers and textures.

Method Summary

Modifier and Type	Method and Description
void	copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin(MTLBuffer sourceBuffer, long sourceOffset, long sourceBytesPerRow, long sourceBytesPerImage, MTLSize sourceSize, MTLTexture destinationTexture, long destinationSlice, long destinationLevel, MTLOrigin destinationOrigin) copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:
void	copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOriginOptions(MTLBuffer sourceBuffer, long sourceOffset, long sourceBytesPerRow, long sourceBytesPerImage, MTLSize sourceSize, MTLTexture destinationTexture, long destinationSlice, long destinationLevel, MTLOrigin destinationOrigin, long options) copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:options:
void	copyFromBufferSourceOffsetToBufferDestinationOffsetSize(MTLBuffer sourceBuffer, long sourceOffset, MTLBuffer destinationBuffer, long destinationOffset, long size) copyFromBuffer:sourceOffset:toBuffer:destinationOffset:size:
void	copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImage(MTLTexture sourceTexture, long sourceSlice, long sourceLevel, MTLOrigin sourceOrigin, MTLSize sourceSize, MTLBuffer destinationBuffer, long destinationOffset, long destinationBytesPerRow, long destinationBytesPerImage) copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:
void	copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImageOptions(MTLTexture sourceTexture, long sourceSlice, long sourceLevel, MTLOrigin sourceOrigin, MTLSize sourceSize, MTLBuffer destinationBuffer, long destinationOffset, long destinationBytesPerRow, long destinationBytesPerImage, long options) copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:sourceOptions:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:
void	copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin(MTLTexture sourceTexture, long sourceSlice, long sourceLevel, MTLOrigin sourceOrigin, MTLSize sourceSize, MTLTexture destinationTexture, long destinationSlice, long destinationLevel, MTLOrigin destinationOrigin) copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:
void	copyFromTextureSourceSliceSourceLevelToTextureDestinationSliceDestinationLevelSliceCountLevelCount(MTLTexture sourceTexture, long sourceSlice, long sourceLevel, MTLTexture destinationTexture, long destinationSlice, long destinationLevel, long sliceCount, long levelCount) copyFromTexture:sourceSlice:sourceLevel:toTexture:destinationSlice:destinationLevel:sliceCount:levelCount:
void	copyFromTextureToTexture(MTLTexture sourceTexture, MTLTexture destinationTexture) copyFromTexture:toTexture:
void	copyIndirectCommandBufferSourceRangeDestinationDestinationIndex(MTLIndirectCommandBuffer source, NSRange sourceRange, MTLIndirectCommandBuffer destination, long destinationIndex) copyIndirectCommandBuffer:source:sourceRange:destination:destinationIndex
void	fillBufferRangeValue(MTLBuffer buffer, NSRange range, byte value) fillBuffer:range:value:
void	generateMipmapsForTexture(MTLTexture texture) generateMipmapsForTexture:
void	getTextureAccessCountersRegionMipLevelSliceResetCountersCountersBufferCountersBufferOffset(MTLTexture texture, MTLRegion region, long mipLevel, long slice, boolean resetCounters, MTLBuffer countersBuffer, long countersBufferOffset) getTextureAccessCounters:region:mipLevel:slice:type:resetCounters:countersBuffer:countersBufferOffset
void	optimizeContentsForCPUAccess(MTLTexture texture) optimizeContentsForCPUAccess:
void	optimizeContentsForCPUAccessSliceLevel(MTLTexture texture, long slice, long level) optimizeContentsForCPUAccess:slice:level:
void	optimizeContentsForGPUAccess(MTLTexture texture) optimizeContentsForGPUAccess:
void	optimizeContentsForGPUAccessSliceLevel(MTLTexture texture, long slice, long level) optimizeContentsForGPUAccess:slice:level:
void	optimizeIndirectCommandBufferWithRange(MTLIndirectCommandBuffer indirectCommandBuffer, NSRange range) optimizeIndirectCommandBuffer:withRange:
void	resetCommandsInBufferWithRange(MTLIndirectCommandBuffer buffer, NSRange range) resetCommandsInBuffer:withRange:
void	resetTextureAccessCountersRegionMipLevelSlice(MTLTexture texture, MTLRegion region, long mipLevel, long slice) resetTextureAccessCounters:region:mipLevel:slice:type:
void	resolveCountersInRangeDestinationBufferDestinationOffset(MTLCounterSampleBuffer sampleBuffer, NSRange range, MTLBuffer destinationBuffer, long destinationOffset) resolveCounters:inRange:destinationBuffer:destinationOffset:
void	sampleCountersInBufferAtSampleIndexWithBarrier(MTLCounterSampleBuffer sampleBuffer, long sampleIndex, boolean barrier) sampleCountersInBuffer:atSampleIndex:withBarrier:
void	updateFence(MTLFence fence) updateFence:
void	waitForFence(MTLFence fence) waitForFence:

Methods inherited from interface apple.metal.protocol.MTLCommandEncoder

device, endEncoding, insertDebugSignpost, label, popDebugGroup, pushDebugGroup, setLabel

Method Detail

copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin

void copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin(MTLBuffer sourceBuffer,
                                                                                                                                        long sourceOffset,
                                                                                                                                        long sourceBytesPerRow,
                                                                                                                                        long sourceBytesPerImage,
                                                                                                                                        MTLSize sourceSize,
                                                                                                                                        MTLTexture destinationTexture,
                                                                                                                                        long destinationSlice,
                                                                                                                                        long destinationLevel,
                                                                                                                                        MTLOrigin destinationOrigin)

copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:

Copy an image from a buffer into a texture.

copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOriginOptions

void copyFromBufferSourceOffsetSourceBytesPerRowSourceBytesPerImageSourceSizeToTextureDestinationSliceDestinationLevelDestinationOriginOptions(MTLBuffer sourceBuffer,
                                                                                                                                               long sourceOffset,
                                                                                                                                               long sourceBytesPerRow,
                                                                                                                                               long sourceBytesPerImage,
                                                                                                                                               MTLSize sourceSize,
                                                                                                                                               MTLTexture destinationTexture,
                                                                                                                                               long destinationSlice,
                                                                                                                                               long destinationLevel,
                                                                                                                                               MTLOrigin destinationOrigin,
                                                                                                                                               long options)

copyFromBuffer:sourceOffset:sourceBytesPerRow:sourceBytesPerImage:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:options:

Copy an image from a buffer into a texture.

copyFromBufferSourceOffsetToBufferDestinationOffsetSize

void copyFromBufferSourceOffsetToBufferDestinationOffsetSize(MTLBuffer sourceBuffer,
                                                             long sourceOffset,
                                                             MTLBuffer destinationBuffer,
                                                             long destinationOffset,
                                                             long size)

copyFromBuffer:sourceOffset:toBuffer:destinationOffset:size:

Basic memory copy between buffers.

copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImage

void copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImage(MTLTexture sourceTexture,
                                                                                                                                        long sourceSlice,
                                                                                                                                        long sourceLevel,
                                                                                                                                        MTLOrigin sourceOrigin,
                                                                                                                                        MTLSize sourceSize,
                                                                                                                                        MTLBuffer destinationBuffer,
                                                                                                                                        long destinationOffset,
                                                                                                                                        long destinationBytesPerRow,
                                                                                                                                        long destinationBytesPerImage)

copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:

Copy an image from a texture into a buffer.

copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImageOptions

void copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToBufferDestinationOffsetDestinationBytesPerRowDestinationBytesPerImageOptions(MTLTexture sourceTexture,
                                                                                                                                               long sourceSlice,
                                                                                                                                               long sourceLevel,
                                                                                                                                               MTLOrigin sourceOrigin,
                                                                                                                                               MTLSize sourceSize,
                                                                                                                                               MTLBuffer destinationBuffer,
                                                                                                                                               long destinationOffset,
                                                                                                                                               long destinationBytesPerRow,
                                                                                                                                               long destinationBytesPerImage,
                                                                                                                                               long options)

copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:sourceOptions:toBuffer:destinationOffset:destinationBytesPerRow:destinationBytesPerImage:options:

Copy an image from a texture into a buffer.

copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin

void copyFromTextureSourceSliceSourceLevelSourceOriginSourceSizeToTextureDestinationSliceDestinationLevelDestinationOrigin(MTLTexture sourceTexture,
                                                                                                                           long sourceSlice,
                                                                                                                           long sourceLevel,
                                                                                                                           MTLOrigin sourceOrigin,
                                                                                                                           MTLSize sourceSize,
                                                                                                                           MTLTexture destinationTexture,
                                                                                                                           long destinationSlice,
                                                                                                                           long destinationLevel,
                                                                                                                           MTLOrigin destinationOrigin)

copyFromTexture:sourceSlice:sourceLevel:sourceOrigin:sourceSize:toTexture:destinationSlice:destinationLevel:destinationOrigin:

Copy a rectangle of pixels between textures.

fillBufferRangeValue

void fillBufferRangeValue(MTLBuffer buffer,
                          NSRange range,
                          byte value)

fillBuffer:range:value:

Fill a buffer with a fixed value in each byte.

generateMipmapsForTexture

void generateMipmapsForTexture(MTLTexture texture)

generateMipmapsForTexture:

Generate mipmaps for a texture from the base level up to the max level.

updateFence

void updateFence(MTLFence fence)

updateFence:

Update the fence to capture all GPU work so far enqueued by this encoder.

The fence is updated at kernel submission to maintain global order and prevent deadlock. Drivers may delay fence updates until the end of the encoder. Drivers may also wait on fences at the beginning of an encoder. It is therefore illegal to wait on a fence after it has been updated in the same encoder.

waitForFence

void waitForFence(MTLFence fence)

waitForFence:

Prevent further GPU work until the fence is reached.

The fence is evaluated at kernel submision to maintain global order and prevent deadlock. Drivers may delay fence updates until the end of the encoder. Drivers may also wait on fences at the beginning of an encoder. It is therefore illegal to wait on a fence after it has been updated in the same encoder.

copyFromTextureSourceSliceSourceLevelToTextureDestinationSliceDestinationLevelSliceCountLevelCount

void copyFromTextureSourceSliceSourceLevelToTextureDestinationSliceDestinationLevelSliceCountLevelCount(MTLTexture sourceTexture,
                                                                                                        long sourceSlice,
                                                                                                        long sourceLevel,
                                                                                                        MTLTexture destinationTexture,
                                                                                                        long destinationSlice,
                                                                                                        long destinationLevel,
                                                                                                        long sliceCount,
                                                                                                        long levelCount)

copyFromTexture:sourceSlice:sourceLevel:toTexture:destinationSlice:destinationLevel:sliceCount:levelCount:

Copy whole surfaces between textures.

Convenience function to copy sliceCount * levelCount whole surfaces between textures The source and destination pixel format must be identical. The source and destination sample count must be identical. The sourceLevel mip in sourceTexture must have the same dimension as the destinationLevel mip in destinationTexture. The sourceTexture must have at least sourceLevel + levelCount mips The destinationTexture must have at least destinationLevel + levelCount mips The sourceTexture must have at least sourceSlice + sliceCount array slices The destinationTexture must have at least destinationSlice + sliceCount array slices

copyFromTextureToTexture

void copyFromTextureToTexture(MTLTexture sourceTexture,
                              MTLTexture destinationTexture)

copyFromTexture:toTexture:

Copy as many whole surfaces as possible between textures.

Convenience function that calls copyFromTexture:sourceSlice:sourceLevel:toTexture:destinationSlice:destinationLevel:sliceCount:levelCount: The source and destination pixel format must be identical. The source and destination sample count must be identical. Either: - sourceTexture must have a mip M with identical dimensions as the first mip of destinationTexture: sourceLevel = M, destinationLevel = 0 - destinationTexture must have a mip M with identical dimensions as the first mip of sourceTexture: sourceLevel = 0, destinationLevel = M Computes: levelCount = min(sourceTexture.mipmapLevelCount - sourceLevel, destinationTexture.mipmapLevelCount - destinationLevel) sliceCount = min(sourceTexture.arrayLength, destinationTexture.arrayLength) Then invokes the method above using the computed parameters.

copyIndirectCommandBufferSourceRangeDestinationDestinationIndex

void copyIndirectCommandBufferSourceRangeDestinationDestinationIndex(MTLIndirectCommandBuffer source,
                                                                     NSRange sourceRange,
                                                                     MTLIndirectCommandBuffer destination,
                                                                     long destinationIndex)

copyIndirectCommandBuffer:source:sourceRange:destination:destinationIndex

copy a region of a buffer into a destination buffer starting at destinationIndex using the GPU

getTextureAccessCountersRegionMipLevelSliceResetCountersCountersBufferCountersBufferOffset

void getTextureAccessCountersRegionMipLevelSliceResetCountersCountersBufferCountersBufferOffset(MTLTexture texture,
                                                                                                MTLRegion region,
                                                                                                long mipLevel,
                                                                                                long slice,
                                                                                                boolean resetCounters,
                                                                                                MTLBuffer countersBuffer,
                                                                                                long countersBufferOffset)

getTextureAccessCounters:region:mipLevel:slice:type:resetCounters:countersBuffer:countersBufferOffset

Copies tile access counters within specified region into provided buffer

optimizeContentsForCPUAccess

void optimizeContentsForCPUAccess(MTLTexture texture)

optimizeContentsForCPUAccess:

Optimizes the texture data to ensure the best possible performance when accessing content on the CPU at the expense of GPU-access performance.

optimizeContentsForCPUAccessSliceLevel

void optimizeContentsForCPUAccessSliceLevel(MTLTexture texture,
                                            long slice,
                                            long level)

optimizeContentsForCPUAccess:slice:level:

Optimizes a subset of the texture data to ensure the best possible performance when accessing content on the CPU at the expense of GPU-access performance.

optimizeContentsForGPUAccess

void optimizeContentsForGPUAccess(MTLTexture texture)

optimizeContentsForGPUAccess:

Optimizes the texture data to ensure the best possible performance when accessing content on the GPU at the expense of CPU-access performance.

optimizeContentsForGPUAccessSliceLevel

void optimizeContentsForGPUAccessSliceLevel(MTLTexture texture,
                                            long slice,
                                            long level)

optimizeContentsForGPUAccess:slice:level:

Optimizes a subset of the texture data to ensure the best possible performance when accessing content on the GPU at the expense of CPU-access performance.

optimizeIndirectCommandBufferWithRange

void optimizeIndirectCommandBufferWithRange(MTLIndirectCommandBuffer indirectCommandBuffer,
                                            NSRange range)

optimizeIndirectCommandBuffer:withRange:

Optimizes a subset of the texture data to ensure the best possible performance when accessing content on the CPU at the expense of GPU-access performance.

resetCommandsInBufferWithRange

void resetCommandsInBufferWithRange(MTLIndirectCommandBuffer buffer,
                                    NSRange range)

resetCommandsInBuffer:withRange:

reset commands in a indirect command buffer using the GPU

resetTextureAccessCountersRegionMipLevelSlice

void resetTextureAccessCountersRegionMipLevelSlice(MTLTexture texture,
                                                   MTLRegion region,
                                                   long mipLevel,
                                                   long slice)

resetTextureAccessCounters:region:mipLevel:slice:type:

Resets tile access counters within specified region

resolveCountersInRangeDestinationBufferDestinationOffset

void resolveCountersInRangeDestinationBufferDestinationOffset(MTLCounterSampleBuffer sampleBuffer,
                                                              NSRange range,
                                                              MTLBuffer destinationBuffer,
                                                              long destinationOffset)

resolveCounters:inRange:destinationBuffer:destinationOffset:

Resolve the counters from the raw buffer to a processed buffer.

Samples that encountered an error during resolve will be set to MTLCounterErrorValue.

Parameters:

sampleBuffer - The sample buffer to resolve.

range - The range of indices to resolve.

destinationBuffer - The buffer to resolve values into.

destinationOffset - The offset to begin writing values out to. This must be a multiple of the minimum constant buffer alignment.

sampleCountersInBufferAtSampleIndexWithBarrier

void sampleCountersInBufferAtSampleIndexWithBarrier(MTLCounterSampleBuffer sampleBuffer,
                                                    long sampleIndex,
                                                    boolean barrier)

sampleCountersInBuffer:atSampleIndex:withBarrier:

Sample hardware counters at this point in the blit encoder and store the counter sample into the sample buffer at the specified index.

On devices where MTLCounterSamplingPointAtBlitBoundary is unsupported, this method is not available and will generate an error if called.

Parameters:

sampleBuffer - The sample buffer to sample into

sampleIndex - The index into the counter buffer to write the sample.

barrier - Insert a barrier before taking the sample. Passing YES will ensure that all work encoded before this operation in the encoder is complete but does not isolate the work with respect to other encoders. Passing NO will allow the sample to be taken concurrently with other operations in this encoder. In general, passing YES will lead to more repeatable counter results but may negatively impact performance. Passing NO will generally be higher performance but counter results may not be repeatable.