Implementing a CVFillExtendedPixelsCallBack

Q: How do I add a CVFillExtendedPixelsCallBack to a CFDictionary of pixel format description keys and implement the callback?

A: A CVFillExtendedPixelsCallBack specifies a custom extended pixel fill callback function optionally used when registering a custom pixel format (see Technical Q&A QA1401, 'Registering custom pixel formats with QuickTime and Core Video'). It is set using the kCVPixelFormatFillExtendedPixelsCallback (type CFData) dictionary key and described with the CVFillExtendedPixelsCallbackData structure.

The CVFillExtendedPixelsCallBack routine should replicate the outer edge of pixels into the extended area.

Note: This callback is optional, if your custom pixel format never needs the functionality of CVPixelBufferFillExtendedPixels, you don\x92t need to add this key or implement the associated callback.

Listing 1 demonstrates how you set this callback function into a CFDictionary describing a pixel format. Listing 2 contains a skeleton implementation of a pixel fill callback and shows how you would call the function in listing 1.

Listing 1: Setting the kCVPixelFormatFillExtendedPixelsCallback key.

OSStatus SetPixelFillCallback(CFMutableDictionaryRef inDictionary, CVFillExtendedPixelsCallBack inCallback)
{
    CVFillExtendedPixelsCallBackData callbackData;
    CFDataRef data;

    if (NULL == inDictionary || NULL == inCallBack) return paramErr;

    callbackData.version = 0;
    callbackData.fillCallBack = inCallback;
    callbackData.refCon = 0;

    data = CFDataCreate(kCFAllocatorDefault, (UInt8 *)&callbackData, sizeof(data));
    if (NULL == data) return coreFoundationUnknownErr;

    CFDictionarySetValue(inDictionary, kCVPixelFormatFillExtendedPixelsCallback, data);

    CFRelease(data);
}

Listing 2: Implementing and setting the CVFillExtendedPixelsCallBack.

/*

Implement a custom extended pixel-fill algorithm appropriate for your custom pixel format.
You will be called whenever Core Video needs to pad a buffer holding your custom pixel format.

This routine should replicate the outer edge of pixels into the extended area. Repeat the first pixel on
each line extendedLeft times to its left, repeat the last pixel on each line extendedRight times to its right,
repeat the first row extendedTop times above and repeat the last row extendedBottom times below.

*/
Boolean MyCVFillExtendedCallback(CVPixelBufferRef pixelBuffer, void *refCon)
{
    size_t extendedLeft, extendedRight, extendedTop, extendedBottom;
    size_t width, height, rowBytes;
    unsigned char *pixels;

    CVPixelBufferGetExtendedPixels(pixelBuffer, &extendedLeft, &extendedRight, &extendedTop, &extendedBottom);
    CVPixelBufferLockBaseAddress(pixelBuffer, 0);

    width = CVPixelBufferGetWidth(pixelBuffer);
    height = CVPixelBufferGetHeight(pixelBuffer);
    rowBytes = CVPixelBufferGetBytesPerRow(pixelBuffer);
    pixels = (unsigned char *)CVPixelBufferGetBaseAddress(pixelBuffer);

    if (0 != extendedLeft) {
        ...
    }

    if (0 != extendedRight) {
        ...
    }

    if (0 != extendedTop) {
        ...
    }

    if (0 != extendedBottom) {
        ...
    }

    CVPixelBufferUnlockBaseAddress(pixelBuffer, 0);

    return TRUE;
}

OSStatus RegisterMyCustomPixelFormatWithCoreVideo(void)
{
    OSStatus status;

    // create a CFDictionary describing my pixel format
    CFDictionaryRef dict = CFDictionaryCreateMutable(kCFAllocatorDefault,
                                              0,
                                              &kCFTypeDictionaryKeyCallBacks,
                                              &kCFTypeDictionaryValueCallBacks);
    if (NULL == dict) return coreFoundationUnknownErr;

    // set my pixel format constant
    status = SetNumberValue(dict, kCVPixelFormatConstant, kMyCustomPixelFormat);
    if (noErr != status)  goto bail;

    // set other pixel format description keys as needed
    ...

    // set the pixel fill callback
    status = SetPixelFillCallback(dict, MyCVFillExtendedCallback);
    if (noErr != status)  goto bail;

    CVPixelFormatDescriptionRegisterDescriptionWithPixelFormatType(dict,
                                                              kMyCustomPixelFormat);
bail:
    CFRelease(dict);

    return status;
}

References

Back to Top 

Document Revision History

DateNotes
2005-09-06editorial
2005-09-01Discusses how you implement a Core Video custom extended pixel fill callback function.

Posted: 2005-09-06

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.