vImageBuffer_InitForCopyToCVPixelBuffer(_:_:_:_:)

Initializes an array of vImage buffers in the order necessary to copy to a Core Video pixel buffer.

Declaration

func vImageBuffer_InitForCopyToCVPixelBuffer(_ buffers: UnsafeMutablePointer<vImage_Buffer>, _ converter: vImageConverter, _ pixelBuffer: CVPixelBuffer, _ flags: vImage_Flags) -> vImage_Error

Parameters

buffers:
An array of Vimage_buffer structures. The number of destination buffers is the return value of Vimageconverter_getnumberofdestinationbuffers(_:).
converter:
A Core-Graphics-to-Core-Video Vimageconverter instance.
pixelBuffer:
A locked Cvpixelbuffer instance.
flags:
The options to use when performing this operation.
important:
Always pass the Kvimagenoallocate flag to this function. The Kvimagenoallocate flag instructs the function to initialize the buffers to read directly from a locked Cvpixelbuffer instance. All operations that use the buffers must be between calls to the Cvpixelbufferlockbaseaddress(_:_:) and Cvpixelbufferunlockbaseaddress(_:_:) functions.

Return Value

kvImageNoError; otherwise, one of the error codes in Data Types and Constants.

Discussion

The vImage library represents multiple plane Core Video pixel buffers as individual vImage buffers. Call vImageConverter_GetNumberOfDestinationBuffers(_:) to instantiate the correct number of destination buffers. Use this function to initialize the vImage buffers that you pass as the destinations to a Core-Video-to-Core-Graphics vImageConverter instance.

The following shows the code for creating the three destination buffers required to represent a kCVPixelFormatType_420YpCbCr8Planar pixel buffer. On return of vImageConvert_AnyToAny(_:_:_:_:_:), the three vImage buffers contain the luminance, Cb, and Cr image data.

let colorSpace = CGColorSpaceCreateDeviceRGB()

guard
    let cgImageFormat = vImage_CGImageFormat(
        bitsPerComponent: 8,
        bitsPerPixel: 32,
        colorSpace: colorSpace,
        bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.noneSkipFirst.rawValue),
        renderingIntent: .defaultIntent),
    
    let cvImageFormat = vImageCVImageFormat.make(
        format: .format420YpCbCr8Planar,
        matrix: kvImage_ARGBToYpCbCrMatrix_ITU_R_709_2.pointee,
        chromaSiting: .center,
        colorSpace: colorSpace,
        alphaIsOpaqueHint: false),
    
    let converterCGtoCV = try? vImageConverter.make(
        sourceFormat: cgImageFormat,
        destinationFormat: cvImageFormat) else {
    return
}

let destinationBufferCount = vImageConverter_GetNumberOfDestinationBuffers(converterCGtoCV)
var destinationBuffers = (0 ..< destinationBufferCount).map { _ in
    return vImage_Buffer()
}

// `cvPixelBuffer` is the destination Core Video pixel buffer.
CVPixelBufferLockBaseAddress(cvPixelBuffer,
                             CVPixelBufferLockFlags(rawValue: 0))

// Initialize the destination buffers.
vImageBuffer_InitForCopyToCVPixelBuffer(
    &destinationBuffers,
    converterCGtoCV,
    cvPixelBuffer,
    vImage_Flags(kvImageNoAllocate))

// The source has an interleaved format with one or more channels, and 
// is encodable with a `vImage_CGImageFormat`.
assert(vImageConverter_GetNumberOfSourceBuffers(converterCGtoCV) == 1)

// On return, `destinationBuffers` contains the YpCbCr conversion of the RGB
// image data in the vImage source buffer.
// `sourceBuffer` is the source vImage buffer.
vImageConvert_AnyToAny(converterCGtoCV,
                       &sourceBuffer,
                       &destinationBuffers,
                       nil,
                       vImage_Flags(kvImageNoFlags))

CVPixelBufferUnlockBaseAddress(cvPixelBuffer,
                               CVPixelBufferLockFlags(rawValue: 0))