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 IOFB_ARBITRARY_SIZE_CURSOR 
    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

#define IOFB_ARBITRARY_SIZE_CURSOR 
#define IOFB_ARBITRARY_FRAMES_CURSOR 1 
#endif

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: 2009-02-23