Contents  Device Contexts  Tracking  Paint Message  Closing Your  Application  Plotting Pixels  GDI Text Functions  Displaying Bitmaps  One Last Thing  Demo program  Printable version  Discuss this article  in the forums The Series  Beginning Windows  Programming  Using Resources  in Win32 Programs  Tracking Your  Window/Using GDI  Introduction  to DirectX  Palettes and Pixels  in DirectDraw  Bitmapped Graphics  in DirectDraw  Developing the  Game Structure  Basic Tile Engines  Adding Characters  Tips and Tricks

Plotting Pixels

At last! Plotting pixels with GDI is a cinch as long as you've got a display device context to work with. Remember, calling GetDC() does this for you. To plot a pixel, not surprisingly, you call SetPixel():

COLORREF SetPixel(
     HDC hdc,           // handle to device context
     int X,             // x-coordinate of pixel
     int Y,             // y-coordinate of pixel
     COLORREF crColor   // pixel color );

The return type is something we haven't encountered yet, a COLORREF. This is not a structure, but a 32-bit value in the form 0x00bbggrr, where bb is an 8-bit value for the blue component, gg is green, and rr is red. The high byte is unused and is always set to zero. Let's take a look at the parameters for SetPixel():

HDC hdc: This is a device context for your window that you should obtain with a call to GetDC(). You only need to call GetDC() once, and then you can use it for any number of these functions. Don't get a new DC every time you want to plot a pixel!

int X, Y: The x- and y-coordinates of the pixel. These are in client coordinates, meaning that (0, 0) represents the upper-left corner of your window's client area, not the upper-left corner of the screen.

COLORREF crColor: This is the color you want to set the pixel to. To do this, it's easiest to use the RGB() macro, which takes values for red, green, and blue -- in that order -- between 0 and 255. SetPixel() will choose the closest available color to the one you have specified.

If the function succeeds, the return value is the color that the pixel was set to. This may not always be exactly the COLORREF you pass if you're working in less than 24-bit color; Windows will choose the closest match. If the function fails, it returns -1. As an example, if you want to set the upper-left corner of your client area to white, you'd use the following call:

 SetPixel(hdc, 0, 0, RGB(255, 255, 255));

This call assumes you've gotten a display device context named hdc. Pretty easy, hey? There's one other way to do it that's just a tad faster. Here's the function:

BOOL SetPixelV(
     HDC hdc,           // handle to device context
     int X,             // x-coordinate of pixel
     int Y,             // y-coordinate of pixel
     COLORREF crColor   // new pixel color );

The parameters are all the same. The return value is simply TRUE or FALSE for success or failure. SetPixelV() is slightly faster since it doesn't need to return the actual color that was used to plot. You'll probably never even notice the difference, unless you're using it thousands of times per frame, but if you don't need the extra information SetPixel() provides, there's no reason not to take the slightly increased performance, right?

The only other thing you need to know about plotting pixels is how to read the value of a pixel that's already been plotted. It's no problem; a quick call to GetPixel() does the job for you:

COLORREF GetPixel(
     HDC hdc,   // handle to device context
     int XPos,  // x-coordinate of pixel
     int nYPos  // y-coordinate of pixel );

The return value is obviously the color of the pixel at the given coordinates. If the coordinates specified are outside the clipping region (the area represented by the device context), the return value is CLR_INVALID. The parameters are the same as for SetPixel(): a device context to use, and the coordinates to operate on. That's it for plotting pixels. Now let's have a look at GDI's text-rendering functions.

Next : GDI Text Functions