Graphics Device Interface (GDI) API

The Graphics Device Interface (GDI) is a core component of the Windows operating system that provides a device-independent way for applications to display graphics on various output devices. GDI handles everything from drawing basic shapes and text to rendering complex images and metafiles.

Drawing Primitives

GDI provides functions to draw fundamental graphical elements.

LineTo

Draws a line from the current position to a specified point.

Syntax
BOOL LineTo(HDC hdc, int x, int y);
Parameters
hdc: Handle to the device context.
x: The x-coordinate of the end point of the line.
y: The y-coordinate of the end point of the line.
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Rectangle

Draws a rectangle using the current pen and fills it with the current brush.

Syntax
BOOL Rectangle(HDC hdc, int x1, int y1, int x2, int y2);
Parameters
hdc: Handle to the device context.
x1: x-coordinate, in logical units, of the upper-left corner of the rectangle.
y1: y-coordinate, in logical units, of the upper-left corner of the rectangle.
x2: x-coordinate, in logical units, of the lower-right corner of the rectangle.
y2: y-coordinate, in logical units, of the lower-right corner of the rectangle.
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Ellipse

Draws an ellipse within the bounding rectangle specified by the coordinates, using the current pen and filled with the current brush.

Syntax
BOOL Ellipse(HDC hdc, int x1, int y1, int x2, int y2);
Parameters
hdc: Handle to the device context.
x1: x-coordinate, in logical units, of the upper-left corner of the bounding rectangle.
y1: y-coordinate, in logical units, of the upper-left corner of the bounding rectangle.
x2: x-coordinate, in logical units, of the lower-right corner of the bounding rectangle.
y2: y-coordinate, in logical units, of the lower-right corner of the bounding rectangle.
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Pens and Brushes

Pens are used for drawing lines and outlines, while brushes are used for filling areas.

CreatePen

Creates a new pen with the specified style, width, and color.

Syntax
HPEN CreatePen(int fnStyle, int nWidth, COLORREF crColor);
Parameters
fnStyle: The pen style. Can be one of `PS_SOLID`, `PS_DASH`, `PS_DOT`, `PS_DASHDOT`, `PS_DASHDOTDOT`, or `PS_NULL`.
nWidth: The width of the pen, in logical units. Must be 1 or greater.
crColor: The color of the pen. A `COLORREF` value.
Return Value
If the function succeeds, the return value is a handle to the newly created pen. If the function fails, the return value is `NULL`.

CreateSolidBrush

Creates a new brush with a solid color.

Syntax
HBRUSH CreateSolidBrush(COLORREF crColor);
Parameters
crColor: The color to be used for the solid brush. A `COLORREF` value.
Return Value
If the function succeeds, the return value is a handle to the newly created brush. If the function fails, the return value is `NULL`.

SelectObject

Selects an object (pen, brush, bitmap, font, region, or color palette) into the specified device context.

Syntax
HGDIOBJ SelectObject(HDC hdc, HGDIOBJ hgdiobj);
Parameters
hdc: Handle to the device context.
hgdiobj: Handle to the GDI object to be selected.
Return Value
If the function succeeds, the return value is a handle to the object previously selected into the device context. If the function fails, the return value is `NULL`.

DeleteObject

Deletes a logical GDI object (bitmap, brush, font, palette, pen, or region) from the system and revokes its handle.

Syntax
BOOL DeleteObject(HGDIOBJ hObject);
Parameters
hObject: Handle to the GDI object to be deleted.
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Fonts

GDI allows applications to use a variety of fonts for displaying text.

CreateFont

Creates a logical font with the specified characteristics.

Syntax
HFONT CreateFont(int nHeight, int nWidth, int nEscapement, int nOrientation, int fnWeight, DWORD fdwItalic, DWORD fdwUnderline, DWORD fdwStrikeOut, DWORD fdwCharSet, DWORD fdwOutputPrecision, DWORD fdwClipPrecision, DWORD fdwQuality, DWORD fdwPitchAndFamily, LPCTSTR lpszFace);
Parameters
nHeight: The desired height of the font, in logical units.
nWidth: The desired average width of characters in the font, in logical units.
lpszFace: Pointer to a null-terminated string that specifies the typeface name of the font.
...
(For a full list of parameters, please refer to the detailed API documentation)
Return Value
If the function succeeds, the return value is a handle to the newly created logical font. If the function fails, the return value is `NULL`.

TextOut

Writes a string of characters at the specified coordinates.

Syntax
BOOL TextOut(HDC hdc, int x, int y, LPCTSTR lpString, int nCount);
Parameters
hdc: Handle to the device context.
x: The x-coordinate, in logical units, of the starting position for the string.
y: The y-coordinate, in logical units, of the starting position for the string.
lpString: Pointer to the string to be drawn.
nCount: The number of characters to draw.
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Bitmaps

GDI supports the manipulation and display of bitmap images.

CreateCompatibleBitmap

Creates a bitmap that is compatible with the specified device context.

Syntax
HBITMAP CreateCompatibleBitmap(HDC hdc, int nWidth, int nHeight);
Parameters
hdc: Handle to the device context with which the bitmap is to be compatible.
nWidth: The width, in pixels, of the bitmap.
nHeight: The height, in pixels, of the bitmap.
Return Value
If the function succeeds, the return value is a handle to the newly created bitmap. If the function fails, the return value is `NULL`.

BitBlt

Performs a bit-block transfer of the color data for a specified rectangle from the source device context to a destination device context.

Syntax
BOOL BitBlt(HDC hdcDest, int nXDest, int nYDest, int nWidth, int nHeight, HDC hdcSrc, int nXSrc, int nYSrc, DWORD dwRop);
Parameters
hdcDest: Handle to the destination device context.
nXDest: The x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
nXSrc: The x-coordinate, in logical units, of the upper-left corner of the source rectangle.
dwRop: The raster-operation code.
...
(For a full list of parameters, please refer to the detailed API documentation)
Return Value
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Device Contexts

Device contexts (DCs) are structures that store the attributes of drawing devices. All drawing operations are performed on a device context.

GetDC

Retrieves a handle to a device context (DC) for the client area of a specified window or for the entire screen.

Syntax
HDC GetDC(HWND hWnd);
Parameters
hWnd: Handle to the window with which the device context is to be associated. If this parameter is `NULL`, `GetDC` retrieves a DC for the entire screen.
Return Value
If the function succeeds, the return value is a handle to the device context for the specified window or screen. If the function fails, the return value is `NULL`.

ReleaseDC

Releases a device context (DC), freeing the memory GDI uses to store characterizations of the DC.

Syntax
int ReleaseDC(HWND hWnd, HDC hdc);
Parameters
hWnd: Handle to the window whose DC is to be released.
hdc: Handle to the device context to be released.
Return Value
The return value indicates whether the DC was released. It is 1 if the DC was released; it is 0 otherwise.