Windows API Reference

GDI32 API Functions

The Graphics Device Interface (GDI) is a core Windows component that provides applications with a consistent way to interact with graphical output devices, such as display monitors and printers.

BitBlt

BOOL BitBlt( HDC hdcDest, int nXDest, int nYDest, int nWidth, int nHeight, HDC hdcSrc, int nXSrc, int nYSrc, DWORD dwRop );
Copies a block of pixels from the specified source device context to the specified destination device context.

Parameters

Name Type Description
hdcDest HDC A handle to the destination device context.
nXDest int The x-coordinate, in logical units, of the upper-left corner of the destination rectangle.
nYDest int The y-coordinate, in logical units, of the upper-left corner of the destination rectangle.
nWidth int The width, in logical units, of the rectangle to be copied.
nHeight int The height, in logical units, of the rectangle to be copied.
hdcSrc HDC A handle to the source device context.
nXSrc int The x-coordinate, in logical units, of the lower-left corner of the source rectangle.
nYSrc int The y-coordinate, in logical units, of the lower-left corner of the source rectangle.
dwRop DWORD The raster operation (ROP) code of the operation to be performed. This parameter can be a combination of raster operation codes.

Return Value

BOOL If the copy operation is successful, the return value is nonzero. If the copy operation fails, the return value is zero.

Remarks

This function performs a bit-block transfer of pixels. BitBlt can be used for drawing images, copying bitmaps between devices, and transforming images.

See Also

CreateCompatibleDC
SelectObject

CreateCompatibleBitmap

HBITMAP CreateCompatibleBitmap( HDC hdc, int nWidth, int nHeight );
Creates a bitmap that is compatible with the specified device.

Parameters

Name Type Description
hdc HDC A handle to the device context to which the bitmap is compatible.
nWidth int The width of the bitmap, in pixels.
nHeight int The height of the bitmap, in pixels.

Return Value

HBITMAP If the function succeeds, the return value is a handle to the newly created bitmap. If the function fails, the return value is NULL.

Remarks

A compatible bitmap is a bitmap that can be used interchangeably with bitmaps that belong to the specified device context. For example, you can use BitBlt to copy color information from a compatible bitmap to any memory device context or to a screen device context.

See Also

CreateCompatibleDC
CreateBitmap

CreateCompatibleDC

HDC CreateCompatibleDC( HDC hdc );
Creates a memory device context that is compatible with the specified device.

Parameters

Name Type Description
hdc HDC A handle to the device context with which the new memory device context will be compatible.

Return Value

HDC If the function succeeds, the return value is a handle to the memory device context. If the function fails, the return value is NULL.

Remarks

A memory device context is a portion of memory that can be used as a drawing surface. Memory device contexts are useful for drawing operations that are not immediately visible to the user, such as creating images off-screen before copying them to the screen.

See Also

BitBlt
CreateCompatibleBitmap
DeleteDC

CreateFont

H فونٹ 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 );
Creates a logical font with the specified characteristics.

Parameters

Name Type Description
nHeight int The desired height of the font, in logical units.
nWidth int The desired width of the font, in logical units.
nEscapement int The escapement of the font in tenths of a degree, measured clockwise from the escapement of the device.
nOrientation int The orientation of the font's characters in the output string, in tenths of a degree.
fnWeight int The desired boldness of the font.
fdwItalic DWORD The desired italic attribute.
fdwUnderline DWORD The desired underline attribute.
fdwStrikeOut DWORD The desired strikeout attribute.
fdwCharSet DWORD The desired character set.
fdwOutputPrecision DWORD The desired output precision.
fdwClipPrecision DWORD The desired clipping precision.
fdwQuality DWORD The desired output quality.
fdwPitchAndFamily DWORD The desired pitch and family of the font.
lpszFace LPCTSTR A pointer to a null-terminated string that contains the typeface name of the font.

Return Value

HFONT 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.

Remarks

To use the font, create a logical font with this function, select it into a device context by calling SelectObject, and then use the device context to draw text. After drawing, you should select the original font back into the device context and delete the font object using DeleteObject.

See Also

CreateFontIndirect
SelectObject
DeleteObject

CreateSolidBrush

HBRUSH CreateSolidBrush( COLORREF color );
Creates a solid brush that has the specified color.

Parameters

Name Type Description
color COLORREF The color of the brush. This parameter is an RGB value.

Return Value

HBRUSH If the function succeeds, the return value is a handle to the new solid brush. If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that the system uses to paint areas. Solid brushes are monochrome brushes that are filled with a single color.

See Also

CreateHatchBrush
CreatePatternBrush
SelectObject

DeleteDC

BOOL DeleteDC( HDC hdc );
Deletes a device context (DC).

Parameters

Name Type Description
hdc HDC A handle to the device context to be deleted.

Return Value

BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks

When you no longer need a device context, you should delete it to free up system resources. This function is typically used for memory device contexts created by functions like CreateCompatibleDC.

See Also

CreateCompatibleDC
DeleteObject

DeleteObject

BOOL DeleteObject( HGDIOBJ hObject );
Deletes a graphics device interface (GDI) object.

Parameters

Name Type Description
hObject HGDIOBJ A handle to the GDI object to be deleted. This parameter can be a handle to a bitmap, brush, font, palette, pen, or device context.

Return Value

BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks

When you no longer need a GDI object (such as a font, brush, or bitmap) created by functions like CreateFont or CreateSolidBrush, you should delete it to free system resources.

See Also

CreateFont
CreateSolidBrush
DeleteDC

Rectangle

BOOL Rectangle( HDC hdc, int nX1, int nY1, int nX2, int nY2 );
Draws a rectangle using the current pen.

Parameters

Name Type Description
hdc HDC A handle to the device context.
nX1 int The x-coordinate, in logical units, of the upper-left corner of the rectangle.
nY1 int The y-coordinate, in logical units, of the upper-left corner of the rectangle.
nX2 int The x-coordinate, in logical units, of the lower-right corner of the rectangle.
nY2 int The y-coordinate, in logical units, of the lower-right corner of the rectangle.

Return Value

BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks

This function draws a rectangle with the specified corners. The rectangle is outlined using the current pen and filled using the current brush. If you want only the outline, select a hollow brush into the DC before calling this function.

See Also

RoundRect
Ellipse

SelectObject

HGDIOBJ SelectObject( HDC hdc, HGDIOBJhObject );
Selects an object into the specified device context.

Parameters

Name Type Description
hdc HDC A handle to the device context.
hObject HGDIOBJ A handle to the GDI object (bitmap, brush, font, palette, or pen) to be selected.

Return Value

HGDIOBJ If the function succeeds, the return value is a handle to the previously selected object of the specified type. If the object was not replaced, the return value is the same as the handle passed in the hObject parameter. If the function fails, the return value is NULL.

Remarks

An application can select only one of each type of GDI object (bitmap, brush, font, palette, or pen) into a device context at any given time. To retain the original object, the application should save the handle returned by SelectObject and then reselect the original object into the device context before the device context is destroyed or the object is deleted.

See Also

CreateFont
CreateSolidBrush
DeleteObject

SetPixel

COLORREF SetPixel( HDC hdc, int X, int Y, COLORREF crColor );
Sets the pixel at the specified coordinates to the specified color.

Parameters

Name Type Description
hdc HDC A handle to the device context.
X int The x-coordinate, in logical units, of the pixel to set.
Y int The y-coordinate, in logical units, of the pixel to set.
crColor COLORREF The color to set. This parameter is an RGB value.

Return Value

COLORREF The return value is the RGB color value of the pixel that was set. If the coordinates are out of bounds, the return value is CLR_INVALID (-1).

Remarks

This function draws a single pixel. For drawing multiple pixels, consider using SetPixelV or GDI drawing functions like Rectangle.

See Also

GetPixel
SetPixelV

TextOut

BOOL TextOut( HDC hdc, int nXStart, int nYStart, LPCTSTR lpString, int cbString );
Writes a string of text at the specified location.

Parameters

Name Type Description
hdc HDC A handle to the device context.
nXStart int The x-coordinate, in logical units, of the starting position for the text.
nYStart int The y-coordinate, in logical units, of the starting position for the text.
lpString LPCTSTR A pointer to the string to be written.
cbString int The number of characters in the string.

Return Value

BOOL If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks

This function writes text using the currently selected font, background color, and foreground color.

See Also

CreateFont
SelectObject