vImageBuffer_InitForCopyFromCVPixelBuffer(_:_:_:_:)

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

Declaration

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

Parameters

buffers:
An array of Vimage_buffer structures. The number of source buffers is the return value of Vimageconverter_getnumberofsourcebuffers(_:).
converter:
A Core-Video-to-Core-Graphics 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_GetNumberOfSourceBuffers(_:) to instantiate the correct number of source buffers. Use this function to initialize the vImage buffers that you pass as the sources to a Core-Video-to-Core-Graphics vImageConverter instance.

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

let colorSpace = CGColorSpaceCreateDeviceRGB()

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

let sourceBufferCount = vImageConverter_GetNumberOfSourceBuffers(converterCVtoCG)
var sourceBuffers = (0 ..< sourceBufferCount).map { _ in
    return vImage_Buffer()
}

// `cvPixelBuffer` is the source Core Video pixel buffer.
CVPixelBufferLockBaseAddress(cvPixelBuffer,
                             CVPixelBufferLockFlags.readOnly)

// Initialize the source buffers.
vImageBuffer_InitForCopyFromCVPixelBuffer(
    &sourceBuffers,
    converterCVtoCG,
    cvPixelBuffer,
    vImage_Flags(kvImageNoAllocate ))

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

// Initialize the destination buffer.
var destinationBuffer = vImage_Buffer()
vImageBuffer_Init(&destinationBuffer,
                  sourceBuffers[0].height,
                  sourceBuffers[0].width,
                  cgImageFormat.bitsPerPixel,
                  vImage_Flags(kvImageNoFlags))
defer {
    destinationBuffer.free()
}

// On return, `destinationBuffer` contains the RGB conversion of the image
// data in the Core Video pixel buffer.
vImageConvert_AnyToAny(converterCVtoCG,
                       sourceBuffers,
                       &destinationBuffer,
                       nil,
                       vImage_Flags(kvImageNoFlags))

CVPixelBufferUnlockBaseAddress(cvPixelBuffer,
                               CVPixelBufferLockFlags.readOnly)