ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOGraphicsLib.h

Includes:

Overview

IOGraphicsLib implements non-kernel task access to IOGraphics family object types - IOFramebuffer and IOAccelerator. These functions implement a graphics family specific API.

A connection to a graphics IOService must be made before these functions are called. A connection is made with the IOServiceOpen function described in IOKitLib.h. An io_connect_t handle is returned by IOServiceOpen, which must be passed to the IOGraphicsLib functions. The appropriate connection type from IOGraphicsTypes.h must be specified in the call to IOServiceOpen. All of the IOFramebuffer functions can only be called from a kIOFBServerConnectType connection. Except as specified below, functions whose names begin with IOFB are IOFramebuffer functions. Functions whose names begin with IOPS are IOAccelerator functions and must be called from connections of type kIOFBEngineControllerConnectType or kIOFBEngineConnectType.

The functions in IOGraphicsLib use a number of special types. The display mode is the screen's resolution and refresh rate. The known display modes are referred to by an index of type IODisplayModeID. The display depth is the number of significant color bits used in representing each pixel. Depths are also referred to by an index value that is 0 for 8 bits, 1 for 15 bits, and 2 for 24 bits. A combination of display mode and depth may have a number of supported pixel formats. The pixel aperture is an index of supported pixel formats for a display mode and depth. This index is of type IOPixelAperture. All of these graphics specific types are defined in IOGraphicsTypes.h.

Functions

IODisplayCreateInfoDictionary: Create a CFDictionary with information about display hardware.
IODisplayMatchDictionaries: Match two display information dictionaries to see if they are for the same display.
IOFBCreateDisplayModeDictionary: Create a CFDictionary with information about a display mode.
IOFBCreateSharedCursor: Create shared cursor memory.
IOFBGetCurrentDisplayModeAndDepth: Get the current display mode and depth.
IOFBGetDisplayModeCount: Get the number of display modes.
IOFBGetDisplayModeInformation: Get information about a display mode.
IOFBGetDisplayModes: Get an array of known display modes.
IOFBGetFramebufferInformationForAperture: Get framebuffer information for a pixel format.
IOFBGetFramebufferOffsetForAperture: Get the byte offset for a framebuffer's VRAM.
IOFBGetPixelFormat: Get pixel format information.
IOFBGetPixelFormats: Get pixel formats that are supported for a display mode and depth.
IOFBGetPixelInfoDictionary: Get a CFDictionary with information about a pixel format.
IOFBGetPixelInformation: Get information about a pixel format.
IOFBSet256To888Table: [place holder]
IOFBSet444To555Table: [place holder]
IOFBSet555To444Table: [place holder]
IOFBSet888To256Table: [place holder]
IOFBSetBounds: Set the location of the framebuffer within display space.
IOFBSetCLUT: Set the color table.
IOFBSetCursorPosition: Set the hardware cursor position.
IOFBSetCursorVisible: Set the hardware cursor visible or invisible.
IOFBSetDisplayModeAndDepth: Set the current display mode and depth.
IOFBSetGamma: Set the gamma data.
IOFBSetNewCursor: Set a new hardware cursor.
IOFBSetStartupDisplayModeAndDepth: Set the display mode and depth to use on startup.

IODisplayCreateInfoDictionary

Create a CFDictionary with information about display hardware.

CFDictionaryRef IODisplayCreateInfoDictionary( 
    io_service_t framebuffer, 
    IOOptionBits options );

Parameters

framebuffer: The IOService handle for an IOFramebuffer service.
options: Use IODisplayDictionaryOptions to specify which keys to include.

Return Value

The returned CFDictionary that should be released by the caller with CFRelease().

Discussion

The CFDictionary created by this function contains information about the display hardware associated with a framebuffer. The keys for the dictionary are listed in IOGraphicsTypes.h.

IODisplayMatchDictionaries

Match two display information dictionaries to see if they are for the same display.

SInt32 IODisplayMatchDictionaries( 
    CFDictionaryRef matching1, 
    CFDictionaryRef matching2, 
    IOOptionBits options );

Parameters

matching1: A CFDictionary returned from IODisplayCreateInfoDictionary().
matching2: Another CFDictionary returned from IODisplayCreateInfoDictionary().
options: No options are currently defined.

Return Value

Returns FALSE if the two displays are not equivalent or TRUE if they are.

Discussion

By comparing two CFDictionaries returned from IODisplayCreateInfoDictionary(), this function determines if the displays are the same. The information compared is what is returned by calling IODisplayCreateInfoDictionary() with an option of kIODisplayMatchingInfo. This includes information such as the vendor, product, and serial number.

IOFBCreateDisplayModeDictionary

Create a CFDictionary with information about a display mode.

CFDictionaryRef IOFBCreateDisplayModeDictionary( 
    io_service_t framebuffer, 
    IODisplayModeID displayMode );

Parameters

framebuffer: The IOService handle for an IOFramebuffer service.
displayMode: A display mode index.

Return Value

The returned CFDictionary that should be released by the caller with CFRelease().

Discussion

This function creates a dictionary containing information about a display mode. The display mode properties that are represented by the kernel as OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, or OSBoolean are converted to their CF counterparts and put in the dictionary.

IOFBCreateSharedCursor

Create shared cursor memory.

extern kern_return_t IOFBCreateSharedCursor(
    io_connect_t connect, 
    unsigned int version, 
    unsigned int maxWidth,
    unsigned int maxHeight );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
version: The version of cursor shared memory to use. For the current version, pass kIOFBCurrentShmemVersion.
maxWidth: The maximum width of the cursor.
maxHeight: The maximum height of the cursor.

Return Value

A kern_return_t error code.

Discussion

This function allocates memory, containing details about the cursor, that can be shared with a calling non-kernel task. The memory contains a StdFBShmem_t structure, which is defined in IOFrameBufferShared.h. This structure contains information on the cursor image, whether it is current shown, its location, etc. The allocated memory can be mapped to the non-kernel task's memory space by calling IOConnectMapMemory() and passing kIOFBCursorMemory for memoryType.

IOFBGetCurrentDisplayModeAndDepth

Get the current display mode and depth.

extern kern_return_t IOFBGetCurrentDisplayModeAndDepth(
    io_connect_t connect, 
    IODisplayModeID *displayMode, 
    IOIndex *depth );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: The ID of the current display mode is returned.
depth: The current display depth is returned (0 = 8 bits, 1 = 15 bits, 2 = 24 bits)

Return Value

A kern_return_t error code.

Discussion

The display mode index returned by this function can be used to determine information about the current display mode and its supported pixel formats through calls to IOFBGetDisplayModeInformation(), IOFBGetPixelFormats(), and IOFBGetPixelInformation().

IOFBGetDisplayModeCount

Get the number of display modes.

kern_return_t IOFBGetDisplayModeCount(
    io_connect_t connect, 
    UInt32 *count );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
count: The display mode count is returned.

Return Value

A kern_return_t error code.

Discussion

IOFBGetDisplayModeCount returns the number of display modes that the IOFramebuffer service is aware of.

IOFBGetDisplayModeInformation

Get information about a display mode.

kern_return_t IOFBGetDisplayModeInformation(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IODisplayModeInformation *info );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: The display mode index.
info: A pointer to an IODisplayModeInformation structure where the display mode information will be returned.

Return Value

A kern_return_t error code.

Discussion

Display modes are referred to by their index of type IODisplayModeID. This function returns a structure containing the width, height, refresh rate, maximum depth, etc. of a display mode. The IODisplayModeInformation structure is defined in IOGraphicsTypes.h.

IOFBGetDisplayModes

Get an array of known display modes.

kern_return_t IOFBGetDisplayModes(
    io_connect_t connect, 
    UInt32 count, 
    IODisplayModeID *allDisplayModes );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
count: The number of display modes to get.
allDisplayModes: An array of IODisplayModeID's with enough space for all entries. The array is filled in upon return.

Return Value

A kern_return_t error code.

Discussion

This function returns an array containing the display modes that the framebuffer service is aware of. To get all display modes, pass the count from IOFBGetDisplayModeCount().

IOFBGetFramebufferInformationForAperture

Get framebuffer information for a pixel format.

extern kern_return_t IOFBGetFramebufferInformationForAperture(
    io_connect_t connect, 
    IOPixelAperture aperture, 
    IOFramebufferInformation *info );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
aperture: The pixel aperture to retrieve information on. The pixel aperture is an index into supported pixel formats for a display mode and depth. To get information for the current aperture, use kIOFBSystemAperture.
info: A pointer to an IOFramebufferInformation structure where the information will be returned.

Return Value

A kern_return_t error code.

Discussion

This function returns framebuffer information for a pixel format that is supported for the current display mode and depth. The returned IOFrameBufferInformation structure contains details on the physical address of the framebuffer, height, width, etc. This structure is defined in IOGraphicsTypes.h.

IOFBGetFramebufferOffsetForAperture

Get the byte offset for a framebuffer's VRAM.

extern kern_return_t IOFBGetFramebufferOffsetForAperture(
    mach_port_t connect, 
    IOPixelAperture aperture, 
    IOByteCount *offset );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
aperture: The pixel aperture to retrieve information on. The pixel aperture is an index into supported pixel formats. To get information for the current aperture, use kIOFBSystemAperture.
offset: The number of bytes offset is returned on success.

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBGetPixelFormat

Get pixel format information.

extern kern_return_t IOFBGetPixelFormat(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IOIndex depth, 
    IOPixelAperture aperture, 
    IOPixelEncoding *pixelFormat );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: A display mode index.
depth: A display depth index.
aperture: The pixel aperture to retrieve the pixel format for. The pixel aperture is an index into supported pixel formats. To get information on the current aperture, use kIOFBSystemAperture.
pixelFormat: The returned pixel format.

Return Value

A kern_return_t error code.

Discussion

Displayed colors are encoded in framebuffer memory in a variety of ways. IOFBGetPixelFormat returns a pixel encoding array specifying how each bit of a particular pixel should be interpreted. The definition of the IOPixelEncoding array returned and common Apple pixel formats are described in IOGraphicsTypes.h.

IOFBGetPixelFormats

Get pixel formats that are supported for a display mode and depth.

kern_return_t IOFBGetPixelFormats(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IOIndex depth, 
    UInt32 *mask );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: A display mode index.
depth: A display depth index.
mask: The returned mask of pixel formats.

Return Value

A kern_return_t error code.

Discussion

This function returns a mask of all supported pixel formats for a particular display mode and depth. [How should the mask be interpreted?]

IOFBGetPixelInfoDictionary

Get a CFDictionary with information about a pixel format.

CFDictionaryRef IOFBGetPixelInfoDictionary( 
    CFDictionaryRef modeDictionary, 
    IOIndex depth, 
    IOPixelAperture aperture );

Parameters

modeDictionary: The CFDictionary containing information about a display mode.
depth: A depth index.
aperture: The pixel aperture to information about. The pixel aperture is an index into supported pixel formats. To get information on the current aperture, use kIOFBSystemAperture.

Return Value

The returned CFDictionary that should be released by the caller with CFRelease().

Discussion

This function extracts a CFDictionary containing information about a supported pixel format from a larger CFDictionary describing a display mode. IOFBCreateDisplayModeDictionary() must be called first to generate the CFDictionary for a display mode.

IOFBGetPixelInformation

Get information about a pixel format.

kern_return_t IOFBGetPixelInformation(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IOIndex depth, 
    IOPixelAperture aperture, 
    IOPixelInformation *pixelInfo );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: A display mode index.
depth: A display depth index.
aperture: A pixel aperture. The pixel aperture is an index into supported pixel formats for a display mode and depth. To get information on the current aperture, use kIOFBSystemAperture.
pixelInfo: A pointer to an IOPixelInformation structure where the pixel information will be returned.

Return Value

A kern_return_t error code.

Discussion

IOFBGetPixelInformation returns a structure containing information about a pixel format such as the bits per pixel, pixel format, etc. The IOPixelInformation structure is defined in IOGraphicsTypes.h.

IOFBSet256To888Table

[place holder]

extern kern_return_t IOFBSet256To888Table(
    io_connect_t connect, 
    const unsigned int * table );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBSet444To555Table

[place holder]

extern kern_return_t IOFBSet444To555Table(
    io_connect_t connect, 
    const unsigned char * table );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBSet555To444Table

[place holder]

extern kern_return_t IOFBSet555To444Table(
    io_connect_t connect, 
    const unsigned char * table );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBSet888To256Table

[place holder]

extern kern_return_t IOFBSet888To256Table(
    io_connect_t connect, 
    const unsigned char * table );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBSetBounds

Set the location of the framebuffer within display space.

extern kern_return_t IOFBSetBounds(
    io_connect_t connect, 
    IOGBounds *rect );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
rect: An IOGBounds structure specifying a rectangular region of the framebuffer.

Return Value

A kern_return_t error code.

Discussion

If there is more than one screen in use, the locations of the screens relative to each other must be specified. These locations are specified in a "display space" that encompasses all the screens. The bounding regions of the screens within display space indicate their location relative to each other as the cursor moves between them. This function sets the bounding region for a framebuffer within display space. If there is only one screen, this does not need to specified, because by default the screen coordinates and display space coordinates will be the same.

IOFBSetCLUT

Set the color table.

extern kern_return_t IOFBSetCLUT(
    io_connect_t connect, 
    UInt32 startIndex, 
    UInt32 numEntries, 
    IOOptionBits options, 
    IOColorEntry *colors );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
startIndex: The first index to set in the color table.
numEntries: The number of entries to set.
options: kSetCLUTByValue may be set to use the index member of the IOColorEntry structure to determine where the entry should be written to the color table. Otherwise the index is taken from the location in the IOColorEntry array. kSetClutImmediately may be set to change the color table immediately instead of waiting for vertical blanking interval. kSetClubWithLuminance may be set to use luminance rather than RGB entries.
colors: The array of color table entries to set. The IOColorEntry structure is defined in IOGraphicsTypes.h.

Return Value

A kern_return_t error code.

Discussion

Indexed pixel formats require a color table to convert from the index stored in a pixel memory location to a displayed color. IOFBSetCLUT sets one or more entries of the color table.

IOFBSetCursorPosition

Set the hardware cursor position.

kern_return_t IOFBSetCursorPosition(
    io_connect_t connect, 
    long int x, 
    long int y );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
x: The x coordinate.
y: The y coordinate.

Return Value

A kern_return_t error code.

Discussion

This function only works with the hardware cursor and will fail if a hardware cursor is not supported.

IOFBSetCursorVisible

Set the hardware cursor visible or invisible.

kern_return_t IOFBSetCursorVisible(
    io_connect_t connect, 
    int visible );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
visible: TRUE to make the cursor visible and FALSE to make it invisible.

Return Value

A kern_return_t error code.

Discussion

The hardware cursor can only be set visible or invisible when it is active. Use IOFBSetNewCursor() to activate the hardware cursor.

IOFBSetDisplayModeAndDepth

Set the current display mode and depth.

kern_return_t IOFBSetDisplayModeAndDepth(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IOIndex depth );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: The index of the new display mode.
depth: The index of the new depth.

Return Value

A kern_return_t error code.

IOFBSetGamma

Set the gamma data.

extern kern_return_t IOFBSetGamma(
    io_connect_t connect, 
    UInt32 channelCount, 
    UInt32 dataCount, 
    UInt32 dataWidth, 
    void *data );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
channelCount
dataCount
dataWidth
data

Return Value

A kern_return_t error code.

Discussion

[place holder]

IOFBSetNewCursor

Set a new hardware cursor.

kern_return_t IOFBSetNewCursor(
    io_connect_t connect, 
    void *cursor, 
    IOIndex frame, 
    IOOptionBits options );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
cursor: This parameter is currently not used and must be 0.
frame: An index to the cursor image to use that must be less than kIOFBNumCursorFrames. Currently only frame 0 is supported.
options: No options are currently defined.

Return Value

A kern_return_t error code.

Discussion

A non-kernel task interacts with the IOFramebuffer service through a slice of shared memory that is created with the IOFBCreateSharedCursor function. The shared memory is a structure of type StdFBShmem_t. In this shared memory several cursor images, or frames may be defined. The maximum number of frames is kIOFBNumCursorFrames. StdFBShmem_t and kIOFBNumCursorFrames are defined in IOFramebufferShared.h. This function sets a new frame to be used as the current cursor image and activates the hardware cursor.

IOFBSetStartupDisplayModeAndDepth

Set the display mode and depth to use on startup.

kern_return_t IOFBSetStartupDisplayModeAndDepth(
    io_connect_t connect, 
    IODisplayModeID displayMode, 
    IOIndex depth );

Parameters

connect: The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode: The index of the new display mode.
depth: The index of the new depth.

Return Value

A kern_return_t error code.

Enumerations

IODisplayDictionaryOptions

enum { 
    kIODisplayMatchingInfo = 0x00000100, 
    kIODisplayOnlyPreferredName = 0x00000200, 
    kIODisplayNoProductName = 0x00000400 
};

Constants

kIODisplayMatchingInfo

Include only the keys necessary to match two displays with IODisplayMatchDictionaries().

kIODisplayOnlyPreferredName

The kDisplayProductName property includes only the localized names returned by CFBundleCopyPreferredLocalizationsFromArray().

kIODisplayNoProductName

The kDisplayProductName property is not included in the returned dictionary.

#defines

IOCreateDisplayInfoDictionary

#define IOCreateDisplayInfoDictionary(f,o) \ 
    IODisplayCreateInfoDictionary(f,o)

Discussion

IOCreateDisplayInfoDictionary() was renamed IODisplayCreateInfoDictionary(). IOCreateDisplayInfoDictionary() is now a macro for IODisplayCreateInfoDictionary() for compatibility with older code.

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.

Last Updated: 2009-02-23