The IOSurfaceAPI header contains the public API for the IOSurface framework. The IOSurface framework provides a framebuffer object suitable for sharing across process boundaries. It is commonly used to allow applications to move complex image decompression and draw logic into a separate process to enhance security.
Language
See the Overview for header-level documentation.
<IOKit/IOKitLib.h>
<IOSurface/IOSurfaceBase.h>
There are cases where it is useful to know whether or not an IOSurface buffer is considered to be "in use" by other users of the same IOSurface. In particular, CoreVideo and other APIs make use of the IOSurface use count facility to know when it is safe to recycle an IOSurface backed CVPixelBuffer object. This is particularly important when IOSurface objects are being shared across process boundaries and the normal mechanisms one might use would not be viable.
The IOSurface use count is similar in concept to any other reference counting scheme. When the global use count of an IOSurface goes to zero, it is no longer considered "in use". When it is anything other than zero, then the IOSurface is still "in use" by someone and therefore anyone attempting to maintain a pool of IOSurfaces to be recycled should not reclaim that IOSurface.
Note that IOSurface maintains both a per-process and an internal system wide usage count. In the current implementation, when the per-process usage count goes from zero to one, the system wide usage count is incremented by one. When the per-process usage count drops back to zero (either via explicit decrement calls or the process terminates), the global usage count is decremented by one.
IOSurfaceGetUseCount() returns the local per-process usage count for an IOSurface. This call is only provided for logging/debugging purposes and should never be used to determine whether an IOSurface is considered to be "in use". IOSurfaceIsInUse() is the only call that should be used for that purpose.
func IOSurfaceDecrementUseCount(IOSurfaceRef)Decrements the per-process usage count for an IOSurface
func IOSurfaceGetUseCount(IOSurfaceRef)Returns the per-process usage count for an IOSurface
func IOSurfaceIncrementUseCount(IOSurfaceRef)Increments the per-process usage count for an IOSurface
func IOSurfaceIsInUse(IOSurfaceRef)Returns true of an IOSurface is in use by any process in the system, otherwise false.
These functions return various properties of a specific plane within a buffer, such as length, height, and so on.
func IOSurfaceGetBaseAddressOfPlane(IOSurfaceRef, Int)Returns the address of the first byte of data in the specified plane.
func IOSurfaceGetBytesPerElementOfPlane(IOSurfaceRef, Int)Returns the size of each element (in bytes) in the specified plane.
func IOSurfaceGetBytesPerRowOfPlane(IOSurfaceRef, Int)Returns the size of each row (in bytes) in the specified plane.
func IOSurfaceGetElementHeightOfPlane(IOSurfaceRef, Int)Returns the height (in pixels) of each element in the specified plane.
func IOSurfaceGetElementWidthOfPlane(IOSurfaceRef, Int)Returns the width (in pixels) of each element in the specified plane.
func IOSurfaceGetHeightOfPlane(IOSurfaceRef, Int)Returns the height of the specified plane (in pixels).
func IOSurfaceGetWidthOfPlane(IOSurfaceRef, Int)Returns the width of the specified plane (in pixels).
These functions return various buffer properties such as length, height, and so on.
func IOSurfaceGetAllocSize(IOSurfaceRef)Returns the total allocation size of the buffer including all planes.
func IOSurfaceGetBaseAddress(IOSurfaceRef)Returns the address of the first byte of data in a particular buffer.
func IOSurfaceGetBytesPerElement(IOSurfaceRef)Returns the length (in bytes) of each element in a particular buffer.
func IOSurfaceGetBytesPerRow(IOSurfaceRef)Returns the length (in bytes) of each row in a particular buffer.
func IOSurfaceGetElementHeight(IOSurfaceRef)Returns the height (in pixels) of each element in a particular buffer.
func IOSurfaceGetElementWidth(IOSurfaceRef)Returns the width (in pixels) of each element in a particular buffer.
func IOSurfaceGetHeight(IOSurfaceRef)Returns the height of the IOSurface buffer in pixels.
func IOSurfaceGetPixelFormat(IOSurfaceRef)Returns an unsigned integer that contains the traditional macOS buffer format.
func IOSurfaceGetWidth(IOSurfaceRef)Returns the width of the IOSurface buffer in pixels.
These functions can be used to obtain handles to IOSurface objects in a form suitable for passing through XPC or Mach IPC.
func IOSurfaceAlignProperty(CFString, Int)Returns the smallest aligned value greater than or equal to the specified value.
func IOSurfaceCreateMachPort(IOSurfaceRef)Returns a mach_port_t that holds a reference to the IOSurface.
func IOSurfaceCreateXPCObject(IOSurfaceRef)Returns an xpc_object_t that holds a reference to the IOSurface.
func IOSurfaceGetPropertyAlignment(CFString)Returns the alignment requirements for a property (if any).
func IOSurfaceGetPropertyMaximum(CFString)Returns the maximum value for a given property that is guaranteed to be compatible with all of the current devices (GPUs, etc.) in the system.
func IOSurfaceLookupFromMachPort(mach_port_t)Recreates an IOSurfaceRef from a mach port.
These functions create new IOSurface buffers and lock and unlock those buffers.
func IOSurfaceCreate(CFDictionary)Creates a brand new IOSurface object
func IOSurfaceGetID(IOSurfaceRef)Retrieves the unique IOSurfaceID value for an IOSurface
func IOSurfaceLock(IOSurfaceRef, IOSurfaceLockOptions, UnsafeMutablePointer<UInt32>?)"Lock" an IOSurface for reading or writing.
func IOSurfaceLookup(IOSurfaceID)Performs an atomic lookup and retain of an IOSurface by its IOSurfaceID.
func IOSurfaceUnlock(IOSurfaceRef, IOSurfaceLockOptions, UnsafeMutablePointer<UInt32>?)"Unlock" an IOSurface for reading or writing.
The functions in this group allow you to attach arbitrary CF property list type objects to an IOSurface buffer. These functions are computationally expensive, and should be used only when necessary.
func IOSurfaceCopyValue(IOSurfaceRef, CFString)Retrieves a value from the dictionary associated with the buffer.
func IOSurfaceRemoveValue(IOSurfaceRef, CFString)Deletes a value in the dictionary associated with the buffer.
func IOSurfaceSetValue(IOSurfaceRef, CFString, CFTypeRef)Sets a value in the dictionary associated with the buffer.
See the Overview for header-level documentation.
IOSurfaceIDAn IOSurface identifier.
IOSurfaceSee the Overview for header-level documentation.