Driver device management and hardware initialization / shutdown.
| Basic Functions | Driver device management and hardware initialization / shutdown. |
| Static functions | |
| Device management | |
| d2_getversionstring | Query versionID string (device independent) |
| d2_getversion | Query versionID (device independent) |
| d2_opendevice | Create a new device handle. |
| d2_closedevice | Destroy a device handle. |
| d2_geterror | Query device error information. |
| d2_geterrorstring | Query detailed device error information. |
| d2_inithw | Initialize hardware for working with specified device. |
| d2_deinithw | Unlink hardware currently bound by specified device. |
| d2_inithwburstlengthlimit | Set the maximum burst lenght of the master bus interfaces. |
| d2_level1interface | Get the lowlevel device handle currently used by the d2_device. |
| d2_getrevisionhw | Query hw revisionID. |
| d2_getrevisionstringhw | Query hw revisionID string. |
| d2_lowlocalmemmode | Enable and configure the ‘low localmem’ mode. |
| Rendering Mode | |
| d2_selectrendermode | Select a rendering mode. |
| d2_getrendermode | Get the rendering mode. |
| d2_layermerge | Join outline and solid parts of currently selected renderbuffer. |
| d2_outlinewidth | Define the width of geometry outlines. |
| d2_shadowoffset | Define the offset of geometry shadows. |
| Utility Functions | |
| d2_flushframe | Wait for current rendering to end. |
| d2_setdlistblocksize | Set blocksize for default displaylists. |
| d2_getdlistblocksize | Get blocksize of default displaylist. |
| d2_getdlistblockcount | Get number of blocks of default displaylist (writelist). |
| d2_commandspending | Check if there are pending commands in the current displaylist. |
d2_device * d2_opendevice( d2_u32 flags )
Create a new device handle.
A device is the basic software object. It contains references to objects that the drawing engine requires, (e.g.: displaylists). All 2D drawing functions require such a device pointer as first parameter.
A device on its own is useless, unless bound to a physical hardware (i.e.: Drawing Engine). The binding is done by the function d2_inithw. A hardware instance can only be mapped to one device object. It is not possible to share a single device pointer between different processes.
Creating a device will never fail (sufficient memory assumed) but binding it to a hardware (see: d2_inithw) can fail.
| flags | a bitfield containing flags |
| d2_df_no_dlist | don’t use a display list (slower single command mode) |
| d2_df_no_irq | don’t use an interrupt (slower polling used instead) |
| d2_df_no_fbcache | disable framebuffer cache (attention: see note below) |
| d2_df_no_texcache | disable texture cache (attention: see note below) |
| d2_df_no_dwclear | disable double word clearing in d2_clear |
| d2_df_no_registercaching | don’t use register caching |
| d2_df_no_blitctxbackup | don’t backup context data at blit for better performance; previous texture modes get lost and must be set again |
Flags ‘d2_df_no_fbcache’ and ‘d2_df_no_texcache’ should only be used for debugging purposes. Especially when multithreading is used, these flags must not be set different for devices which are bound to the same hardware instance through d2_inithw.
device pointer or NULL if not enough memory was available
d2_s32 d2_closedevice( d2_device * handle )
Destroy a device handle.
All contexts associated with the device are destroyed as well.
| handle | device pointer (see: d2_opendevice) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_geterror( const d2_device * handle )
Query device error information.
See list of all Errorcodes for more details.
| handle | device pointer (see: d2_opendevice) |
integer error code (0 is no error)
const d2_char * d2_geterrorstring( const d2_device * handle )
Query detailed device error information.
See list of all Errorcodes for more details.
| handle | device pointer (see: d2_opendevice) |
string with human readable error description, or 0 if an error occurs
d2_s32 d2_inithw( d2_device * handle, d2_u32 flags )
Initialize hardware for working with specified device. After creation a device is ‘bound’ to a hardware instance by calling inithw for this device. A single device cannot work with multiple hardware units.
| handle | device pointer (see: d2_opendevice) |
| flags | hardware instance id (use 0 for default) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_deinithw( d2_device * handle )
Unlink hardware currently bound by specified device. Hardware must be deinitialized before it can be reinitalized for another device.
| handle | device pointer (see: d2_opendevice) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_inithwburstlengthlimit( d2_device * handle, d2_busburstlength burstlengthFBread, d2_busburstlength burstlengthFBwrite, d2_busburstlength burstlengthTX, d2_busburstlength burstlengthDL )
Set the maximum burst lenght of the master bus interfaces. Changing the burst length limit should be done only when Dave completely is in idle mode and all bus transfers are finished.
| handle | device pointer (see: d2_opendevice) |
| burstlengthFBread | max burst length of framebuffer read interface |
| burstlengthFBwrite | max burst length of framebuffer write interface |
| burstlengthTX | max burst length of texture cache read interface |
| burstlengthDL | max burst length of displaylist read interface |
| d2_bbl_1 | single cycle bus access |
| d2_bbl_2 | max bus burst length = 2 |
| d2_bbl_4 | max bus burst length = 4 |
| d2_bbl_8 | max bus burst length = 8 |
| d2_bbl_16 | max bus burst length = 16 |
| d2_bbl_32 | max bus burst length = 32 |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d1_device * d2_level1interface( const d2_device * handle )
Get the lowlevel device handle currently used by the d2_device. This is necessary e.g. for allocating framebuffers using the lowlevel (d1_) interface.
| handle | device pointer (see: d2_opendevice) |
handle for lowlevel device, or NULL if an error occurs
d2_u32 d2_getrevisionhw( const d2_device * handle )
Query hw revisionID. This information is available after calling d2_inithw.
| handle | device pointer (see: d2_opendevice) |
HW Revision ID
| Bit[7..0] | revision number |
| Bit[11..8] | branch number |
| Bit[15..12] | D/AVE Type |
| Bit[20..16] | Features |
| 0 | D/AVE2DT-S |
| 1 | D/AVE2DT-L |
| Bit[16] | D2FB_SWDAVE (Software D/AVE) |
| Bit[17] | D2FB_DLR (DisplayListReader available) |
| Bit[18] | D2FB_FBCACHE (Framebuffer Cache available) |
| Bit[19] | D2FB_TXCACHE (Texture Cache available) |
| Bit[20] | D2FB_PERFCOUNT (Two performance counters available) |
| Bit[21] | D2FB_TEXCLUT (Color Lookup Table for ai44 format) |
| Bit[22] | D2FB_FBPREFETCH (frame buffer cache prefetch available) |
| Bit[23] | D2FB_RLEUNIT (RLE unit available) |
| Bit[24] | D2FB_TEXCLUT256 (256 entry CLUT available) |
| Bit[25] | D2FB_COLORKEY (color keying available) |
| Bit[26] | D2FB_HILIMITERPRECISION (limiter high precision mode available) |
| Bit[27] | D2FB_ALPHACHANNELBLENDING (alpha channel blending available) |
const d2_char * d2_getrevisionstringhw( const d2_device * handle )
Query hw revisionID string. This information is available after calling d2_inithw.
| handle | device pointer (see: d2_opendevice) |
human readable hw revision string, or 0 if an error occurs (e.g. “D/AVE 2DT-S, Revision 1.05, Features: DLR FBCACHE”).
d2_s32 d2_lowlocalmemmode( d2_device * handle, d2_u32 dlistblockfactor, d2_u32 dlistblocks )
Enable and configure the ‘low localmem’ mode.
On systems with low local CPU memory, the display lists can not be completely assembled in the local memory. A special mode is used in this case, which assembles small display list blocks in the local memory and copies them to the video memory, where they are concatenated to larger blocks. In order to use this mode it is necessary to call d2_lowlocalmemmode directly after d2_opendevice and before d2_inithw.
Querying the number of effectively used display list blocks can be done using d2_getdlistblockcount, which gives the number of display list blocks used so far (in units of the local display list block size). The application developer must take care that the maximum display list size configured using d2_lowlocalmemmode is sufficient.
| handle | device pointer (see: d2_opendevice) |
| dlistblockfactor | size of a dlist block in vidmem is this factor * local size (configurable using d2_setdlistblocksize) |
| dlistblocks | maximum number of dlist blocks in vidmem |
errorcode (D2_OK if successful) see list of Errorcodes for details
d2_s32 d2_selectrendermode( d2_device * handle, d2_u32 mode )
Select a rendering mode. Dave can automatically generate and render geometry outlines and shadows. A different rendering context is used for interior (solid context) and addons (outline context) so that both parts can have entirely different materials.
Note that primitives which are issued while rendermode ‘postprocess’ is active are buffered and put into the commandlist after all normal commands. Combined rendermodes like ‘solid_outlined’ and ‘solid_shadow’ internally use postprocessing to sort solid and outline parts.
| handle | device pointer (see: d2_opendevice) |
| mode | rendering mode |
| d2_rm_solid | Direct rendering of primitives (default mode) |
| d2_rm_outline | Only outlines are rendered |
| d2_rm_solid_outlined | Interior and outlines are rendered |
| d2_rm_shadow | Only shadows are rendered |
| d2_rm_solid_shadow | Interior and shadows are rendered |
| d2_rm_postprocess | Direct rendering of primitives as a postprocess |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_u32 d2_getrendermode( const d2_device * handle )
Get the rendering mode. This function can be used to get the rendering mode used for a specified d2_device.
| handle | device pointer (see: d2_opendevice) |
| d2_rm_solid | Direct rendering of primitives (default mode) |
| d2_rm_outline | Only outlines are rendered |
| d2_rm_solid_outlined | Interior and outlines are rendered |
| d2_rm_shadow | Only shadows are rendered |
| d2_rm_solid_shadow | Interior and shadows are rendered |
| d2_rm_postprocess | Direct rendering of primitives as a postprocess |
integer specifying the rendering mode, or 0 if an error occurs
d2_s32 d2_layermerge( d2_device * handle )
Join outline and solid parts of currently selected renderbuffer. When using rendermode d2_rm_postprocess (see: d2_selectrendermode) the postprocess buffer can be flushed using a call to d2_layermerge.
| handle | device pointer (see: d2_opendevice) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_outlinewidth( d2_device * handle, d2_width width )
Define the width of geometry outlines. Used only when using outline or solid_outlined rendering modes.
| handle | device pointer (see: d2_opendevice) |
| width | outline width in pixels (fixedpoint) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_shadowoffset( d2_device * handle, d2_point x, d2_point y )
Define the offset of geometry shadows. Used only when using shadow or solid_shadow rendering modes.
| handle | device pointer (see: d2_opendevice) |
| x | x axis offset in pixels (fixedpoint) |
| y | y axis offset in pixels (fixedpoint) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_flushframe( d2_device * handle )
Wait for current rendering to end.
Function will not return until the hardware has finished executing all currently active rendering operations. Note that no rendering operations are started until a renderbuffer is executed. (See Render Buffers)
| handle | device pointer (see: d2_opendevice) |
errorcode (D2_OK if successfull) see list of Errorcodes for details
d2_s32 d2_setdlistblocksize( d2_device * handle, d2_u32 size )
Set blocksize for default displaylists.
Sets the number of displaylist entries per block (aka page). The value given is effectively used for internal calls to d2_newrenderbuffer as both ‘initialsize’ and ‘stepsize’. For hints on how to optimize this size see documentation of d2_newrenderbuffer.
The default blocksize is: 204
| handle | device pointer (see: d2_opendevice) |
| size | number of displaylist entries per block (minimum is 3) |
errorcode (D2_OK if successful) see list of Errorcodes for details
The minimum number of displaylist entries per block is 3. This limitation is required to terminate a list correctly, there must be enough space to insert a dlist jump and a special termination entry.
d2_u32 d2_getdlistblocksize( const d2_device * handle )
Get blocksize of default displaylist.
Function will return the number of displaylist entries per block
| handle | device pointer (see: d2_opendevice) |
number of displaylist entries per block, or 0 if an error occurs
d2_u32 d2_getdlistblockcount( d2_device * handle )
Get number of blocks of default displaylist (writelist).
Function will return the number of used blocks for current displaylist
| handle | device pointer (see: d2_opendevice) |
number of used blocks
d2_s32 d2_commandspending( d2_device * handle )
Check if there are pending commands in the current displaylist.
| handle | device pointer (see: d2_opendevice) |
boolean value: true when there are commands pending, also 0 if an error occurs
Query versionID string (device independent)
const d2_char * d2_getversionstring( void )
Query versionID (device independent)
d2_s32 d2_getversion( void )
Create a new device handle.
d2_device * d2_opendevice( d2_u32 flags )
Destroy a device handle.
d2_s32 d2_closedevice( d2_device * handle )
Query device error information.
d2_s32 d2_geterror( const d2_device * handle )
Query detailed device error information.
const d2_char * d2_geterrorstring( const d2_device * handle )
Initialize hardware for working with specified device.
d2_s32 d2_inithw( d2_device * handle, d2_u32 flags )
Unlink hardware currently bound by specified device.
d2_s32 d2_deinithw( d2_device * handle )
Set the maximum burst lenght of the master bus interfaces.
d2_s32 d2_inithwburstlengthlimit( d2_device * handle, d2_busburstlength burstlengthFBread, d2_busburstlength burstlengthFBwrite, d2_busburstlength burstlengthTX, d2_busburstlength burstlengthDL )
Get the lowlevel device handle currently used by the d2_device.
d1_device * d2_level1interface( const d2_device * handle )
Query hw revisionID.
d2_u32 d2_getrevisionhw( const d2_device * handle )
Query hw revisionID string.
const d2_char * d2_getrevisionstringhw( const d2_device * handle )
Enable and configure the ‘low localmem’ mode.
d2_s32 d2_lowlocalmemmode( d2_device * handle, d2_u32 dlistblockfactor, d2_u32 dlistblocks )
Select a rendering mode.
d2_s32 d2_selectrendermode( d2_device * handle, d2_u32 mode )
Get the rendering mode.
d2_u32 d2_getrendermode( const d2_device * handle )
Join outline and solid parts of currently selected renderbuffer.
d2_s32 d2_layermerge( d2_device * handle )
Define the width of geometry outlines.
d2_s32 d2_outlinewidth( d2_device * handle, d2_width width )
Define the offset of geometry shadows.
d2_s32 d2_shadowoffset( d2_device * handle, d2_point x, d2_point y )
Wait for current rendering to end.
d2_s32 d2_flushframe( d2_device * handle )
Set blocksize for default displaylists.
d2_s32 d2_setdlistblocksize( d2_device * handle, d2_u32 size )
Get blocksize of default displaylist.
d2_u32 d2_getdlistblocksize( const d2_device * handle )
Get number of blocks of default displaylist (writelist).
d2_u32 d2_getdlistblockcount( d2_device * handle )
Check if there are pending commands in the current displaylist.
d2_s32 d2_commandspending( d2_device * handle )
Create a new renderbuffer.
d2_renderbuffer * d2_newrenderbuffer( d2_device * handle, d2_u32 initialsize, d2_u32 stepsize )