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

IOFramebufferShared.h

Includes:

Overview

This header contains definitions of objects and types shared between a kernel level IOFrameBuffer service and a non-kernel window server. In Mac OS X this structure is used by the CoreGraphics server and IOGraphics Family, and is not available to other clients. IOFramebuffer subclasses and IOFramebuffer clients within the kernel should also not rely on this structure definition and constants. It is public only for use on Darwin based window servers. Cursor and window server state data is exchanged by kernel and non-kernel tasks through a slice of shared memory containing a StdFBShmem_t structure.
For a non-kernel task to get access to this slice of shared memory, a connection to an IOFramebuffer service must be made. A connection is made with the IOServiceOpen() function described in IOKitLib.h. A connection type of kIOFBServerConnectType or kIOFBSharedConnectType (for read-only access) should be specified. An io_connect_t handle is returned by IOServiceOpen(). This handle must be passed to IOFBCreateSharedCursor() to create the slice of shared memory. Then IOConnectMapMemory() may be called with a memory type of kIOFBCursorMemory to map the shared memory into the non-kernel task.

Structs and Unions

bm12Cursor

Cursor image for 1-bit cursor.

struct bm12Cursor { 
    unsigned int image[4][16]; 
    unsigned int mask[4][16]; 
    unsigned int save[16]; 
};

Fields

image
This array contains the cursor images.

mask
This array contains the cursor mask.

save
This array stores the pixel values of the region underneath the cursor in its last drawn position.

Discussion

This structure stores 16 pixel x 16 pixel cursors to be used with 1-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm18Cursor

Cursor image for 8-bit cursor.

struct bm18Cursor { 
    unsigned char image[4][256]; 
    unsigned char mask[4][256]; 
    unsigned char save[256]; 
};

Fields

image
This array contains cursor color values, which are converted to displayed colors through the color table. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel.

mask
This array contains the cursor alpha mask. The array is two dimensional with the same indexing as the image. If an alpha mask pixel is 0 and the corresponding image pixel is set to white for the display, then this cursor pixel will invert pixels on the display.

save
This array stores the color values of the region underneath the cursor in its last drawn position.

Discussion

This structure stores 16 pixel x 16 pixel cursors to be used with 8-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm34Cursor

Cursor image for 15-bit cursor.

struct bm34Cursor { 
    unsigned short image[4][256]; 
    unsigned short save[256]; 
};

Fields

image
This array defines the cursor color values and transparency. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel. A value of 0 means the pixel is transparent. Non-zero values are stored with the red, green, blue, and alpha values encoded with the following masks:
red mask = 0xF000
blue mask 0x0F00
green mask 0x00F0
alpha mask = 0x000F
Note, only 4 bits are allocated for each color component.

save
This array stores the color values of the region underneath the cursor in its last drawn position.

Discussion

This structure stores 16 pixel x 16 pixel cursors to be used with 15-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm38Cursor

Cursor image for 24-bit cursor.

struct bm38Cursor { 
    unsigned int image[4][256]; 
    unsigned int save[256]; 
};

Fields

image
This array defines the cursor color values and transparency. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel. The lower 24 bits of a pixel's value contain the RGB color, while the upper 8 bits contain the alpha value.

save
This array stores the color values of the region underneath the cursor in its last drawn position.

Discussion

This structure stores 16 pixel x 16 pixel cursors to be used with 24-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

StdFBShmem_t

struct StdFBShmem_t { 
    ev_lock_data_t cursorSema; 
    int frame; 
    char cursorShow; 
    char cursorObscured; 
    char shieldFlag; 
    char shielded; 
    IOGBounds saveRect; 
    IOGBounds shieldRect; 
    IOGPoint cursorLoc; 
    IOGBounds cursorRect; 
    IOGBounds oldCursorRect; 
    IOGBounds screenBounds; 
    int version; 
    int structSize; 
    AbsoluteTime vblTime; 
    AbsoluteTime vblDelta; 
    unsigned long long int vblCount; 
    #if 1 
    unsigned int reservedC[28]; 
    #else 
    unsigned int reservedC[27]; 
    unsigned char hardwareCursorFlags[kIOFBNumCursorFrames]; 
    #endif  
    unsigned char hardwareCursorCapable; 
    unsigned char hardwareCursorActive; 
    unsigned char hardwareCursorShields; 
    unsigned char reservedB[1]; 
    #if 1 
    IOGSize cursorSize[kIOFBNumCursorIndex]; 
    IOGPoint hotSpot[kIOFBNumCursorIndex]; 
    #else 
    IOGSize cursorSize[kIOFBNumCursorFrames]; 
    IOGPoint hotSpot[kIOFBNumCursorFrames]; 
    #endif  
    #ifndef  
    union { 
        struct bm12Cursor bw; 
        struct bm18Cursor bw8; 
        struct bm34Cursor rgb; 
        struct bm38Cursor rgb24; 
        } cursor; 
    #else /* IOFB_ARBITRARY_SIZE_CURSOR */
    unsigned char cursor[0]; 
    #endif 
    /* IOFB_ARBITRARY_SIZE_CURSOR */
};

Fields

cursorSema
Semaphore lock for write access to the shared data in this structure.

frame
The current cursor frame index.

cursorShow
The cursor is displayed when cursorShow is 0.

cursorObscured
If this is true, the cursor has been obscured and cursorShow should not be 0. The cursor will be shown again the next time it is moved.

shieldFlag
When this is set to true the cursor will not be displayed in the region specified by shieldRect.

shielded
True if the cursor has been hidden because it entered the shielded region.

saveRect
The region that is saved underneath the cursor in software cursor mode.

shieldRect
The region that the cursor will not be displayed in if shieldFlag is true.

cursorLoc
The location of the cursor hot spot.

cursorRect
The region that the cursor image currently occupies in software cursor mode.

oldCursorRect
The region that the cursor image occupied the last time the cursor was drawn in software cursor mode.

screenBounds
The region that the current screen occupies.

version
Contains kIOFBCurrentShmemVersion so that a user client can ensure it is using the same version of this structure as the kernel.

structSize
Contains the size of this structure.

vblTime
The time of the most recent vertical blanking.

vblDelta
The interval between the two most recent vertical blankings.

vblCount
A running count of vertical blank interrupts.

reservedC
Reserved for future use.

hardwareCursorCapable
True if the hardware is capable of using hardware cursor mode.

hardwareCursorActive
True if currently using the hardware cursor mode.

reservedB
Reserved for future use.

cursorSize
This array contains the cursor sizes indexed by frame.

hotSpot
This array contains the location of the cursor hot spots indexed by frame. The hot spots coordinates are given relative to the top left corner of the cursor image.

cursor
A union of structures that define the cursor images. The structure used depends on the framebuffer's bit depth. These structures are defined above.

Discussion

This structure contains cursor and window server state data and occupies a slice of shared memory between the kernel and window server. Several elements of this structure are only used in software cursor mode. Unless otherwise indicated, the coordinates in this structure are given in display space. Display space is the coordinate space that encompasses all the screens. The positions of the screens within display space indicate their location relative to each other as the cursor moves between them. If there is only one screen, the screen coordinates and display space coordinates will be the same.

Enumerations

CursorParameters

enum { 
    #if 1 
    kIOFBMainCursorIndex = 0, 
    kIOFBWaitCursorIndex = 1, 
    kIOFBNumCursorIndex = 4, 
    #else 
    kIOFBNumCursorFrames = 4, 
    kIOFBNumCursorFramesShift = 2, 
    #endif  
    kIOFBMaxCursorDepth = 32 
};

Constants

kIOFBNumCursorFrames
The number of cursor images stored in the StdFBShmem_t structure.

kIOFBNumCursorFramesShift
Used with waiting cursors.

kIOFBMaxCursorDepth
The maximum cursor pixel depth.

FramebufferConstants

enum { 
    // version for IOFBCreateSharedCursor 
    kIOFBShmemVersionMask = 0x000000ff, 
    kIOFBTenPtOneShmemVersion = 2, 
    kIOFBTenPtTwoShmemVersion = 3, 
    kIOFBCurrentShmemVersion = 2,  
    // number of frames in animating cursor (if > kIOFBTenPtTwoShmemVersion) 
    kIOFBShmemCursorNumFramesMask = 0x00ff0000, 
    kIOFBShmemCursorNumFramesShift = 16,  
    // memory types for IOConnectMapMemory. 
    // 0..n are apertures 
    kIOFBCursorMemory = 100, 
    kIOFBVRAMMemory = 110 
};

Constants

kIOFBCurrentShmemVersion
The current version of the slice of shared memory that contains the cursor and window server state data in the StdFBShmem_t structure.

kIOFBCursorMemory
The memory type for IOConnectMapMemory() to get a slice of shared memory that contains the StdFBShmem_t structure.

kIOFBVRAMMemory
The memory type for IOConnectMapMemory() to get the VRAM memory. Use a memory type equal to the IOPixelAperture index to get a particular pixel aperture.

#defines

CURSORHEIGHT

#define CURSORHEIGHT 16 /* height in pixels */

Discussion

The maximum height of the cursor image in pixels. This is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

CURSORWIDTH

#define CURSORWIDTH 16 /* width in pixels */

Discussion

The maximum width of the cursor image in pixels. This is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

IOFB_ARBITRARY_FRAMES_CURSOR

See Also:

IOFB_ARBITRARY_SIZE_CURSOR

#define IOFB_ARBITRARY_FRAMES_CURSOR 1

Discussion

When IOFB_ARBITRARY_SIZE_CURSOR is not defined, the maximum cursor size is assumed to be CURSORWIDTH x CURSORHEIGHT and this header file will define a number of structures for storing cursor images accordingly. A non-kernel task may define IOFB_ARBITRARY_SIZE_CURSOR and use cursors up to the size specified when IOFBCreateSharedCursor() was called. In this case appropriate structures for storing cursor images must be defined elsewhere. In the kernel, IOFB_ARBITRARY_SIZE_CURSOR is always defined.

IOFB_ARBITRARY_SIZE_CURSOR

See Also:

IOFB_ARBITRARY_FRAMES_CURSOR
IOFB_SUPPORTS_XOR_CURSOR
IOFB_SUPPORTS_HW_SHIELD
IOFB_SUPPORTS_ARBITRARY_FRAMES_CURSOR

#define IOFB_ARBITRARY_SIZE_CURSOR
#define IOFB_ARBITRARY_FRAMES_CURSOR 1
#define IOFB_SUPPORTS_XOR_CURSOR
#define IOFB_SUPPORTS_HW_SHIELD
#define IOFB_SUPPORTS_ARBITRARY_FRAMES_CURSOR

Discussion

IOFB_SUPPORTS_ARBITRARY_FRAMES_CURSOR

See Also:

IOFB_ARBITRARY_SIZE_CURSOR

#define IOFB_SUPPORTS_ARBITRARY_FRAMES_CURSOR

Discussion

IOFB_SUPPORTS_HW_SHIELD

See Also:

IOFB_ARBITRARY_SIZE_CURSOR

#define IOFB_SUPPORTS_HW_SHIELD

Discussion

IOFB_SUPPORTS_XOR_CURSOR

See Also:

IOFB_ARBITRARY_SIZE_CURSOR

 #define IOFB_SUPPORTS_XOR_CURSOR

Discussion

IOFRAMEBUFFER_CONFORMSTO

#define IOFRAMEBUFFER_CONFORMSTO "IOFramebuffer"

Discussion

The class name of the framebuffer service.

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: 2008-03-11