Mac Developer Library

Developer

IOFramebuffer Class Reference

Options
Deployment Target:

On This Page
Language:

IOFramebuffer

Inheritance


  • IOFramebuffer

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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

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.

  • Return display sense information for legacy Apple sensing.

    Declaration

    C++

    virtual IOReturn connectFlags( IOIndexconnectIndex, IODisplayModeIDdisplayMode, 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.

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

    Declaration

    C++

    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.

  • Carry out an I2C request.

    Declaration

    C++

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

    Parameters

    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. @timing event Subclasses may pass timing parameters tuned for the specific bus, otherwise if NULL, VESA DDC defaults will apply.

  • Perform first time setup of the framebuffer.

    Declaration

    C++

    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.

  • Perform any needed cache flushing after software cursor rendering.

    Declaration

    C++

    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.

  • Return reference to IODeviceMemory object representing memory range of framebuffer.

    Declaration

    C++

    virtual IODeviceMemory * getApertureRange( IOPixelApertureaperture ) = 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.

  • Return display sense information for legacy Apple sensing.

    Declaration

    C++

    virtual IOReturn getAppleSense( IOIndexconnectIndex, 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.

  • Generic method to retrieve some attribute of the framebuffer device.

    Declaration

    C++

    virtual IOReturn getAttribute( IOSelectattribute, uintptr_t *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.

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

    Declaration

    C++

    virtual IOReturn getAttributeForConnection( IOIndex connectIndex, IOSelect attribute, uintptr_t *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.

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

    Declaration

    C++

    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.

  • Return the framebuffers current display mode and depth.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Return display EDID data.

    Declaration

    C++

    virtual IOReturn getDDCBlock( IOIndexconnectIndex, UInt32blockNumber, IOSelectblockType, IOOptionBitsoptions, 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.

  • Return the number of display modes the framebuffer supports.

    Declaration

    C++

    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.

  • Return the number of display modes the framebuffer supports.

    Declaration

    C++

    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.

  • Return information about a given display mode.

    Declaration

    C++

    virtual IOReturn getInformationForDisplayMode( IODisplayModeIDdisplayMode, 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.

  • List the pixel formats the framebuffer supports.

    Declaration

    C++

    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.

  • Obsolete.

    Declaration

    C++

    virtual UInt64 getPixelFormatsForDisplayMode( IODisplayModeIDdisplayMode, IOIndexdepth ) = 0;

    Parameters

    displayMode

    Ignored.

    depth

    Ignored.

    Return Value

    Return zero.

    Discussion

    IOFramebuffer subclasses must implement this method to return zero.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Returns a timing description for a display mode.

    Declaration

    C++

    virtual IOReturn getTimingInfoForDisplayMode( IODisplayModeIDdisplayMode, 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.

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

    Declaration

    C++

    virtual IODeviceMemory * getVRAMRange( void );

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

  • Notify IOFramebuffer superclass code of events.

    Declaration

    C++

    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.

  • Return display DDC connect state.

    Declaration

    C++

    virtual bool hasDDCConnect( IOIndexconnectIndex );

    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()).

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

    Declaration

    C++

    virtual bool readDDCClock( IOIndexbus );

    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.

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

    Declaration

    C++

    virtual bool readDDCData( IOIndexbus );

    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.

  • Set callbacks for driver to call on interrupt events.

    Declaration

    C++

    virtual IOReturn registerForInterruptType( IOSelectinterruptType, IOFBInterruptProcproc, 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.

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

    Declaration

    C++

    virtual IOReturn setApertureEnable( IOPixelApertureaperture, IOOptionBitsenable );

    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.

  • Generic method to set some attribute of the framebuffer device.

    Declaration

    C++

    virtual IOReturn setAttribute( IOSelectattribute, uintptr_tvalue );

    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.

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

    Declaration

    C++

    virtual IOReturn setAttributeForConnection( IOIndex connectIndex, IOSelect attribute, uintptr_t 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.

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

    Declaration

    C++

    virtual IOReturn setCLUTWithEntries( IOColorEntry *colors, UInt32index, UInt32numEntries, IOOptionBitsoptions );

    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.

  • Set the framebuffers current display mode and depth.

    Declaration

    C++

    virtual IOReturn setDisplayMode( IODisplayModeIDdisplayMode, IOIndexdepth );

    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.

  • Set a new image for the hardware cursor.

    Declaration

    C++

    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.

  • Set a new position and visibility for the hardware cursor.

    Declaration

    C++

    virtual IOReturn setCursorState( SInt32x, SInt32y, boolvisible );

    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.

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

    Declaration

    C++

    virtual void setDDCClock( IOIndexbus, UInt32value );

    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.

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

    Declaration

    C++

    virtual void setDDCData( IOIndexbus, UInt32value );

    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.

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

    Declaration

    C++

    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.

  • Set the framebuffers current display mode and depth.

    Declaration

    C++

    virtual IOReturn setDisplayMode( IODisplayModeIDdisplayMode, IOIndexdepth );

    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.

  • Set the gamma table to be used by the framebuffer.

    Declaration

    C++

    virtual IOReturn setGammaTable( UInt32channelCount, UInt32dataCount, UInt32dataWidth, 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.

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

    Declaration

    C++

    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().

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

    Declaration

    C++

    virtual IOReturn setStartupDisplayMode( IODisplayModeIDdisplayMode, IOIndexdepth );

    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.

  • Remove a callback previously installed by registerForInterruptType().

    Declaration

    C++

    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().

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

    Declaration

    C++

    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().

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

    Declaration

    C++

    virtual IOReturn validateDetailedTiming( void *description, IOByteCountdescripSize );

    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.

Data Types

  • Declaration

    C++

    struct ExpansionData { };

    Discussion

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

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * reserved;