IOFramebufferShared.h Reference

Declared in
IOFramebufferShared.h

Overview

The IOFramebufferShared.h 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.

Included Headers

  • <IOKit/hidsystem/IOHIDTypes.h>

  • <IOKit/graphics/IOGraphicsTypes.h>

  • <libkern/OSAtomic.h>

Data Types

See the Overview section above for header-level documentation.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOFramebufferShared.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOFramebufferShared.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOFramebufferShared.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOFramebufferShared.h

StdFBShmem_t

struct StdFBShmem_t {
   OSSpinLock 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 IOFB_ARBITRARY_FRAMES_CURSOR
   unsigned long long int vblDrift;
   unsigned long long int vblDeltaMeasured;
   unsigned int reservedC[24];
   #else
   unsigned int reservedC[27];
   unsigned char hardwareCursorFlags[kIOFBNumCursorFrames];
   #endif
   unsigned char hardwareCursorCapable;
   unsigned char hardwareCursorActive;
   unsigned char hardwareCursorShields;
   unsigned char reservedB[1];
   #if IOFB_ARBITRARY_FRAMES_CURSOR
   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.

Availability
  • Available in OS X v10.6 and later.
Declared In
IOFramebufferShared.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

   
#define CURSORHEIGHT 16 /* height in pixels */
#define CURSORWIDTH 16 /* width in pixels */
#define IOFB_ARBITRARY_SIZE_CURSOR
#define IOFRAMEBUFFER_CONFORMSTO "IOFramebuffer"
Constants
CURSORHEIGHT

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

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

CURSORWIDTH

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

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

IOFB_ARBITRARY_SIZE_CURSOR

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.

Available in OS X v10.6 and later.

Declared in IOFramebufferShared.h.

IOFRAMEBUFFER_CONFORMSTO

The class name of the framebuffer service.

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

CursorParameters

enum {
   #if IOFB_ARBITRARY_FRAMES_CURSOR
   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.

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

kIOFBNumCursorFramesShift

Used with waiting cursors.

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

kIOFBMaxCursorDepth

The maximum cursor pixel depth.

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

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.
   kIOFBCursorMemory = 100
};
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.

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.

kIOFBCursorMemory

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

Available in OS X v10.0 and later.

Declared in IOFramebufferShared.h.