Windows User Interface Graphics API Reference
This section provides comprehensive documentation for the Windows API functions, structures, and interfaces used for graphics rendering and manipulation within the Windows operating system.
On this page
Graphics Overview
The Windows Graphics Device Interface (GDI) is a core component of the Windows operating system that provides a standardized way for applications to interact with graphics output devices such as displays and printers. GDI allows applications to draw lines, curves, text, shapes, and images in a device-independent manner.
Key concepts include:
- Device Context (DC): A handle to a structure that contains information about the drawing attributes of a particular output device.
- Graphical Objects: Pens, brushes, fonts, bitmaps, and regions used to define drawing characteristics.
- Drawing Functions: Functions that use graphical objects and a device context to render output.
Device Context (DC)
A device context is essential for any graphics operation. It holds all the information that GDI needs to draw on a specific device.
GetDC
HDC GetDC(HWND hWnd);
Retrieves a handle to a device context (DC) for the client area of a specified window or for the entire screen. The DC can be used to draw graphics and text.
CreateCompatibleDC
HDC CreateCompatibleDC(HDC hdc);
Creates a memory device context that is compatible with the specified device context. This is often used for off-screen drawing and bitmap manipulation.
ReleaseDC
int ReleaseDC(HWND hWnd, HDC hDC);
Releases a device context, freeing the system resources associated with it. It's crucial to call this function after you are finished with a DC obtained from GetDC.
Parameter: HDC
| Type | Description |
|---|---|
HDC |
A handle to the device context. If the function fails, the return value is NULL. |
Drawing Primitives
GDI provides functions to draw basic geometric shapes.
LineTo
BOOL LineTo(HDC hdc, int x, int y);
Draws a line from the current position in the specified device context to a specified point. The current position is updated to the end of the line.
Rectangle
BOOL Rectangle(HDC hdc, int x1, int y1, int x2, int y2);
Draws a rectangle using the current pen and fills it using the current brush. The rectangle is defined by the coordinates of its upper-left and lower-right corners.
Ellipse
BOOL Ellipse(HDC hdc, int x1, int y1, int x2, int y2);
Draws an ellipse that fits within the bounding rectangle defined by (x1, y1) and (x2, y2).
Bitmaps and Images
Manage and draw bitmap images.
LoadBitmap
HBITMAP LoadBitmap(HINSTANCE hInstance, LPCTSTR lpBitmapName);
Loads a bitmap resource from an executable file.
BitBlt
BOOL BitBlt(HDC hdcDest, int nXDest, int nYDest, int nWidth, int nHeight, HDC hdcSrc, int nXSrc, int nYSrc, DWORD dwRop);
Performs a bit-block transfer of the pixels from the source rectangle of a device context to a destination rectangle in another device context.
dwRop (Raster Operation) codes determine how the source and destination pixels are combined. Common values include SRCCOPY for simple copying.
Text Rendering
Display text within your application's graphics context.
TextOut
BOOL TextOut(HDC hdc, int nXStart, int nYStart, LPCTSTR lpString, int nCount);
Writes a specified number of characters starting at the specified x-coordinate and y-coordinate. The current text position is updated.
SetTextColor
COLORREF SetTextColor(HDC hdc, COLORREF color);
Sets the text color for the specified device context. COLORREF is a Windows type used to represent RGB colors.
SelectObject
HGDIOBJ SelectObject(HDC hdc, HGDIOBJ hgdiobj);
Selects a graphical object (like a font, pen, or brush) into a device context. This function returns the previously selected object of the same type, which should be saved and restored later.
To set a font for text rendering, you would first load or create a HFONT object, then use SelectObject to make it the active font in the DC.
Color Management
Understand and manipulate colors in GDI.
COLORREF
A 32-bit value used to specify an RGB color. It is typically formed by combining red, green, and blue color components. The macro RGB(r, g, b) is used to create a COLORREF value, where r, g, and b are integers from 0 to 255.
SetPixel
COLORREF SetPixel(HDC hdc, int x, int y, COLORREF color);
Sets the color of the specified pixel in the client area of a device context.
Advanced Graphics (GDI+)
For more advanced graphics capabilities, including anti-aliased rendering, gradients, and image manipulation, Windows provides GDI+.
While GDI provides foundational drawing capabilities, GDI+ offers a richer set of features for modern graphics applications. Key classes include:
Graphics: Represents the drawing surface.Pen: Defines how lines and curves are drawn.Brush: Defines how shapes are filled.Bitmap: Represents image data.
GDI+ functions are typically accessed through classes and objects rather than direct API calls like GDI, offering an object-oriented approach to graphics programming.
Example: Drawing with GDI+
#include <windows.h>
#include <gdiplus.h>
using namespace Gdiplus;
// ... inside your window's paint handler (e.g., WM_PAINT) ...
GdiplusStartupInput gdiplusStartupInput;
ULONG_PTR gdiplusToken;
GdiplusStartup(&gdiplusToken, &gdiplusStartupInput, NULL);
HDC hdc = GetDC(hWnd);
Graphics graphics(hdc);
// Create a pen and a brush
Pen redPen(Color(255, 255, 0, 0), 2); // Red pen, 2 pixels wide
SolidBrush blueBrush(Color(255, 0, 0, 255)); // Blue brush
// Draw a rectangle
graphics.DrawRectangle(&redPen, 10, 10, 100, 100);
graphics.FillRectangle(&blueBrush, 120, 10, 100, 100);
// Remember to shut down GDI+ when your application exits
// GdiplusShutdown(gdiplusToken);