SCI/FreeSCI/Graphics/Drivers

Document conversion incomplete. Work in progress.

Graphics drivers

Every FreeSCI graphics driver provides an individual implementation for one specific target platform, such as the X Window System. In order to work correctly, it needs to implement the interface outlined in src/include/gfx_driver.h and list itself in src/include/gfx_drivers.h. Drivers have some freedom in determining which features they want to provide and which they want to have emulated. These features are determined by flags contained in its variable capabilities.

Graphics drivers must provide at least five buffers: Both priority buffers, and the three visual buffers. They are grouped in three sets labelled the Front Buffer (only one visual buffer), the Back Buffer, and the Static Buffer (both containing both a priority and a visual buffer). Most graphical operations operate on the back buffer, with their results being propagated to the front buffer by means of explicit buffer operations.

Driver implementations with limited or no hardware accelleration support, such as those operating on plain frame buffers, may use some shared functionality exported for their benefit. Those functions are listed in the appropriate function definitions below.

Unless specified differently, each function must return GFX_OK on success, GFX_ERROR on failure, and GFX_FATAL if and only if a fatal and unrecoverable error occured, such as the target display being closed by external means.

Functions that receive color parameters must respect those parameters' mask values for GFX_MAP_MASK.

I/O and debug functionality

For basic input and output, the GFXDEBUG(), GFXWARN() and GFXERROR() macros defined in src/include/gfx_system.h can be used. Also, there is another variable, debug_flags defined for drivers; while it cannot be changed during runtime (yet), it may be used in combination with the various GFX_DEBUG_ constants to selectively enable and disable debugging for certain parts of the driver during development.

For further debugging, the FreeSCI functions sciprintf() (a printf clone), MEMTEST() (tries to detect heap corruption), and BREAKPOINT() (Sets a debugger breakpoint on Alpha, ia32 and SPARC) may be used.

Initialization and shutdown functionality

None of the functions defined in here are optional. They are called during startup or shutdown and need not be considered performance critical.

set_parameter(attribute, value)

This function is completely driver specific. Drivers may use it to allow external configuration of options not covered by the standard FreeSCI set of configuration options. It must be implemented to operate correctly both if init() has already been called and if it hasn't, although it may choose to ignore any options set afterwards.

Documentation of this function's options is up to the graphics driver's maintainer.

init_specific(xscale, yscale, bytespp)

Initializes a graphics driver to a pre-determined mode, where xscale and yscale are the requested horizontal and vertical scaling factors (integers > 0), and bytespp is the number of bytes per pixel on the target display.

The function may set a higher resolution, provided that no matching resolution is available. The mode structure (stored locally to the driver structure) must be set by this function if it succeeds; for this, the function gfx_new_mode(), defined in src/include/gfx_tools.h, may be used.

GFX_OK must be returned if the initialization succeeded; otherwise, GFX_ERROR must be reported, unless the graphics target is not (or no longer) able to provide any of the supported modes (e.g. if a required external module was not found, or if the driver detected during run-time that the target does not support any appropriate graphics mode).

init()

This operation initializes the driver's default graphics mode. Determining this mode is up to the graphics driver; if its target platform has no means for determining an appropriate mode, it may choose to invoke init_specific() repeatedly with educated guesses. It must return one of GFX_OK or GFX_FATAL.

See gfx-driver-init-specificSection [*] for details.

exit()

Deinitializes the graphics driver, frees all resources allocated by it and just generally performs clean-up. This function must succeed (so it does not have a return value). It may use gfx_free_mode() (from src/include/gfx_tools.h) to free the data allocated in the gfx_mode_t structure.

Primitive drawing operations

"Primitive drawing operations" here are operations that draw primitives. FreeSCI uses only two graphics primitives: Lines and solid boxes, both of which are commonly provided by graphics libraries. Both operations draw to the back buffer; they also must respect the priority aspect of the primary color used on them.

draw_line(line, color, line_mode, line_style)

Draws a single line. The line parameter describes the starting point and a relative coordinates of the line to draw in the specified color, whereas line_mode specifies the line mode to use. This value may be GFX_LINE_MODE_FAST, which means that the line's thickness is roughly about the average of the horizontal and vertical scaling factors. The other two values need not be supported (they should fall back to GFX_LINE_MODE_FAST if they're used'):

GFX_LINE_MODE_FAST

Line thickness is averate of x and y scale factors.

GFX_LINE_MODE_CORRECT

Lines are scaled separately for x and y and have correct widths there.

GFX_LINE_MODE_THIN

Line has a width of 1.

The other parameter, line_style, may be either of GFX_LINE_STYLE_NORMAL or GFX_LINE_STYLE_STIPPLED, although the latter is used iff the capability flag GFX_CAPABILITY_STIPPLED_LINES is set.

This function must return GFX_OK or GFX_FATAL.

draw_filled_rect(rect, color1, color2, shade_mode)