CVMetalTextureCacheCreateTextureFromImage use count note and how to handle it

The documentation CVMetalTextureCacheCreateTextureFromImage has the following "Important" note:

This function increments the use count of the image buffer, but not the IOSurface buffer. The Core Video Metal texture owns this IOSurface buffer. Therefore, you must maintain a strong reference to either the image buffer or the Metal texture until the Metal rendering completes. Consider using the MTLCommandBufferHandler for this purpose.

However, when using CFGetRetainCount on the CVPixelBufferRef the count remains the same.

Furthermore, the MTLTexture aquired from the returned CVMetalTextureRef has a strong reference to the IOSurfaceRef, so unless when using commandBufferWithUnretainedReferences there should be no risk that the backing storage will be discarded before the command buffer completes.

So what does this note mean? Am I responsible for decrementing the use count of the passed CVPixelBufferRef? Do I even need to do something with the underlying IOSurfaceRef?

CV* API's are part of CoreVideo, so you'll likely want to tag this question with CoreVideo to get the full scoop.

The use count refers to the IOSurface's usage by an API. This differs from its retain count. If the use count is non-zero the IOSurface will not be recycled by a CVPixelBufferPool that created it. This prevents race conditions where one API writes to the surface while another simultaneously reads from it.  If there is a CVMetalTextureRef, CVImageBufferRef, CVPixelBufferRef the underlying IOSurface's use count will be non-zero. 

The note is trying to say that the surface should stay inUse until the command buffer is done with it.   To do this, you need to retain the CVMetalTextureRef until the kernel schedules any command buffer using and fires its schedule handler.

CVMetalTextureCacheCreateTextureFromImage use count note and how to handle it
 
 
Q