DirectDraw: Drawing Primatives
By: Jack Hoxley
Written: May 2000
Download: DD_Primatives.Zip (10kb)

Although a lot of graphical work done in directdraw will stem from existing graphics and textures loaded into surfaces, there will always be a time when you need to use basic shapes and primatives; Directdraw currently has built in support for the following shapes:

1. Normal Rectangle (A rectangle can be a square)
2. Rounded Rectangle
3. Circle
4. Ellipse
5. Line

You can also apply different fill patterns and fill colours. An extremely useful, and often impressive method is to combine color keying with primatives. Color keying is not discussed in this tutorial, but if you do know (or learn) how to use them you can do some impresive things with the Destination color keys. When using a destination colour key, you define what colour you want to blit the image onto (such as full blue); before hand you could create a basic image using primatives, and then use a detination blit to only copy a texture to certain colours. This will be explained in greater depth in a later tutorial.

Primative 1: The Normal rectangle
A rectangle can also be a square, if it's height and width are the same then it's a square - which is why there isn't a seperate a method included for drawing squares.

Surface.DrawBox(x1 As Long, y1 As Long, x2 As Long, y2 As Long)

This is the function call for drawing a box. The parameters define the top-left and the bottom-right corners of the rectangle. Make sure that the coordinates that you are passing actually exist; ie. if you had a 640x480 screen, there is no point in passing an x of -1 as it doesn't exist, same with passing a value of 641. If you are finding that the shape you are drawing isn't appearing, one possible reason is that you are trying to draw outside the surface; Directdraw doesn't automatically clip the shape, if even one pixel is out-of-bounds then it will ignore the whole call - and not draw anything. Unless you set the surface to fill in the shape it will draw just the outline of the box (by default it doesn't fill shapes).

Primative 2: Rounded rectangle
The rounded rectangle is almost identical to the rectangle except that it softens the corner by adding a slight curve to them.

Surface.DrawRoundedBox(x1 As Long, y1 As Long, x2 As Long, y2 As Long, rw As Long, rh As Long)

The first four parameters are the same as for the rectangle (or box) method, only the end two are new. These last two values define the amount of curve on the corners, the first argument is the horizontal and the second the vertical. The more you increase these, the more of a curve you'll get - until it is so curved you either get an ellipse or a circle.

Primative 3: Circle
This is another simple primative, but it require a little more thought than the previous methods.

Surface.DrawCircle(x1 As Long, y1 As Long, r As Long)

Looks simple enough. The X and Y parameters are the central point of the circle and r is the radius. Still simple, but many people get mixed up as to what the variables mean. The slightly difficult part is remembering where to place it, as with all the other primatives you can't go outside the boundaries of a surface. If X1 was 100 and Y1 was 100, you could have R as a maximum of 100. If X1 was 70 and Y1 was 100 the largest you could have R would be 70. Despite what I said, it's still simple, but lots of people have had problems attempting this method.

Primative 4: Ellipse
An ellipse is similiar to a rectangle (or box).

Surface.DrawEllipse(x1 As Long, y1 As Long, x2 As Long, y2 As Long)

You pass the same variables to this function as you do to the DrawBox method. This time, Directdraw draws an ellipse within the boundaries that you've defined ( the top-left and bottom-right).

Primative 5: Line
This line is probably the simplest, but most useful primative. The line method can be used to create simple dividing lines, to simple user interfaces. One of the more graphically pleasing things it can be used for is gradients, in essence a gradient is lots of different coloured lines...

Surface.DrawLine(x1 As Long, y1 As Long, x2 As Long, y2 As Long)

The parameters passed to this function are identical to the Ellipse and Box methods, but the result is different. DirectDraw draws a line between the two X/Y cordinates you have passed to it - simple as that.

Setting the colour of your shape
So far there has been no mention of colour. This is probably the most important part of drawing primatives, as the whole idea behind graphics is presentation, controling the colour that the primatives are drawn in is very important.

Surface.SetForeColor(color As Long)

Very simple really. This value also affects what colour any text is drawn. The color as long part can simply be passed as an RGB value - using visual basic's built in function:
RGB(red,green,blue)
This will require a basic knowledge of how pixels are coloured, which can be quite complicated if you don't understand. Basically, each colour value is in the range 0 to 255, with 255 being full X colour, and 0 being none of X colour. Try these examples:

Backbuffer.SetForecolor RGB(0,0,0) 'Black
Backbuffer.SetForeColor RGB(255,255,255) 'White
Backbuffer.SetForeColor RGB(255,0,255) 'Magenta

Setting the fillstyle and fillcolor of your shape
The previous part only covers the outline of the shape, and will still leave you with the outline coloured. To make the shape filled in you need to do this:

Surface.SetFillStyle 0 'Default - Solid
Surface.SetFillStyle 1 'Transparent
Surface.SetFillStyle 2 'Horizontal Line
Surface.SetFillStyle 3 'Vertical Line
Surface.SetFillStyle 4 'Upward Diagonal
Surface.SetFillStyle 5 'Downward Diagonal
Surface.SetFillStyle 6 'Cross
Surface.SetFillStyle 7 'Diagonal Cross

Even though the above states that by default the shapes should be filled, it doesn't appear to be that way. The above list is directly from the DirectX SDK help file, In my experience, although "0" does fill the shape Directdraw by default doesn't apply any filling to a shape.

Now that you can fill the shape with a colour or pattern, you may want to change the colour that it fills the shape with. Use this function:

Surface.SetFillColor(color As Long)

This is similiar to the previous method for setting the foreground colour. The Color as long part can be substituted with the RGB(red,green,blue) call. Eg:
Backbuffer.SetFillColor RGB(255,255,255)

Now you know everything there is to know about drawing primatives on a directdraw surface. There is a sample application available to download from the top of the page, or on the download page