ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOFramebuffer

Inherits from:	IOGraphicsDevice
Declared In:	IOFramebuffer.h

Overview

The base class for graphics devices to be made available as part of the desktop.

Discussion

The IOFramebuffer base class defines APIs used to publish a linear framebuffer device. Device driver writers should subclass this class to provide a X native driver. Mac OS X will also utilize 'ndrv' drivers via a subclass of IOFramebuffer IONDRVFramebuffer that does not require device driver writers to provide a X native driver.

There are no in kernel clients of IOFramebuffer aside from rudimentary console and panic UI supported by the IOFramebuffer class. The IOFramebuffer class provides the IOUserClient implementation to allow the CoreGraphics server to provide the user accessible interface to all displays on a Mac OS X system, and this is further layered underneath application frameworks. Device driver writers should not need any knowledge of this part of the interfaces. Similarly the instance variables of IOFramebuffer are mostly used for cursor rendering which is handled by the IOFramebuffer class, and should be avoided by subclass implementors. Only IOFramebuffer methods with header documentation in this header are designed for subclasses to implement.

IOFramebuffer provides simple dumb framebuffer operation - accceleration for 2D, 3D and video may be provided by a separate implementation of the IOAccelerator class.

Functions

connectFlags: Return display sense information for legacy Apple sensing.
convertCursorImage: Utility method of IOFramebuffer to convert cursor image to a hardware cursor format.
doI2CRequest: Carry out an I2C request.
enableController: Perform first time setup of the framebuffer.
flushCursor: Perform any needed cache flushing after software cursor rendering.
getApertureRange: Return reference to IODeviceMemory object representing memory range of framebuffer.
getAppleSense: Return display sense information for legacy Apple sensing.
getAttribute: Generic method to retrieve some attribute of the framebuffer device.
getAttributeForConnection: Generic method to retrieve some attribute of the framebuffer device, specific to one display connection.
getConnectionCount: Reports the number of display connections the device supports, driven from one framebuffer.
getCurrentDisplayMode(IODisplayModeID *, IOIndex *): Return the framebuffers current display mode and depth.
getCurrentDisplayMode(IODisplayModeID *, IOIndex *): Return the framebuffers display mode and depth to be used during boot and at startup.
getDDCBlock: Return display EDID data.
getDisplayModeCount: Return the number of display modes the framebuffer supports.
getDisplayModes: Return the number of display modes the framebuffer supports.
getInformationForDisplayMode: Return information about a given display mode.
getPixelFormats: List the pixel formats the framebuffer supports.
getPixelFormatsForDisplayMode: Obsolete.
getPixelInformation: Return information about the framebuffer format for a given display mode and depth.
getStartupDisplayMode: Return the framebuffers display mode and depth to be used during boot and at startup.
getTimingInfoForDisplayMode: Returns a timing description for a display mode.
getVRAMRange: Return reference to IODeviceMemory object representing memory range of all the cards vram.
handleEvent: Notify IOFramebuffer superclass code of events.
hasDDCConnect: Return display DDC connect state.
readDDCClock: Reads the input state of the I2C clock line on a bus.
readDDCData: Reads the input state of the I2C data line on a bus.
registerForInterruptType: Set callbacks for driver to call on interrupt events.
setApertureEnable: Enable an aperture on the framebuffer (usually unimplemented, no OS usage).
setAttribute: Generic method to set some attribute of the framebuffer device.
setAttributeForConnection: Generic method to set some attribute of the framebuffer device, specific to one display connection.
setCLUTWithEntries: Set the color lookup table to be used by the framebuffer in indexed modes.
setCurrentDisplayMode: Set the framebuffers current display mode and depth.
setCursorImage: Set a new image for the hardware cursor.
setCursorState: Set a new position and visibility for the hardware cursor.
setDDCClock: Sets the state of the I2C clock line on a bus.
setDDCData: Sets the state of the I2C data line on a bus.
setDetailedTimings: Installs an array of OS programmed detailed timings to be made available by the driver.
setDisplayMode: Set the framebuffers current display mode and depth.
setGammaTable: Set the gamma table to be used by the framebuffer.
setInterruptState: Enable or disable a callback previously installed by registerForInterruptType().
setStartupDisplayMode: Set the framebuffers display mode and depth to be used during boot and at startup.
unregisterInterrupt(void *): Remove a callback previously installed by registerForInterruptType().
unregisterInterrupt(void *, UInt32): Enable or disable a callback previously installed by registerForInterruptType().
validateDetailedTiming: Reports whether a detailed timing is able to be programmed with the device.

connectFlags

Return display sense information for legacy Apple sensing.

public

virtual IOReturn connectFlags(
    IOIndex connectIndex, 
    IODisplayModeID displayMode,
    IOOptionBits *flags );

Parameters

connectIndex: Index of the display connection, from zero to the value of getConnectionCount().
displayMode: A display mode ID.
flags: Return the flags value for the given mode with the connected display. Flags are:
kDisplayModeValidFlag - mode is considered valid for the connected display by the driver. kDisplayModeSafeFlag - mode is considered safe (not requiring mode change confirmation) for the connected display by the driver. kDisplayModeDefaultFlag - mode is considered default for the connected display by the driver.

Return Value

An IOReturn code.

Discussion

Hardware that supports simple display sensing, or the classic 3 pin Apple sensing described in Designing Cards and Drivers, should implement this method to return mode flags relative to the sensed display. If this method is unimplemented, all modes have are given the flags kDisplayModeValidFlag | kDisplayModeSafeFlag.

convertCursorImage

Utility method of IOFramebuffer to convert cursor image to a hardware cursor format.

public

virtual bool convertCursorImage(
    void *cursorImage, 
    IOHardwareCursorDescriptor *description, 
    IOHardwareCursorInfo *cursor );

Parameters

cursorImage: Opaque cursor parameter from the setCursorImage() call.
description: Describes the cursor format supported by the driver.
cursor: Structure describing the drivers allocated buffer to receive the converted image.

Return Value

a bool indicating the conversion was successful.

Discussion

IOFramebuffer subclasses may implement hardware cursor functionality, if so they should pass the cursor image given by the setCursorImage() method, with a description of their hardware cursor format, to this helper function to this routine to convert the image to one suitable for the hardware.

doI2CRequest

Carry out an I2C request.

public

virtual IOReturn doI2CRequest(
    UInt32 bus,
    struct IOI2CBusTiming *timing,
    struct IOI2CRequest *request );

Parameters

timing: Subclasses may pass timing parameters tuned for the specific bus, otherwise if NULL, VESA DDC defaults will apply.
request: An IOI2CRequest structure. The request should be carried out synchronously if the completion routine is NULL, otherwise it may optionally be carried out asynchronously. The completion routine should be called if supplied.

Return Value

an IOReturn code. If kIOReturnSuccces, the result of the transaction is returned in the requests result field.

Discussion

IOFramebuffer subclasses may optionally implement this method to perform I2C bus requests on one of the buses they support. Alternatively they may implement the setDDCClock(), setDDCData(), readDDCClock(), readDDCData() methods and respond from getAttributeForConnection() to the kConnectionSupportsLLDDCSense attribute with success, in which case IOFramebuffer::doI2CRequest() will carry out a software implementation of I2C using the low level routines and conforming to the timing constraints passed in the timing parameter. Subclasses may pass timing parameters tuned for the specific bus, otherwise VESA DDC defaults will apply.

enableController

Perform first time setup of the framebuffer.

public

virtual IOReturn enableController(
    void );

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses should perform their initialization of the hardware here. The IOService start() method is not called at a time appropriate for this initialization.

flushCursor

Perform any needed cache flushing after software cursor rendering.

public

virtual void flushCursor(
    void );

Discussion

IOFramebuffer implements software cursor functionality when a hardware cursor is unavailable. Some hardware may need to flush a cache after the processor has finished lifting and dropping the software cursor.

getApertureRange

Return reference to IODeviceMemory object representing memory range of framebuffer.

public

virtual IODeviceMemory * getApertureRange(
    IOPixelAperture aperture ) = 0;

Parameters

aperture: The system will only access the aperture kIOFBSystemAperture.

Return Value

an IODeviceMemory instance. A reference will be consumed by the caller for each call of this method - the implementatation should create a new instance of IODeviceMemory for each call, or return one instance with a retain for each call.

Discussion

IOFramebuffer subclasses must implement this method to describe the memory used by the framebuffer in the current mode. The OS will map this memory range into user space for client access - the range should only include vram memory not hardware registers.

getAppleSense

Return display sense information for legacy Apple sensing.

public

virtual IOReturn getAppleSense(
    IOIndex connectIndex, 
    UInt32 *senseType, 
    UInt32 *primary, 
    UInt32 *extended, 
    UInt32 *displayType );

Parameters

connectIndex: Index of the display connection, from zero to the value of getConnectionCount().
senseType: Return zero to indicate legacy Apple sensing.
primary: Return the value of the primary Apple sense code.
extended: Return the value of the secondary Apple sense code.
displayType: Return an Apple defined constant for the type of display sensed. For example, kVGAConnect, kNTSCConnect, kPALConnect etc.

Return Value

An IOReturn code.

Discussion

Hardware that supports simple display sensing, or the classic 3 pin Apple sensing described in Designing Cards and Drivers, should implement this method to return sense information.

getAttribute

Generic method to retrieve some attribute of the framebuffer device.

public

virtual IOReturn getAttribute(
    IOSelect attribute,
    UInt32 *value );

Parameters

attribute: Defines the attribute to be set. Some defined attributes are:
kIOHardwareCursorAttribute If the device supports a hardware cursor and implements the setCursorImage() and setCursorState() calls it should return true for this attribute.
value: Returns the value for the attribute.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be returned.

getAttributeForConnection

Generic method to retrieve some attribute of the framebuffer device, specific to one display connection.

public

virtual IOReturn getAttributeForConnection(
    IOIndex connectIndex, 
    IOSelect attribute,
    UInt32 *value );

Parameters

attribute: Defines the attribute to be returned. Some defined attributes are:
kConnectionSupportsHLDDCSense If the framebuffer supports the DDC methods hasDDCConnect() and getDDCBlock() it should return success (and no value) for this attribute.
kConnectionSupportsLLDDCSense If the framebuffer wishes to make use of IOFramebuffer::doI2CRequest software implementation of I2C it should implement the I2C methods setDDCClock(), setDDCData(), readDDCClock(), readDDCData(), and it should return success (and no value) for this attribute.
value: Returns the value for the attribute.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be returned, specific to one display connection.

getConnectionCount

Reports the number of display connections the device supports, driven from one framebuffer.

public

virtual IOItemCount getConnectionCount(
    void );

Return Value

A count of the number of display connections reported by the framebuffer. Current versions of OS X only support one connection completely.

Discussion

IOFramebuffer subclasses may implement functionality where a single framebuffer drives multiple displays. This is not recommended or fully supported and instead multihead cards should implement multiple instances of IOFramebuffer objects to provide full functionality.

getCurrentDisplayMode(IODisplayModeID , IOIndex )

Return the framebuffers current display mode and depth.

public

virtual IOReturn getCurrentDisplayMode(
    IODisplayModeID *displayMode, 
    IOIndex *depth ) = 0;

Parameters

displayMode: A display mode ID representing the current mode.
depth: An index indicating the depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses must implement this method to return the current mode and depth.

getCurrentDisplayMode(IODisplayModeID , IOIndex )

Return the framebuffers display mode and depth to be used during boot and at startup.

public

virtual IOReturn getStartupDisplayMode(
    IODisplayModeID *displayMode, 
    IOIndex *depth );

Parameters

displayMode: A display mode ID representing the mode used during startup.
depth: An index indicating the depth configuration of the framebuffer used during startup. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses should implement this method to return the current mode and depth.

getDDCBlock

Return display EDID data.

public

virtual IOReturn getDDCBlock(
    IOIndex connectIndex,
    UInt32 blockNumber, 
    IOSelect blockType,
    IOOptionBits options, 
    UInt8 *data,
    IOByteCount *length );

Parameters

connectIndex: Index of the display connection, from zero to the value of getConnectionCount().
blockNumber: Block number, ranging from one to the number of blocks return by the display.
blockType: kIODDCBlockTypeEDID will be passed.
options: No options are currently defined.
data: Caller allocated buffer to receive the blocks data.
length: In/out parameter - callers allocated buffer size, driver returns actual size.

Return Value

An IOReturn code.

Discussion

Hardware that supports DDC/EDID display sensing should implement this method to return EDID data in 128 byte blocks.

getDisplayModeCount

Return the number of display modes the framebuffer supports.

public

virtual IOItemCount getDisplayModeCount(
    void ) = 0;

Return Value

A count of the display modes available.

Discussion

IOFramebuffer subclasses must implement this method to return a count of the display modes available. This count should change unless a connection change is posted for the device indicated the framebuffer and/or display configuration has changed.

getDisplayModes

Return the number of display modes the framebuffer supports.

public

virtual IOReturn getDisplayModes(
    IODisplayModeID *allDisplayModes ) = 0;

Parameters

allDisplayModes: A caller allocated buffer with the size given by the result of getDisplayModeCount().

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses must implement this method to return an array of display mode IDs available for the framebuffer. The IDs are defined by the driver in the range 0x00000001 - 0x7fffffff, and should be constant for a given display mode.

getInformationForDisplayMode

Return information about a given display mode.

public

virtual IOReturn getInformationForDisplayMode(
    IODisplayModeID displayMode, 
    IODisplayModeInformation *info ) = 0;

Parameters

displayMode: A display mode ID previously returned by getDisplayModes().
info: Pointer to a structure of type IODisplayModeInformation to be filled out by the driver. IODisplayModeInformation is documented in IOGraphicsTypes.h.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses must implement this method to return information in the IODisplayModeInformation structure for the display mode with the passed ID.

getPixelFormats

List the pixel formats the framebuffer supports.

public

virtual const char * getPixelFormats( void ) = 0;

Return Value

A const char * pointer. The string consists of a concatenation of each pixel format string separated by the NULL character. The commonly supported pixel formats for Mac OS X are defined as IO8BitIndexedPixels, IO16BitDirectPixels, IO32BitDirectPixels.

Discussion

IOFramebuffer subclasses must implement this method to return an array of strings representing the possible pixel formats available in the framebuffer.

getPixelFormatsForDisplayMode

Obsolete.

public

virtual UInt64 getPixelFormatsForDisplayMode(
    IODisplayModeID displayMode, 
    IOIndex depth ) = 0;

Parameters

displayMode: Ignored.
depth: Ignored.

Return Value

Return zero.

Discussion

IOFramebuffer subclasses must implement this method to return zero.

getPixelInformation

Return information about the framebuffer format for a given display mode and depth.

public

virtual IOReturn getPixelInformation( 
    IODisplayModeID displayMode,
    IOIndex depth, 
    IOPixelAperture aperture,
    IOPixelInformation *pixelInfo ) = 0;

Parameters

displayMode: A display mode ID previously returned by getDisplayModes().
depth: An index from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure (inclusive).
info: Pointer to a structure of type IOPixelInformation to be filled out by the driver. IOPixelInformation is documented in IOGraphicsTypes.h.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses must implement this method to return information in the IOPixelInformation structure for the display mode with the passed ID, depth index and aperture. The aperture utilized by the system is always kIOFBSystemAperture. Drivers may define alternative apertures, being a view of the framebuffer in a different pixel format from the default.

getStartupDisplayMode

Return the framebuffers display mode and depth to be used during boot and at startup.

public

virtual IOReturn getStartupDisplayMode(
    IODisplayModeID *displayMode, 
    IOIndex *depth );

Parameters

displayMode: A display mode ID representing the mode used during startup.
depth: An index indicating the depth configuration of the framebuffer used during startup. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses should implement this method to return the current mode and depth.

getTimingInfoForDisplayMode

Returns a timing description for a display mode.

public

virtual IOReturn getTimingInfoForDisplayMode( 
    IODisplayModeID displayMode,
    IOTimingInformation *info );

Parameters

displayMode: A display mode ID representing the mode to examine.
info: The driver returns the information for the display mode in this structure.
If the mode has an Apple defined constant, such as timingVESA_1024x768_75hz, it should be returned in the appleTimingID field. Otherwise the field should be set to timingInvalid.
If the driver is able to supply detailed timing information, it should return it in the detailedInfo.v2 field of the structure, otherwise the driver should clear the kIODetailedTimingValid flag from the flags field.
The IODetailedTimingInformationV2 structure is documented in IOGraphicsTypes.h

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses should implement this method to return timing information for a display mode. This allows the OS to enable display modes based on its knowledge of the connected display type. Two types of timing information are defined, by Apple defined constant, or by a detailed description of the timing parameters of the mode.

getVRAMRange

Return reference to IODeviceMemory object representing memory range of all the cards vram.

public

virtual IODeviceMemory * getVRAMRange(
    void );

Return Value

Discussion

IOFramebuffer subclasses should implement this method to describe all the vram memory available on the card. The OS will map this memory range into user space for client access - the range should only include vram memory not hardware registers.

handleEvent

Notify IOFramebuffer superclass code of events.

protected

IOReturn handleEvent(
    IOIndex event,
    void *info = 0 );

Parameters

event: The event that has occurred:
kIOFBNotifyWillPowerOff call before entering a state other than the maximum.
kIOFBNotifyDidPowerOn call after entering the maximum power state.
kIOFBNotifyWillPowerOff call before entering a state other than the maximum.
kIOFBNotifyDidPowerOn call after entering a state other than the maximum.
info: None of the above events require additional info, pass zero.

Return Value

an IOReturn code, safely ignored.

Discussion

IOFramebuffer subclasses should call this IOFramebuffer method on certain power state changes.

hasDDCConnect

Return display DDC connect state.

public

virtual bool hasDDCConnect(
    IOIndex connectIndex );

Parameters

connectIndex: Index of the display connection, from zero to the value of getConnectionCount().

Return Value

True if a DDC display is detected.

Discussion

Hardware that supports DDC/EDID display sensing should implement this method to return true if a DDC display is detected. They should also return success for the connection attribute kConnectionSupportsHLDDCSense (from getAttributeForConnection()).

readDDCClock

Reads the input state of the I2C clock line on a bus.

public

virtual bool readDDCClock(
    IOIndex bus );

Parameters

bus: Index of the bus.

Return Value

A boolean reflecting the current state of the clock line on the given bus.

Discussion

Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to return the input state of the I2C clock line on the given bus. Otherwise may be unimplemented.

readDDCData

Reads the input state of the I2C data line on a bus.

public

virtual bool readDDCData(
    IOIndex bus );

Parameters

bus: Index of the bus.

Return Value

A boolean reflecting the current state of the data line on the given bus.

Discussion

Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to return the input state of the I2C data line on the given bus. Otherwise may be unimplemented.

registerForInterruptType

Set callbacks for driver to call on interrupt events.

public

virtual IOReturn registerForInterruptType(
    IOSelect interruptType, 
    IOFBInterruptProc proc,
    OSObject *target,
    void *ref, 
    void **interruptRef );

Parameters

interruptType: One of these constants:
kIOFBVBLInterruptType Specifying a vertical blanking interrupt. kIOFBConnectInterruptType Specify the display connection should be resensed.
proc: C callback to be called by the driver when the specified event occurs.
target: Target parameter for the callback proc.
ref: Ref parameter for the callback proc.
interruptRef: The subclass should return an opaque reference to the installed interrupt handler, for use with unregisterInterrupt() and setInterruptState().

Return Value

An IOReturn code.

Discussion

The IOFramebuffer class will call its subclasses to set callbacks to be called on interrupt events generated by hardware events. Only two are currently in use - vertical blank interrupts and connection changed interrupts.

setApertureEnable

Enable an aperture on the framebuffer (usually unimplemented, no OS usage).

public

virtual IOReturn setApertureEnable(
    IOPixelAperture aperture, 
    IOOptionBits enable );

Parameters

aperture: A device specific aperture index.
enable: Device specific mask of options.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to set enable a non standard aperture. The system does not call this method.

setAttribute

Generic method to set some attribute of the framebuffer device.

public

virtual IOReturn setAttribute(
    IOSelect attribute,
    UInt32 value );

Parameters

attribute: Defines the attribute to be set. Some defined attributes are:
kIOPowerAttribute The IOFramebuffer class implements most power management (IOService) methods. It calls the subclass to carry out the power management state change with this attribute. When carrying out power state changes, the subclass should call IOFramebuffer::handleEvent for certain changes - set that method for more information.
value: The new value for the attribute.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be set.

setAttributeForConnection

Generic method to set some attribute of the framebuffer device, specific to one display connection.

public

virtual IOReturn setAttributeForConnection(
    IOIndex connectIndex, 
    IOSelect attribute,
    UInt32 value );

Parameters

attribute: Defines the attribute to be set. Some defined attributes are:
kIOCapturedAttribute If the device supports hotplugging displays, it should disable the generation of hot plug interrupts when the attribute kIOCapturedAttribute is set to true.
value: The new value for the attribute.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be set, specific to one display connection.

setCLUTWithEntries

Set the color lookup table to be used by the framebuffer in indexed modes.

public

virtual IOReturn setCLUTWithEntries(
    IOColorEntry *colors,
    UInt32 index, 
    UInt32 numEntries,
    IOOptionBits options );

Parameters

colors: A pointer to an array of numEntries RGB color entries.
index: The index of the first entry to set.
numEntries: The number of entries in the table.
options: Options controlling the operation.
kSetCLUTByValue is set if the index field of each entry should be used to set the table sparsely, otherwise consecutive entries from the index parameter should be set.
kSetCLUTImmediately is set if the CLUT set should not be synchronized with the vertical blank, otherwise it should.
kSetCLUTWithLuminance is set if the CLUT should be set to a gray value equivalent in luminance to the passed color entry.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses may implement this method to allow a palette to be set for indexed display modes. It will not be called on framebuffers in direct display modes.

setCurrentDisplayMode

Set the framebuffers current display mode and depth.

public

virtual IOReturn setDisplayMode(
    IODisplayModeID displayMode, 
    IOIndex depth );

Parameters

displayMode: A display mode ID representing the new mode.
depth: An index indicating the new depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

IOFramebuffer subclasses should implement this method to set the current mode and depth. Other than at enableController() time, this is the only method that should change the framebuffer format and is synchronized with clients and attached accelerators to make sure access to the device is disallowed during the change.

setCursorImage

Set a new image for the hardware cursor.

public

virtual IOReturn setCursorImage(
    void *cursorImage );

Parameters

cursorImage: Opaque cursor description. This should be passed to the convertCursorImage() method to convert to a format specific to the hardware.

Return Value

An IOReturn code.

Discussion

IOFramebuffer subclasses may implement hardware cursor functionality, if so they should implement this method to change the hardware cursor image. The image should be passed to the convertCursorImage() method with each type of cursor format the hardware supports until success, if all fail the hardware cursor should be hidden and kIOReturnUnsupported returned.

setCursorState

Set a new position and visibility for the hardware cursor.

public

virtual IOReturn setCursorState(
    SInt32 x,
    SInt32 y,
    bool visible );

Parameters

x: Left coordinate of the cursor image. A signed value, will be negative if the cursor's hot spot and position place it partly offscreen.
y: Top coordinate of the cursor image. A signed value, will be negative if the cursor's hot spot and position place it partly offscreen.
visible: Visible state of the cursor.

Return Value

An IOReturn code.

Discussion

IOFramebuffer subclasses may implement hardware cursor functionality, if so they should implement this method to change the position and visibility of the cursor.

setDDCClock

Sets the state of the I2C clock line on a bus.

public

virtual void setDDCClock(
    IOIndex bus,
    UInt32 value );

Parameters

bus: Index of the bus.
value: One of kIODDCLow, kIODDCHigh, kIODDCTristate.

Discussion

Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to set the state of the I2C clock line on the given bus. Otherwise may be unimplemented.

setDDCData

Sets the state of the I2C data line on a bus.

public

virtual void setDDCData(
    IOIndex bus,
    UInt32 value );

Parameters

bus: Index of the bus.
value: One of kIODDCLow, kIODDCHigh, kIODDCTristate.

Discussion

Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to set the state of the I2C data line on the given bus. Otherwise may be unimplemented.

setDetailedTimings

Installs an array of OS programmed detailed timings to be made available by the driver.

public

virtual IOReturn setDetailedTimings(
    OSArray *array );

Parameters

array: An OSArray of OSData objects. Each OSData contains one IODetailedTimingInformationV2 structure. All the data described by the array should be copied or retained by this call until the next invocation of this method.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from installing the programmable modes.

Discussion

IOFramebuffer subclasses may implement programmable mode functionality where the OS is able to install modes described by a detailed timing into the driver. The driver needs to add these modes to its internal mode list if it provides this functionality.

setDisplayMode

Set the framebuffers current display mode and depth.

public

virtual IOReturn setDisplayMode(
    IODisplayModeID displayMode, 
    IOIndex depth );

Parameters

displayMode: A display mode ID representing the new mode.
depth: An index indicating the new depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.

Discussion

setGammaTable

Set the gamma table to be used by the framebuffer.

public

virtual IOReturn setGammaTable(
    UInt32 channelCount,
    UInt32 dataCount, 
    UInt32 dataWidth,
    void *data );

Parameters

channelCount: Defines the number of channels in the supplied data. OS X will pass three for separate R, G, B data, or one if the same data should apply to all channels.
dataCount: The number of data entries per channel.
dataWidth: The number of bits in each entry. 8 for Mac OS X 10.1 and earlier, 16 for later releases.
data: The packed array of correction data. Data is passed for the R (or single) channel followed by the G & B channels. Each entry is one or two bytes (if dataWidth > 8).

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses should implement this method to allow a gamma table to be set.

setInterruptState

Enable or disable a callback previously installed by registerForInterruptType().

public

virtual IOReturn setInterruptState(
    void *interruptRef,
    UInt32 state );

Parameters

state: True or false to enable the callback.

Return Value

An IOReturn code.

Discussion

Enable or disable a callback previously installed by registerForInterruptType().

setStartupDisplayMode

Set the framebuffers display mode and depth to be used during boot and at startup.

public

virtual IOReturn setStartupDisplayMode(
    IODisplayModeID displayMode, 
    IOIndex depth );

Parameters

displayMode: A display mode ID representing the new startup mode.
depth: An index indicating the new startup depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.

Return Value

an IOReturn code.

Discussion

IOFramebuffer subclasses should implement this method to set the mode and depth to be used during boot and at startup, to reduce needed mode changes during boot when the display connection type is the same. If possible this mode should also be used by the OpenFirmware driver for the card.

unregisterInterrupt(void *)

Remove a callback previously installed by registerForInterruptType().

public

virtual IOReturn unregisterInterrupt(
    void *interruptRef );

Parameters

interruptRef: The interruptRef returned from the registerForInterruptType call that installed the interrupt.

Return Value

An IOReturn code.

Discussion

Remove a callback previously installed by registerForInterruptType().

unregisterInterrupt(void *, UInt32)

Enable or disable a callback previously installed by registerForInterruptType().

public

virtual IOReturn setInterruptState(
    void *interruptRef,
    UInt32 state );

Parameters

state: True or false to enable the callback.

Return Value

An IOReturn code.

Discussion

Enable or disable a callback previously installed by registerForInterruptType().

validateDetailedTiming

Reports whether a detailed timing is able to be programmed with the device.

public

virtual IOReturn validateDetailedTiming( 
    void *description,
    IOByteCount descripSize );

Parameters

description: A pointer to a IODetailedTimingInformationV2 structure. The driver should examine this description and change any fields that it cannot implement to reflect its closest possible implementation.
descripSize: sizeof(IODetailedTimingInformationV2)

Return Value

an IOReturn code. A return other than kIOReturnSuccess will prevent the system from installing the programmable mode.

Discussion

IOFramebuffer subclasses may implement programmable mode functionality where the OS is able to install modes described by a detailed timing into the driver.

Structs and Unions

ExpansionData

protected

struct ExpansionData {
};

Discussion

This structure will be used to expand the capablilties of this class in the future.

Member Data

reserved

protected

ExpansionData * reserved;

Discussion

Reserved for future use. (Internal use only)

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-12-19