Instance Method

encodeToCommandBuffer:primaryTexture:inPlaceSecondaryTexture:fallbackCopyAllocator:

This method attempts to apply a kernel in place on a texture.

Declaration

- (BOOL)encodeToCommandBuffer:(id<MTLCommandBuffer>)commandBuffer primaryTexture:(id<MTLTexture>)primaryTexture inPlaceSecondaryTexture:(id<MTLTexture>  _Nonnull *)inPlaceSecondaryTexture fallbackCopyAllocator:(MPSCopyAllocator)copyAllocator;

Parameters

commandBuffer

A valid command buffer to receive the encoded kernel.

primaryTexture

A pointer to a valid texture containing the primary source image. It will not be overwritten.

inPlaceSecondaryTexture

A pointer to a valid texture containing the secondary image. On success, the image contents and possibly the texture itself will be replaced with the result image.

copyAllocator

An optional block to allocate a new texture to hold the operation results, in case in-place operation is not possible. The allocator may use a different pixel format or size than the original texture. You may enqueue operations on the provided command buffer using the provided compute command encoder to initialize the texture contents.

Return Value

  • YES if the operation succeeded (the texture may have been replaced with a new texture if a copy allocator was provided).

  • NO if the operation failed (the texture is unmodified).

Discussion

This method attempts to apply the kernel in place on a texture. In-place operation means that the same texture is used both to hold the input image and the results. Operating in-place can be an excellent way to reduce resource utilization, and save time and energy. While simple Metal kernels can not operate in place because textures can not be readable and writable at the same time, some Metal Performance Shaders kernels can operate in place because they use multi-pass algorithms. Whether a kernel can operate in-place can depend on current hardware, OS version, and the parameters and properties passed to it. You should never assume that a kernel will continue to work in place, even if you have observed it doing so before.

If the in-place operation succeeds, this method returns YES. If the in-place operation fails and no copy allocator is provided, then this method returns NO. Without a fallback copy allocator, in neither case is the pointer held at texture modified.

Failure during in-place operation is common. You may find it simplifies your code to provide a copy allocator. When an in-place operation fails, your copy allocator will be invoked to create a new texture in which to write the results, allowing the kernel to proceed reliably out-of-place. The original texture will be released, replaced with a pointer to the new texture and YES will be returned. If the copy allocator returns an invalid texture, it is released, texture remains unmodified, and NO is returned.

See Also

Methods

- encodeToCommandBuffer:inPlacePrimaryTexture:secondaryTexture:fallbackCopyAllocator:

This method attempts to apply a kernel in place on a texture.

- encodeToCommandBuffer:primaryTexture:secondaryTexture:destinationTexture:

Encodes a kernel into a command buffer, out-of-place.

- primarySourceRegionForDestinationSize:

Determines the region of the primary source texture that will be read for an encode operation.

- secondarySourceRegionForDestinationSize:

Determines the region of the secondary source texture that will be read for an encode operation.