The DisplayDriver base class provides unacclerated software rendering functions which can draw a line between two points, or Blit a bitmap into the video framebuffer. The VesaDriver class is a fully functional VESA 2.0 display driver, and is the default display driver which Syllable will attempt to use if no accelerated display driver can be found for the installed hardware. Most video drivers generally inherit from the DisplayDriver base class, but some may choose to inherit from the VesaDriver class. The VesaDriver provides additional VESA mode switching functions which may be used for certain hardware E.g. the Mach64 accelerated driver inherits from the VesaDriver in order to use the VESA mode switching functions for some chipsets.
The most basic video driver for any hardware must provide the following functions and methods.
Fire::Fire( void ); Fire::~Fire( void ); bool Fire::IsInitiated( void ) const; area_id Fire::Open( void ); int GetFramebufferOffset(); int Fire::GetScreenModeCount( void ); bool Fire::GetScreenModeDesc( int nIndex, os::screen_mode* psMode ); int Fire::SetScreenMode( os::screen_mode sMode ); extern "C" DisplayDriver* init_gfx_driver( void );
The last function in that list is not a C++ method, but instead a C style function. This function is called when the display driver is initialised. Most display drivers simply implement init_gfx_driver(); to create a new instance of their display driver class, and then do the actual hardware detection and initialisation in the class constructor. The constructor and destructor should be fairly obvious. Generally the constructor will probe for the video hardware using the usual pci_* functions. If supported hardware is found then generally the hardware must be initialised, although this is an internal function of the display driver and will differ between different video hardware. What your initialisation code must do however is create and remap an area over the video framebuffer. This area is returned to the appserver later in the initialisation process and is the only way in which the DisplayDriver base class can access the video framebuffer.
Unless your hardware has a functional VESA BIOS and you have inherited from the VesaDriver class, you will have to provide three methods which are used by the appserver to set the correct video mode. GetScreenModeCount(); should simply return the total number of valid screenmodes. GetScreenModeDesc(); returns a structure which contains the display mode information for the requested display mode. Finally, SetScreenMode(); is used to actually set the desired video mode. GetScreenModeCount(); & GetScreenModeDesc(); are generally implemented in a similiar maner in any display driver as they are hardware independent. SetScreenMode(); is obviously extremely hardware dependent, and how you implement this will depend on your hardware.
IsInitiated(); simply returns true if the driver was able to detect and initialise the video hardware, or false otherwise.
GetFramebufferOffset(); should almost always return 0.
The Open(); method is the last peice of the puzzle. All it does it is return the area ID of the previously created framebuffer area. The appserver can then find the video framebuffer base address from this area and use it to access the video framebuffer to perform drawing functions.
void Fire::LockBitmap( SrvBitmap* pcDstBitmap, SrvBitmap* pcSrcBitmap = NULL ); void Fire::UnlockBitmap( SrvBitmap* pcDstBitmap, SrvBitmap* pcSrcBitmap = NULL );
Both are called by the software rendering methods before/after they access any bitmap. A normal video driver will only have to implement the LockBitmap() method. An example:
Fire::LockBitmap( SrvBitmap* pcDstBitmap, SrvBitmap* pcSrcBitmap = NULL )
{
if( ( pcDstBitmap->m_bVideoMem == false && ( pcSrcBitmap == NULL || pcSrcBitmap->m_bVideoMem == false ) ) || m_bEngineDirty == false )
return;
// ... Lock hardware and call the WaitForIdle() method ...
m_bEngineDirty = false;
}
The m_bEngineDirty flag should be set in every hardware accelerated drawing method. The UnlockBitmap() method is only necessary if the hardware does not allow accesses to the framebuffer and accelerated drawing at the same time.
An accelerated video driver will also provide methods which override the DisplayDriver software rendering methods. There implementation is highly hardware dependent, but most drivers implement methods to accelerate Line drawing, rectangular Fills and Bitmap Blits. The methods are:
bool Fire::DrawLine( SrvBitmap* pcBitMap, const IRect& cClipRect, const IPoint& cPnt1, const IPoint& cPnt2, const Color32_s& sColor, int nMode ); bool Fire::FillRect( SrvBitmap* pcBitMap, const IRect& cRect, const Color32_s& sColor, int nMode ); bool Fire::BltBitmap( SrvBitmap* pcDstBitMap, SrvBitmap* pcSrcBitMap, IRect cSrcRect, IRect cDstRect, int nMode, int nAlpha );
All of these methods receive a pointer to a SrvBitmap class. This class is the internal bitmap which is being rendered too. SrvBitmaps can either be in video memory or user memory, depending on wether they are on screen or off screen. Generally, video hardware cannot perform rendering operations on memory which is not in its own video framebuffer, so you must first check to ensure that the bitmap you are rendering to exists in video memory[1]. If not, you should pass the rendering request down to your base class, which will use the software rendering methods in DisplayDriver.[2]
DrawLine(); and FillRect(); recieve Color information which indicates the color that the line or fill should be drawn in. You may need to convert the RGBA information contained in the Color32_s class to information which can be used by your video hardware, but this is hardware dependent.
All methods recieve the nMode argument, which indicates the drawing mode which should be used to perform the operation. This argument will specify DM_COPY (A stright drawing operation), DM_OVER (An alpha transparent "stamp" operation where the transparency is either "On" or "Off") or DM_BLEND (An alpha blending operation). DM_COPY and DM_BLEND operations are the most common, and you may choose not to support hardware accelerated DM_OVER and DM_BLEND operations. Generally, passing this drawing operations down to the DisplayDriver methods does not noticably slow down rendering[3].
BltBitmap(); has an alpha parameter but the hardware only has to care about it if it supports the DM_BLEND mode.
bool Fire::CreateVideoOverlay( const os::IPoint& cSize, const os::IRect& cDst, os::color_space eFormat, os::Color32_s sColorKey, area_id *pBuffer ); bool Fire::RecreateVideoOverlay( const os::IPoint& cSize, const os::IRect& cDst, os::color_space eFormat, area_id *pBuffer ); void Fire::DeleteVideoOverlay( area_id *pBuffer );
Unlike the rendering functions, these functions do not have a software implementation in the DisplayDriver class. Your video driver must either support Video Overlays or the user will not be able to use them at all.[4]
CreateVideoOverlay(); and DeleteVideoOverlay(); are self explanitory. RecreateVideoOverlay(); is used to resize a current Video Overlay or to change the current color space of a Video Overlay.
All of these functions will be highly hardware specific and the functionality is complex. You should refer to actual driver implementations of these methods if you wish to understand how they work.[5]
[2]: E.g: if( pcBitMap->m_bVideoMem == false ) { return( DisplayDriver::FillRect( pcBitMap, cRect, sColor ) ); }
If you support offscreen videomemory bitmaps then you also have to use the m_nVideoMemOffset and m_nBytesPerRow members!
[3]: The DisplayDriver class now also supports MMX accelerated functions on hardware which supports MMX. This generally provides quite fast software rendering on most systems.
[4]: Users can instead use the slower Bitmap rendering output provided by the Media Framework.
[5]: At the time of writing the Riva, GeForce, Radeon, Mach64, Intel and SiS drivers implement Video Overlays.
1.5.1