Driver Overview

Quickinfo about Dave2d Driver implementation

• interface and driver are pure ansi C
• code is fully reentrant
• all exports prefixed by d2_
• all files are prefixed by dave_
• all functions and types are entierly lowercase
• all macros are entierly uppercase
• all functions set an errorcode
• only a single include is necessary from the clientside (dave_driver.h)

Basic objects and principles

The driver allows direct access to all hardware features.  Functionality not directly supported by hardware is not offered (emulated) by the driver.

• basic object is called a device. all functions require a device pointer as first parameter (see <opendevice>)
• devices are assigned to a hardware unit before anything is rendered through them (see <inithw>)
• material settings like color, texture, blending etc.. are stored in a context
• shapes are rendered by Rendering Functions using the current context(s)
• rendering does not happen immediately but fills a renderbuffer (see Render Buffers)
• renderbuffers can be executed totally in parallel (without any cpu interaction)
• calling d2 functions from interrupt service routines is not recommended in general and must be done with care

Simple example of using the dave driver

Further information and examples can be found in the Driver Tutorial (software/tutorial/driver_tutorial.doc).

To create a device, allocate and initialize the hardware (errorchecks omitted for clarity) :

#include "dave_driver.h"

int main()
{
    void *framebuffer;

    // Use the default memory management functions and register a wrapper for the normal malloc, free and msize commands of the system.
    // Note: On some platforms a different memory manager for video and heap management may be required.
    // A different memory manager can be chosen by calling d0_initheapmanager(..) instead of d0_initdefaultheapmanager().

    d0_initdefaultheapmanager();              // initialize D/AVE driver memory management interface

    d2_device *handle = d2_opendevice( 0 );   // create a device
    d2_setdlistblocksize( handle, 25 );       // set blocksize for default displaylist
    d2_lowlocalmemmode( handle, 20, 10 );     // systems with low local CPU memory need this mode
    d2_inithw( handle, 0 );                   // bind the hardware

now we setup a 32bit 640x480 pixel framebuffer using the lowlevel driver

framebuffer = d1_allocvidmem(d2_level1interface(handle), d1_mem_display, 640*480*4);

// define address and memory organisation of framebuffer
d2_framebuffer( handle, framebuffer, 640, 640, 480, d2_mode_argb8888 );

using the default context we can directly start and setup our material attributes

d2_setcolor( handle, 0, 0xffffff );         // just simple white
d2_setblendmode( handle, d2_bm_alpha, d2_bm_one_minus_alpha );
d2_setalphamode( handle, d2_am_constant );
d2_setalpha( handle, 0x7f );                // 50% transparency
d2_setblur( handle, 4*16 );

the rendering happens inside an endless loop, as it is the case for most realtime animated graphics.  In order to avoid having to deal with renderbuffers manual, we use the utility functions startframe and endframe to get automatic buffer management.

d2_point x = 320*16;
d2_point y = 240*16;
//
while (1)
{
    d2_startframe( handle );
    d2_clear( handle, 0x000000 );               // clear the background

    d2_rendercircle( handle, x, y, 64*16, 0 );  // draw our circle

    d2_endframe( handle );

    x += 1;
    y += 8;
}