Chapter 5 - Miscellaneous unsorted new stuff

Microsoft did not provide a "PutPixel"-type function with DirectDraw to draw a pixel onto a DirectDraw surface. Granted, no real game is going to draw its graphics using a PutPixel routine, since it would be too slow - but it would have been nice to have such a "convenience function", and it could also be useful for testing out stuff. Some applications that might not necessarily need speed could also benefit from the convenience of a PutPixel routine. But, DirectX was not designed with convenience in mind.

Anyway, there are a number of ways to go about writing a PutPixel routine. One way would be to use GDI functions on the surface, using GetDC(). Another way is to use the IDirectDrawSurface::Blt() function, specifying a solid color operation with a 1x1 rectangle. A third way is to obtain a pointer to the memory representing the surface by calling IDirectDrawSurface::Lock(), and drawing the pixel in memory yourself. Each of these methods demonstrates general techniques whose usefulness goes beyond a simple PutPixel function.

2.1. PutPixel by surface locking

The basic technique here is to obtain a pointer to the memory representing the surface. You then calculate the offset into that memory for the coordinates of the pixel you wish to draw, and then you write the bytes representing the color of the pixel you want into that position in memory. There is nothing complex or difficult here, it's just a lot of grunt-work and jumping through hoops.

By default, you may not just write directly into the memory of a surface. You first have to obtain exclusive access to that surface, by "locking" it. This is done with a call to Lock().

HRESULT IDirectDrawSurface::Lock( LPRECT pRect, LPDDSURFACEDESC pDDSD, DWORD dwFlags, HANDLE hEvent );

pRect

Area of surface to lock. NULL locks entire surface.

pDDSD

Points to struct that describes the surface.

dwFlags

Control flags.

hEvent

Unused. Microsoft loves these unused parameters.

The pointer to the surface memory is one of the members of the DDSURFACEDESC structure, and is filled by the call to Lock() with a valid pointer. You may then write to this memory, and when you are finished with it you must call Unlock on that surface.

Now, to draw a pixel, you need to understand how pixels are represented in memory, which will depend on what color depth screen mode your surface is (see Chapter 2). Of course, if you create a "generic" PutPixel routine, that will work no matter what mode you are in, you will probably want to specify the color in some human-readable format, like an RGB triple. The PutPixel routine must then convert this, store it somewhere, and dump it to the surface memory. I use an unsigned int to temporarily store the pixel value. For convenience, I have created a CreateRGB function that can generate this unsigned int from supplied RGB values which range from 0 to 255:

/*--------------------------------------------------------------------------*/
// Create color from RGB triple
unsigned int CreateRGB( int r, int g, int b )
{
   unsigned int pixel;
   switch (g_iBpp)
   {
   case 8:
      // Here you should do a palette lookup to find the closest match.
      // I'm not going to bother with that. Many modern games no
      // longer support 256-color modes.
      break;
   case 16:
      // Break down r,g,b into 5-6-5 format.
      pixel = ((r/8)<<11) | ((g/4)<<5) | (b/8);
      break;
   case 24:
   case 32:
      pixel = (r<<16) | (g<<8) | (b);
      break;
   default:
      pixel =0;
   }
   return pixel;
}
/*--------------------------------------------------------------------------*/

Here is the actual PutPixel routine, taking as input a DirectDraw surface, an (x,y) location, and an RGB triple with r,g and b in the range 0 to 255. The function returns 0 for success. Notice the function, like CreateRGB, assumes the existence of g_iBpp, which I will explain in a bit.

/*--------------------------------------------------------------------------*/
int PutPixel( LPDIRECTDRAWSURFACE pDDS, int x, int y, int r, int g, int b )
{
   DDSURFACEDESC   ddsd;       // Surface description
   unsigned int    pixel;      // Store pixel to be dumped to screen
   int             offset;     // Store offset of destination memory location
   unsigned char * szSurface;  // Store pointer to surface
   HRESULT         hr;
   int             pixelwidth; // The width of a single pixel, in bytes

   // Initialize struct information
   ddsd.dwSize = sizeof(ddsd);

   // Calculate how the pixel is represented in memory
   pixel = CreateRGB( r, g, b );

   // Lock entire surface, wait if it is busy, return surface memory pointer
   hr = pDDS->Lock( NULL, &ddsd, DDLOCK_WAIT | DDLOCK_SURFACEMEMORYPTR, NULL );
   if (FAILED(hr))
      return -1;

   // Get surface memory pointer
   szSurface = (unsigned char*)ddsd.lpSurface;

   // Calculate the width of a pixel in bytes - this is how many bytes
   // we must write to the surface
   switch (g_iBpp)
   {
   case 16: pixelwidth = 2; break;
   case 24: pixelwidth = 3; break;
   case 32: pixelwidth = 4; break;
   default: pixelwidth = 1;
   }

   // Calculate memory offset
   // (Notice I use dwPitch instead of dwWidth - see Chapter 2)
   offset = (y*ddsd.lPitch + x*pixelwidth);

   // Copy pixel onto the surface, need string.h for this
   memcpy( szSurface + offset, &pixel, pixelwidth );

   // Unlock the surface. The parameter may be NULL if you locked the entire
   // surface, otherwise it must be a pointer to the DirectDraw surface memory.
   hr = pDDS->Unlock( NULL );
   if (FAILED(hr))
      return -2;

   return 0;
}
/*--------------------------------------------------------------------------*/

There are a few things worth mentioning about this function. Firstly, it can be optimized quite a lot, I know. But in a production game, this is not the function you will be using for all your drawing routines anyway. (One of the rules of optimization - never optimise what you don't need to.) Secondly, it makes some crass assumptions about your architecture - it may not work if your system is big endian. However, the Intel x86 is little endian, and as far as I know DirectX is only really available on the Intel x86. Thirdly, it only knows about a limited number of screen modes, and sometime in the future, when people start using video modes with higher bit depths (like 48), the code may no longer work. (However, as far as I can tell, DirectDraw itself may not be able to handle 48-bit color depths.) Anyway, the point is that to make the above PutPixel routine "correct" requires quite a bit more work still.

The g_iBpp in the code above is an integer representing the bits per pixel of the screen mode of the surface. You can get this from the DDSURFACEDESC.

Something else worth mentioning is that if the DirectDraw surface here is the primary surface - that is, it represents the entire screen, and you are in windowed mode and not in full-screen mode - then the pixel offsets here are relative to the top left of the screen, and not to your application window. You will find yourself drawing all over the screen, unless you work the offset of your window into your calculations (eg by using the ClientToScreen Win32 call or something.)

2.2. PutPixel by using IDirectDrawSurface::Blt

This routine is demonstrated in the supplied sample DDSamp.

This method also makes use of the CreateRGB function described in 5.1.1, so go read that part now if you have not done so yet.

This method is quite simple, and probably a bit "safer" than the method described in 5.1.1.

/*--------------------------------------------------------------------------*/
// PutPixel routine for a DirectDraw surface
void DDPutPixel( LPDIRECTDRAWSURFACE pDDS, int x, int y, int r, int g, int b )
{
   HRESULT hr;
   DDBLTFX ddbfx;
   RECT    rcDest;
   POINT   p;

   // Safety net
   if (g_pDDS == NULL)
      return;

   // Initialize the DDBLTFX structure with the pixel color
   ddbfx.dwSize = sizeof( ddbfx );
   ddbfx.dwFillColor = (DWORD)CreateRGB( r, g, b );

   // Prepare the destination rectangle as a 1x1 (1 pixel) rectangle
   p.x = x;
   p.y = y;
   ClientToScreen( g_hWnd, &p );
   OffsetRect( &rcDest, p.x, p.y );
   SetRect( &rcDest, p.x, p.y, p.x+1, p.y+1 );
   
   // Blit 1x1 rectangle using solid color op
   hr = g_pDDS->Blt( &rcDest, NULL, NULL, DDBLT_WAIT | DDBLT_COLORFILL, &ddbfx );
   if (FAILED(hr))
      OutputDebugString( (LPCTSTR)"Royal fuckup\n" );
}
/*--------------------------------------------------------------------------*/

All I've done here is:

• Create and set up a destination rectangle 1x1 pixels large
• Prepare the DDBLTFX structure with the solid color required
• Call Blt on the surface, specifying DDBLT_COLORFILL as the blit operation

That's about it.

Before you go running off locking every surface you see now, it must first be mentioned that there are some limitations to surface locking (what did you expect?) These are summarized from the DirectX help files.

• Never assume a constant display pitch - this can change for various reasons, so check the pitch before you do anything.
• Never blit to a locked surface. The call will fail, since the surface is "busy".
• Limit what you do while the surface is locked. This is important - Windows has a braindamaged mutex known as the Win16 lock, which lingers from the days of 16-bit Windows. While any thread holds this mutex, Windows is effectively dead, it cannot do anything. Even your debugger stops working while the Win16Lock is held. If an application crashes while holding this mutex, you have to press that ol' well-worn reset button. While a surface is locked, DirectDraw grabs this mutex (because the Win16Lock "serialises access to GDI and USER"). Calls to IDirectDrawSurface::GetDC and IDirectDrawSurface::ReleaseDC also implicitly call Lock and Unlock, so use those with caution as well.

Note that you can have multiple rectangles on a surface locked at the same time, so long as the rectangles don't overlap.

The DirectX documentation also makes the following warning which I don't fully understand *:

"Copy aligned to display memory. Windows 95 uses a page fault handler, Vflatd.386, to implement a virtual flat-frame buffer for display cards with bank-switched memory. The handler allows these display devices to present a linear frame buffer to DirectDraw. Copying unaligned to display memory can cause the system to suspend operations if the copy spans memory banks."