The DirectDraw Helper

The following sections document the routines, variables and constants available in our DirectDraw helper module for Visual Basic. Use this module in conjunction with Patrice Scribes DirectX TLB's.

An updated version of this module is now available, allowing you to run windowed or fullscreen without changing any game code.
Click HERE for  details on how this works.

Changes :

Added windowed mode support
Added scaling feature
Convert ddInit mode/color consts to ENUMs

These routines must be used with DirectX 3.0 or higher. They were compiled and tested using DirectX 5.0

Interface Contents :

Inititalization Functions:

Surface Functions

Palette Functions

Global Variables

General Constants Available

Error codes ddBmpNotFound Couldn't find the requested bitmap
ddSurfaceFailed Failed to create the surface
BltFast flag shortcuts ddSrcColorKey DDBLTFAST_WAIT Or DDBLTFAST_SRCCOLORKEY
ddNoColorKey DDBLTFAST_WAIT Or DDBLTFAST_NOCOLORKEY
ddBltSprite ddSrcColorKey

Other constants available are described in the relevent section.

Function Descriptions

ddInit : Initialize the DirectDraw interface

Sub DDInit(Owner as Form, Res as Long, Mode as displayModes, Color as pixelFormats)

Use this routine as a general initialization routine. It initializes the DirectDraw interface, and stores it in the DDraw varible. It creates a primary (screen) surface, and attachs a back buffer to it.

Owner : Use the ME of your main form. This is the form that owns the DirectDraw session.

Res : Used to specify the screen resolution to use :

m320x200 Standard VGA
m320x240 ModeX
m640x400 640x400
m640x480 640x480
m800x600 800x600
m1024x768 1024x768

Mode : Selects between windowed or full screen modes :

Windowed Starts a windowed session in your main form
FullScreen Sets up a full screen session

Color : This is the color depth (bits per pixel) to use.

c256 256 colors (8 bpp)
c64000 65535 colors (16 bpp)
c16Million 16 Million colors (24 bpp)
c8Bit 8 BPP (256 colors)
c16Bit 16 BPP (65535 colors)
c24Bit 24 BPP (16 Million colors)


ddInitFullScreen : Initializes a 640x480 256 color DirectDraw mode

Sub DDInitFullScreen(Owner as Form)

This starts a 640x480 full screen DirectDraw session with 256 colors. This routine makes use of the ddInit sub-routine.

Owner : The ME of your main form. This is the form the owns the DirectDraw session.

ddInitTrueColor : Initializes a 640x480 24-bit DirectDraw mode

Sub DDInitTrueColor(Owner as Form)

This starts a 640x480 full screen DirectDraw session with 16 million (24-bit) colors.This routine makes use of the ddInit sub-routine.

Owner : The ME of your main form. This is the form the owns the DirectDraw session.

ddInitLowRes : Starts a 320x200 256 color (Standard VGA) mode

Sub DDInitLowRes(Owner as Form)

This starts a 320x200 full screen DirectDraw session with 256 colors. This is the standard VGA mode supported by all VGA cards. This routine makes use of the ddInit sub-routine.

Owner : The ME of your main form. This is the form the owns the DirectDraw session.

ddUnload : Shuts down the DirectDraw system

Sub DDUnload()

This ends your DirectDraw session and restores the GDI setting. This will not release any bitmaps you still have assigned to DirectDrawSurface variables. These must by physically released by you.

 

ddLoadBitmap : Loads a bitmap and returns a DirectDrawSurface

Sub ddLoadBitmap(bmpFile as String) as DirectDrawSurface2

Use this routine to load a bitmap from a file or out of a resource in your executable file. A surface is created, and the image is loaded onto it. The pixel in the top left corner, (0,0), is used as the transparent color (the source color key).

If the a bitmap file cannot be found, then it is assumed to be a resource identifier, and an attempt to load it from the resource is made. If this fails the call fails.

bmpFile : Contains the full path to the bitmap, or just the resource name if it is to be loaded from a resource

Returns Success : The bitmap surface (DirectDrawSurface2)
Returns Failure  :
Nothing

ddCreateSurface : Creates a DirectDrawSurface2

Sub ddCreateSurface(ByVal fW as Long, ByVal fH as Long) as DirectDrawSurface2

Creates an empty (black) surface. This could be done to be used later to save portions of another surface, to save GDI text output for blitting later, etc. In my experience, the maximum size for a surface is 1MB, i.e 1024x1024, or 2048x52, etc. No color key is set up.

fW : The width of the new surface.
fH : The height of the new surface.

Returns Success : The DirectDrawsSurface2 object
Returns Failure : Nothing

ddClearSurface : Clears a surface to black

Sub ddClearSurface(Surface as DirectDrawSurface2)

After this sub-routine has executed, the surface is entirely black.

Surface : A DirectDrawSurface2 which you want the clear.

ddSetColorKey : Sets the source color key of a surface

Sub ddSetColorKey(Surface as DirectDrawSurface2, ByVal Index as Long)

The source color key of the surface is set to Index. If you are using a 256 color
mode, then Index must be the palette index of the color you want for the transparent color. For 16 and 24 bit modes, Index is the RGB value of the transparent color.

Surface : The surface whose source color key you wish to set.
Index : The new color key value.

ddGetSurfaceSize : Returns the surface width and height

Sub ddGetSurfaceSize(Surface as DirectDrawSurface2, Width as Long, Height as Long)

On completion, Width is set to the width of the surface, and Height contains the surface Height. Note that the width returned is the actual width of the surface, not it pitch, i.e if a surface is created for a bitmap (see ddLoadBitmap) the width returned is the width of the bitmap.

Surface : The surface in question
Width : A long value to store the surface width
Height : A long value to store the surface height

ddBltFast : Blit an entire surface using BltFast

Sub ddBltFast(ByVal X as Integer, ByVal Y as Integer, Source as DirectDrawSurface2)

This routine will blit the entire source surface onto the BackBuffer surface using its BltFast method. It always uses the source color key, thus leacing transparent bits. As BltFast is used, any clippers you have attached are ignored. Currently, if source is larger than the BackBuffer surface, or if (X;Y) is specified so that Source overlaps the edges of BackBuffer, and automaton error will occur.

Use this routine to blit items like sprites, or fonts which need transparent bits.

working.gif (185 bytes)  The next version will clip source is necessary.

X : The X position on BackBuffer for the left hand corner
Y : The Y position on BackBuffer for the top corner
Source : The surface to be blitted.

ddBltFastNoColorKey : Blits an entire surface with no transparency

Sub ddBltFastNoColorKey(ByVal X as Integer, ByVal Y as Integer, Source as DirectDrawSurface2)

This routine will blit the entire source surface onto the BackBuffer surface using its BltFast method. It never uses any color key, so there is no transparency. As BltFast is used, any clippers you have attached are ignored. Currently, if source is larger than the BackBuffer surface, or if (X;Y) is specified so that Source overlaps the edges of BackBuffer, and automaton error will occur.

This routine is used for blitting items like splash screens, where no tranparency is required.

working.gif (185 bytes)  The next version will clip source is necessary.

X : The X position on BackBuffer for the left hand corner
Y : The Y position on BackBuffer for the top corner
Source : The surface to be blitted.

ddLoadPalette : Loads a palette from a palette file

Sub ddLoadPalette(palFile as String) as DirectDrawPalette

CONSTRUCTION2.GIF (2856 bytes)

This routnes has not yet been implemented. When it is complete, it will allow you to load a palette from a .PAL file, and returns a DirectDrawPalette object containing this palette.

ddUsePalette : Apply a bitmaps palette to the primary surface

Sub ddUsePalette(bmpFile as String) as DirectDrawPalette

The palette used by the bitmap is loaded, and the PrimarySurface's palette is set to match this palette. The loaded palette is also returned so you can save it for later use. This routine is currently limited to bitmaps in disk files, and won't work if specify a bitmap in the resource.

bmpFile : Full path of the bitmap to use.
Returns Success : A DirectDrawPalette object
Returns Failure : Nothing

DDraw : Main DirectDraw object

Public DDraw as DirectDraw2

This variable holds a DirectDraw object, and can be used to access all the methods in the DirectDraw2 Interface described in the SDK documentation

PrimarySurface : The display screen surface

Public PrimarySurface as DirectDrawSurface2

This surface represents the actual display screen. Any changes made to this surface are immediatly reflected in on the screen. This surface is always in video memory. It is always present.

BackBuffer : The screen buffer used to implement page flipping

Public BackBuffer as DirectDrawSurface2

This surface is attached to the primary surface, and is always present. Changes made to this surface are not immediatly visible. They only become visible when ddFlip is called, and its contents are represented on the primary surface. It will also always reside in video memory is there is enough. On any moderm (1MB+)
video card, a 640x480 256 color back buffer fits into video memory. When the back buffer won't go into vide memory, performance is considerably reduced.

ddTextColor : Color used by the GDI text routines

Public ddTextColor as Long

Defines the color used by the GDI text output methods. The default is white. To set the color, add the line:       ddTextColor = RGB(redValue, greenValue, blueValue)

ddTextBackground   : Color used as opaque color in GDI text output

Public ddTextBackground as Long

This is the color that is used as the background color for text when the ddTextMode is set to OPAQUE. It is ignored when the TRANSPARENT style is set. Assign a color as with ddTextColor.

ddTextMode : Opaque or transparent style

Public ddTextMode as Long

Defines how the text is drawn.

Opaque Draws text with a background color of  ddTextBackground color
Transparent Draws the text transparently over the surface

 

Back to DirectX Tutorial Back to DirectX Tutorial

fireline.gif (5182 bytes)

TN00018A.gif (1390 bytes) Return to Digital Zone Software Homepage

fireline.gif (5182 bytes)

Copyright © 1998 Digital Zone Software. All rights reserved.
Author: Mark Hewitt