Source code libraries

Even if using DirectX is much more easy - especially for 3D rendering - than writing your own routines, there is still a bunch of things you have ever to do in DirectX apps. Also DirectX doesn't include high-level objects such as sprites... "dixu" is a set of source code libraries - to improve over time - that deals with DirectX routines such as initializing or clearing DirectX objects, loading bitmaps or sounds... On top of this library, a "sprite engine" would allow to write easyly sprites based applications... The design goal is *not* to hide any of DirectX features but to ease the ever done stuff...

I'll keep to enhance "dixu" with DirectX stuff. Regarding the Sprite part, I'll hope to be able to use DirectAnimation against a DirectDraw surface created with DirectX Fundation and perhaps to be then able to use the Sprite library (or also the Effect library) provided with IE4...

A DirectDraw sample : Donut

Download Donut source code (.ZIP)

Creating the VB Project

Once Visual Basic is started with a new project :

Initializing DirectX

It's time now to initialize DirectX. Select the form's code module. In the Form_Load event write the following code : 

dixuInit dixuInitFullScreen, Me, 320, 200, 16
That's all you need to initialize DirectDraw ! This app will run in full screen mode in a 320x200 pixels mode and with 65536 colors (16 bits per pixel).

Initializing a sprite

First, declare a Donut sprite at the module level : 
Dim Donut As dixuSprite
Then back in the Form_Load event, write the sprite initialization code : 

Set Donut = New dixuSprite
With Donut
    .Surface=dixuCreateSurfaceFromBitmap(App.Path & "\donut.bmp")
    .Height = 64
    .Width = 64
    .VelocityX = 5
    .VelocityY = 5
End With
The sprite is now ready !

The rendering loop

The rendering loop is simply : 

While Not blnEnd
    dixuBackBufferDraw
    DoEvents		' Enables events to be handled by Windows
Wend
' Clear objects and terminate
dixuDone
UnLoad Me
Note that the created sprite is automatically registered when created. The sprite is painted by the dixuBackBufferDraw sub...
To be able to quit you should also add the following code in the Form_KeyPress code : 

    blnEnd=True
To quit the app, just press any key... You should finally ends with the followin code : 

' Bouncing Donut demo : demonstrates the use of dixu.bas and sprite.cls

Option Explicit

Dim blnEnd As Boolean
Dim Donut As dixuSprite

Private Sub Form_Load()
    ' Initialize DirectX
    dixuInit dixuInitFullScreen, Me, 320, 200, 16
    ' Initialize a sprite
    Set Donut = New dixuSprite
    With Donut
        ' Loads the sprite bitmap
        .Surface = dixuCreateSurfaceFromBitmap(App.Path & "\donut.bmp")
        .Height = 64	' Height of a sprite image
        .Width = 64	' Width of a sprite image
        .VelocityX = 5	' Velocity in pixels/s along the X axis
        .VelocityY = 5	' Velocity in pixels/s along the Y axis
    End With
    While Not blnEnd
        dixuBackBufferDraw	' Clear the back buffer surface
        DoEvents
    Wend
    Set Donut = Nothing	' Clear the sprite
    dixuDone	' Clear DirectX object
    UnLoad Me
End Sub

Private Sub Form_Keypress
    blnEnd = True
End Sub

A Direct3D Retained Mode sample : Room

Download Room source code

The use of dixu for Direct3D Retained Mode apps is very similar to DirectDraw apps. You should refer to the Donut sample regarding the VB Project initialization. You may want also to refer to the sample for some more explanation about the following code. You will not be surprised if you already seen the donut code sample. The Form_Load event code is simply : 

Private Sub Form_Load()
    dixuInit dixuInitFullScreen Or dixuInit3DDevice, Me, 320, 200, 16
    SceneInit
    While Not dixuAppEnd
       dixuBackBufferDraw
       DoEvents
    Wend
    dixuDone
    Unload Me
End Sub

Private Sub Form_KeyPress()
    blnEnd = TrueEnd Sub
End Sub

Private Sub Form_KeyPress
    dixuCameraMove KeyCode
End Sub
Regarding dixu the only difference is the use of the dixuInit3DDevice flag ! You have also to initialize the 3D scene before beginning the rendering loop. This initialization code uses the top level Direct3D objects exposed by dixu such as dixuScene or dixuCamera. It is just regular DirectX code. Check the source code and the DirectX docs for more explanations... You may also want to check the Collision detection using Pick that explains some implementation details regarding dixu functions (such as collision detection for camera movements)...

dixu Library Reference

DIXU_NOSPRITE constant
If you define this constant to anything but 0, all parts relevant to the dixuSprite class in the dixu "core" library (needed to register and handle automatically sprites, see dixuFrameDraw) will not be compiled. This allow to leave the sprites relevant code in Direct3D Retained Mode apps. This constant must be declared in needed in the Project Properties within the Make tab. The syntax is :
DIXU_NOSPRITE=1 
dixuBackBuffer object
A DirectDrawSurface2 object used as a back buffer for DirectDraw apps. You should use this object when you want to draw custom drawings to the surface. For example you could use GetDC or Lock to gain direct access to the surface and perform custom operation... 
dixuBackBufferDraw
This sub performs automatically the following operations :

If dixuBackBufferClear has been called prior to the last dixuBackBufferDraw, the first step (clearing the dixuBackBuffer object) is not performed. This allow to add easily your own rendering code in the rendering loop :


dixuBackBufferClear
' Your own rendering code...
dixuBackBufferDraw ' As dixuBackBufferClear has been called the back buffer is not cleared...

Public Sub dixuCameraMove(ByVal KeyAscii As Long)
dixuClipper object
A DirectDrawClipper object used to manage windowed application. In most cases, you shoudn't have to use this object. 
dixuCreateSurfaceFromBitmap(FileName) function
Returns a new DirectDrawSurface2 object initialized with the specified bitmap file. 
dixuD3DRM object
A Direct3DRM object at top of the Direct3D Retained Mode hierarchy. This objects allows to create other objects and to control overall characteristics of 3D rendering. D3DRM.CreateMeshBuilder Cube will create a Direct3DRMMeshBuilder object... 
dixuD3DRMDevice
A Direct3DRMDevice used for 3D rendering. In most cases you shouldn't have to use this object. 
dixuD3DRMViewport
A Direct3DRMViewport object used for 3D rendering. In most cases you shouldn't have to use this object. 
dixuDone
Clears all DirectX objects and restore display mode. 
dixuInit Flags, frm, Width, Height, BitsPerPixel
This sub initializes all the DirectX objects for the specified display mode. As dixuInit don't destroy objects such as dixuScene and dixCamera, dixuInit could also be used to change the current display mode (for example from windowed to full screen) without loosing the current 3D scene... dixuInit initializes the following objects : In most apps, you should only need to use dixuBackBuffer, dixuCamera and dixuScene. 
dixuScene
A Direct3DRMFrame object used as a scene

dixuSprite class

Height
The height in pixels of each sprite image. 
Surface
A DirectDrawSurface2 object used as the source for the various sprite images. You can initialize this surface by using the dixuCreateSurfaceFromBitmap function. As this surface is exposed you could also use the regular DirectX methods (for example to set the color keys to achieve transparent blit). 
VelocityX
VelocityX is the velocity of the sprite along the X axis (in pixels/s). 
VelocityY
VelocityY is the velocity of the sprite along the Y axis (in pixels/s). 
Width
The width in pixels of each sprite image.
Copyright Patrice Scribe, 1997