API Notes: Quartz frameworks


An introduction to PyObjC describes the general method for translating Objective-C calls into Python calls, including the handling of pass-by-reference arguments and buffers.

This document describes where the PyObjC bindings for this framework are different from the general rule, such as mentioning APIs that are not supported or where the interface is different than expected.

Quartz vs. CoreGraphics

The PyObjC bindings for the Quartz related frameworks, including CoreGraphics and QuartzComposer are in the Python package “Quartz”. When you use the system version of Python there’s also a package named “CoreGraphics”. This is Apple’s closed-source binding of CoreGraphics, which is not a direct mapping of the Quartz API’s but includes some convenience APIs that are not present in the C API.

The PyObjC bindings for Quartz are not compatible with the CoreGraphics Python package by Apple.


The prefered way to import from packages in these bindings is:

import Quartz

It is also possible to import directly from subwrappers (such as Quartz.CoreGraphics), but it better to import from the toplevel to ensure you’ll get all relevant definitions.

API Notes

API Extensions

See Context Managers for CoreGraphics for some extensions to the API in the CoreGraphics framework.


The userinfo for CGDataConsumerCreate, CGDataProviderCreate, CGDataProviderCreateDirect, CGDataProviderCreateDirectAccess, CGDataProviderCreateSequential, CGDataProviderCreateWithData, CGDisplayRegisterReconfigurationCallback, CGDisplayRemoveReconfigurationCallback, CGFunctionCreate, CGRegisterScreenRefreshCallback, CGReleaseScreenRefreshRects, CGScreenRegisterMoveCallback, CGScreenUnregisterMoveCallback, CGUnregisterScreenRefreshCallback, CGPDFDictionaryApplyFunction, CGPathApply, CGPatternCreate, CGEventTapCreate, CGEventTapCreateForPSN, CGPDFOperatorTableSetCallback and CGPSConverterCreate can be any Python object.

The function arguments for these functions can be any Python callable, including bound methods. Functions mentioned earlier that have a struct with callback functions take in tuple with those callbacks in Python.

CGEventTapCreate and CGEventTapCreateForPSN leak some memory when they are called. This is needed to avoid memory management problems. It is therefore advisable not to call these functions, are at least call them a small number of times.

CGPatternCreate: the callback argument is a single function: the drawPattern callback.

CGDataProviderCreateWithData: the release callback can be None. If it is not None it must be a function with 1 argument: the info object.

CGPDFOperatorTableSetCallback is not supported at the moment.


This function is not supported because the lowlevel “CMProfileRef” type is not wrappped by PyObjC.


This value isn’t actually a constant and can therefore not be wrapped by PyObjC. Use CGMainDisplayID() instead.

CGWindowListCreate, CGWindowListCreateDescriptionFromArray, CGWindowListCreateImageFromArray

This function is documented to return a “CFArray of CGWindowID”. This specific type cannot be represented by PyObjC, therefore the (manually wrapped) function returns a tuple of CGWindowID values instead.

For the same reason CGWindowListCreateDescriptionFromArray, CGWindowListCreateImageFromArray are manually wrapped and take a tuple of WindowID values as an argument.


The easiest way to use this function is to pass None as the buffer argument, that way Quartz will create the buffer for you. If you do want direct access to the buffer you’ll have to create a writable buffer, for example like so:

bytes = array.array('B', (0 for i in xrange(100*80*4)))
ctx = CGBitmapContextCreate(bytes, 100, 80, 8, 400, CGColorSpaceCreateDeviceRGB(), kCGImageAlphaPremultipliedLast)

This creates a context for a 100 pixels by 80 pixels image with a RGBA colorspace.

Note that there limitations on the kinds of context’s you can create, see the Apple documentation about supported pixel formats for the details on that.


This function has an output buffer of indetermined size. You cannot pass None as the value of that buffer but have to explicitly specify a writable output buffer (such an array.array or the right type and size).

Low-level PDF support

Low-level PDF support in the CoreGraphics framework (such as the PDFArrayRef type) are barely supported by PyObjC and these API’s are currently not covered by PyObjC’s testsuite.

Adding support for these API’s is on the todo-list, but adding proper support requires work because the PDFArrayRef type (and simular types) is not a CoreFoundation based type.


The API’s related to CGPSConverter are not supported at the moment.


  • -render:toBitmap:rowBytes:bounds:format:colorSpace

    You must pass a writable buffer of the right size to this method (such as a properly sized instance of array.array.


This function requires a manual wrapper and is not supported yet.


This function requires a manual wrapper and is not supported yet.


This function requires a manual wrapper and is not supported yet.


Pixel format attributes of this type are not supported.