Instance Method


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


func encode(commandBuffer: MTLCommandBuffer, primaryTexture: MTLTexture, inPlaceSecondaryTexture: UnsafeMutablePointer<MTLTexture>, fallbackCopyAllocator copyAllocator: MPSCopyAllocator? = nil) -> Bool



A valid command buffer to receive the encoded kernel.


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


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.


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

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

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


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 true. If the in-place operation fails and no copy allocator is provided, then this method returns false. 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 true will be returned. If the copy allocator returns an invalid texture, it is released, texture remains unmodified, and false is returned.

See Also