DC means Device Context, just like Graphics Context (GC) of X Lib. DC represents a rectangle area on the actual screen or a virtual screen created in memory. We call the rectangle area as "surface" of the DC. More...

Macros
#define	HDC_SCREEN ((HDC)0)
	Handle to the device context of the whole screen or the fake screen when MiniGUI is running under MiniGUI-Processes with compositing schema. More...

#define	HDC_INVALID ((HDC)-1)
	Indicates an invalid handle to device context. More...

#define	CreateCompatibleDC(hdc) CreateCompatibleDCEx(hdc, 0, 0)
	Creates a memory DC which is compatible with a given DC. More...

#define	DeleteCompatibleDC(hdc) DeleteMemDC(hdc)
	Deletes a memory DC. More...

Typedefs
typedef void(*	CB_DIRECT_DRAW_RECT) (HDC hdc, Uint8 pixels, int pitch, int bytesPerPixel, const RECT rc, void *context)
	Type of directly access pixels hook function. More...

typedef int(*	ON_UPDATE_SECONDARYDC) (HWND hwnd, HDC secondary_dc, HDC real_dc, const RECT secondary_rc, const RECT real_rc, const RECT *main_update_rc)
	The callback type of on updating secondary DC. More...

Functions
MG_EXPORT Uint32 GUIAPI	GetGDCapability (HDC hdc, int iItem)
	Returns a capability of a DC. More...

MG_EXPORT HDC GUIAPI	GetDCEx (HWND hWnd, BOOL bClient)
	Get a window or client DC of a window. More...

static HDC GUIAPI	GetDC (HWND hWnd)
	Get a window DC of a window. More...

static HDC GUIAPI	GetClientDC (HWND hWnd)
	Get a client DC of a window. More...

MG_EXPORT HDC GUIAPI	GetSubDC (HDC hdc, int off_x, int off_y, int width, int height)
	This function gets a sub DC which is compliant to the specified client DC. More...

MG_EXPORT void GUIAPI	ReleaseDC (HDC hdc)
	Releases a DC from DC pool. More...

MG_EXPORT HWND GUIAPI	WindowFromDC (HDC hdc)
	Get the window handle from DC. More...

MG_EXPORT int GUIAPI	SaveDC (HDC hdc)
	Saves the current state of a device context. More...

MG_EXPORT BOOL GUIAPI	RestoreDC (HDC hdc, int saved_dc)
	Restores a device context (DC) to the specified state. More...

MG_EXPORT HDC GUIAPI	CreateCompatibleDCEx (HDC hdc, int width, int height)
	Creates a memory DC which is compatible with the specified reference DC. More...

MG_EXPORT BOOL GUIAPI	IsCompatibleDC (HDC hdc1, HDC hdc2)
	Check whether a given DC is compliant to a specific DC. More...

MG_EXPORT BOOL GUIAPI	IsMemDC (HDC hdc)
	Check whether a given DC is a memory DC. More...

MG_EXPORT BOOL GUIAPI	IsScreenDC (HDC hdc)
	Check whether a given DC is a screen DC. More...

MG_EXPORT BOOL GUIAPI	IsWindowDC (HDC hdc)
	Check whether a given DC is a window DC. More...

MG_EXPORT HDC GUIAPI	CreateMemDCEx (int width, int height, int depth, DWORD flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask, void *bits, int pitch)
	Creates a memory DC. More...

static HDC GUIAPI	CreateMemDC (int width, int height, int depth, DWORD flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
	Creates a memory DC. More...

MG_EXPORT HDC GUIAPI	CreateSubMemDC (HDC parent, int off_x, int off_y, int width, int height, BOOL comp_to_parent)
	Creates a sub memory DC in the given memory DC. More...

MG_EXPORT HDC GUIAPI	CreateMemDCFromBitmap (HDC hdc, const BITMAP *bmp)
	Creates a memory DC from a reference DC and a BITMAP object. More...

MG_EXPORT HDC GUIAPI	CreateMemDCFromMyBitmap (const MYBITMAP my_bmp, const RGB pal)
	Creates a memory DC from a device independent MYBITMAP object. More...

MG_EXPORT BOOL GUIAPI	ConvertMemDC (HDC mem_dc, HDC ref_dc, DWORD flags)
	Converts a memory DC to have a same format as a reference DC. More...

MG_EXPORT BOOL GUIAPI	SetMemDCAlpha (HDC mem_dc, DWORD flags, Uint8 alpha)
	Set the alpha value for the entire surface of a DC, as opposed to using the alpha component of each pixel. More...

MG_EXPORT BOOL GUIAPI	SetMemDCColorKey (HDC mem_dc, DWORD flags, Uint32 color_key)
	Set the color key (transparent pixel) of a memory DC. More...

MG_EXPORT void GUIAPI	DeleteMemDC (HDC mem_dc)
	Deletes a memory DC. More...

MG_EXPORT Uint8 *GUIAPI	LockDC (HDC hdc, const RECT rw_rc, int width, int height, int pitch)
	Locks a dc to get direct access to pixels in the DC. More...

MG_EXPORT BOOL GUIAPI	LockDCEx (HDC hdc, const PCLIPRGN region, void *context, CB_DIRECT_DRAW_RECT cb)
	directly access the pixels in a DC. More...

MG_EXPORT void GUIAPI	UnlockDC (HDC hdc)
	Unlocks a locked DC. More...

MG_EXPORT HDC GUIAPI	CreatePrivateDC (HWND hwnd)
	Creates a private window DC of a window. More...

MG_EXPORT HDC GUIAPI	CreatePrivateClientDC (HWND hwnd)
	Creates a private client DC of a window. More...

HDC GUIAPI	CreatePrivateSubDC (HDC hdc, int off_x, int off_y, int width, int height)
	Creates a private SubDC of a window. More...

MG_EXPORT HDC GUIAPI	GetPrivateClientDC (HWND hwnd)
	Returns the private client DC of a window. More...

MG_EXPORT void GUIAPI	DeletePrivateDC (HDC hdc)
	Deletes the DC returned by CreatePrivateDC or CreatePrivateClientDC or CreatePrivateSubDC. More...

MG_EXPORT HDC GUIAPI	CreateSecondaryDC (HWND hwnd)
	Creates a secondary DC for a main window. More...

MG_EXPORT HDC GUIAPI	SetSecondaryDC (HWND hwnd, HDC secondary_dc, ON_UPDATE_SECONDARYDC on_update_secondarydc)
	Set a window's secondary DC and the callback procedure for the secondary DC update. More...

MG_EXPORT HDC GUIAPI	GetSecondaryDC (HWND hwnd)
	Retrieve and return the secondary DC of a specific window. More...

MG_EXPORT HDC GUIAPI	GetDCInSecondarySurface (HWND hWnd, BOOL bClient)
	Get a window or client DC by using the secondary surface if possible. More...

static HDC GUIAPI	GetSecondaryClientDC (HWND hwnd)
	Get a client DC of a window by using the secondary surface if possible. More...

static void GUIAPI	ReleaseSecondaryDC (HWND hwnd, HDC hdc)
	Release the DC returned by GetSecondaryClientDC. More...

MG_EXPORT void GUIAPI	DeleteSecondaryDC (HWND hwnd)
	Deletes the secondary DC of the window. More...

MG_EXPORT HDC GUIAPI	GetEffectiveCDC (HWND hwnd)
	Get the effective client DC of a window. More...

MG_EXPORT BOOL GUIAPI	SyncUpdateDC (HDC hdc)
	Synchronize the update rectangles of the surface corresponding to a DC to screen. More...

MG_EXPORT BOOL GUIAPI	SyncUpdateSurface (HWND hwnd)
	Synchronize the update rectangles of the backing surface of a window to screen. More...

Detailed Description

DC means Device Context, just like Graphics Context (GC) of X Lib. DC represents a rectangle area on the actual screen or a virtual screen created in memory. We call the rectangle area as "surface" of the DC.

You can call a GDI function and pass a DC to the function to draw lines, circles, or text. Commonly, you should call a function like GetClientDC or CreateCompatibleDC to get or create a DC, then call GDI functions to draw objects, e.g. MoveTo and LineTo. After finishing drawing, you should call ReleaseDC or DeleteMemDC function to release or destroy the DC.

MiniGUI reserved an global DC called HDC_SCREEN. You can use this DC directly without getting/creating or releasing/destroying.

For main windows or controls, MiniGUI will send a MSG_PAINT message to the window when the whole or part of window area have been invalidated. You should call BegainPaint function to get the DC, then repaint the window, and call EndPaint function to release the DC at the last.

Example:

case MSG_PAINT:
{
    HDC hdc;
 
    hdc = BeginPaint (hWnd);
 
    // Draw a line.
    MoveTo (hdc, 0, 0);
    LineTo (hdc, 100, 100);
 
    EndPaint (hWnd, hdc);
    return 0;
}

Macro Definition Documentation

◆ CreateCompatibleDC

#define CreateCompatibleDC ( hdc ) CreateCompatibleDCEx(hdc, 0, 0)

Creates a memory DC which is compatible with a given DC.

This function creates a memory DC fully compatible with the reference DC hdc, including pixel format and geomatry.

Parameters

hdc	The reference DC.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

See also: CreateCompatibleDCEx, DeleteMemDC

Definition at line 1969 of file gdi.h.

◆ DeleteCompatibleDC

#define DeleteCompatibleDC ( hdc ) DeleteMemDC(hdc)

Deletes a memory DC.

This function deletes a memory DC created by CreateCompatibleDC.

Parameters

hdc	The device context to be deleted.

See also: CreateCompatibleDC, DeleteMemDC

Definition at line 1981 of file gdi.h.

◆ HDC_INVALID

#define HDC_INVALID ((HDC)-1)

Indicates an invalid handle to device context.

Definition at line 1382 of file gdi.h.

◆ HDC_SCREEN

#define HDC_SCREEN ((HDC)0)

Handle to the device context of the whole screen or the fake screen when MiniGUI is running under MiniGUI-Processes with compositing schema.

This DC is a special one. Under MiniGUI-Standalone runmode, MiniGUI-Threads runmode, and MiniGUI-Processes runmode with shared frame buffer schema, MiniGUI uses it to draw popup menus and other global objects. You can also use this DC to draw lines or text on the screen directly, and there is no need to get or release it.

If you do not want to create any main window, but you want to draw on the screen, you can use this DC. Note that MiniGUI does not do any clipping operation for this DC, so drawing something on this DC may make a mess of other windows.

However, under MiniGUI-Processes with compositing schema, HDC_SCREEN stands for a global shared surface for wallpaper pattern. This surface is the ONLY surface that can be accessed by all processes (including the server and all clients) under compositing schema.

This surface will have the same pixel format as the real screen. Therefore, one app can still use HDC_SCREEN to create a compatible memory DC, load bitmaps, or draw something to the surface. However, the content in the wallpaper surface may not be reflected to the whole screen; the compositor decides how to display the contents in it.

On the other hand, you can configure MiniGUI to create a smaller surface than the whole screen as the underlying surface of HDC_SCREEN, and the compositor may use it as a pattern to tile the content to the whole wallpaper. You can use the key compositing_schema.wallpaper_pattern_size to specify the pattern size, i.e., the size of HDC_SCREEN, in runtime configuration.

Because of the change of HDC_SCREEN's connotation, you should avoid to use GetGDCapability to determine the screen resolution. Instead, you use the global variable/macro g_rcScr or the function GetScreenRect();

See also: HDC_SCREEN_SYS, GetScreenRect

Definition at line 1358 of file gdi.h.

Typedef Documentation

◆ CB_DIRECT_DRAW_RECT

typedef void(* CB_DIRECT_DRAW_RECT)(HDC hdc, Uint8 *pixels, int pitch, int bytesPerPixel, const RECT *rc, void *context)

Type of directly access pixels hook function.

This function is invoked by LockDCEx, application should implement this function in which could directly read and write the pixels in a DC.

Parameters

hdc	the device context.
pixels	the pixels addr point to the rc's left-top in DC.
pitch	(the bytes of one scan line) of the DC.
bytesPerPixel	bytes per pixel.
rc	the rectangle to draw, the field left of which is mapped to pixels.
context	the context provided by application.

Definition at line 2039 of file gdi.h.

◆ ON_UPDATE_SECONDARYDC

typedef int(* ON_UPDATE_SECONDARYDC)(HWND hwnd, HDC secondary_dc, HDC real_dc, const RECT *secondary_rc, const RECT *real_rc, const RECT *main_update_rc)

The callback type of on updating secondary DC.

Parameters

hwnd	The handle to the updated window.
secondary_dc	The update src dc.
real_dc	The update dst dc.
secondary_rc	The rectangle relative to secondary_dc.
real_rc	The rectangle relative to real_dc.
main_update_dc	The rectangle relative to main window.

Returns: The update result.

Definition at line 2235 of file gdi.h.

Function Documentation

◆ ConvertMemDC()

BOOL GUIAPI ConvertMemDC	(	HDC	mem_dc,
		HDC	ref_dc,
		DWORD	flags
	)

Converts a memory DC to have a same format as a reference DC.

This function converts a memory DC mem_dc in order to let it have the same pixel format as the reference DC ref_dc. This function will try to create a new surface for mem_dc, and then copies and maps the surface of ref_dc to it so the blit of the converted memory DC will be as fast as possible.

The flags parameter has the same semantics as CreateMemDC. You can also pass MEMDC_FLAG_RLEACCEL in the flags parameter and MiniGUI will try to RLE accelerate colorkey and alpha blits in the resulting memory DC.

Parameters

mem_dc	The device context to be converted.
ref_dc	The reference device context.
flags	The memory DC flags, has the same semantics as CreateMemDC.

Returns: TRUE on success, otherwise FALSE.

See also: CreateMemDC, DeleteMemDC

◆ CreateCompatibleDCEx()

HDC GUIAPI CreateCompatibleDCEx	(	HDC	hdc,
		int	width,
		int	height
	)

Creates a memory DC which is compatible with the specified reference DC.

This function creates a memory DC which have the same pixel format as the specified reference DC hdc. The same pixel format means that the memory DC will have the same pixel depth, the same RGB composition, or the same palette as the reference DC. Note that the memdc will have the same DC attributes as the reference DC.

Parameters

hdc	The handle to the reference DC.
width	The expected width of the result memory DC. If it is zero, the width will be equal to the width of the reference DC.
height	The expected height of the result memory DC. If it is zero, the height will be equal to the height of the reference DC.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

See also: CreateCompatibleDC

◆ CreateMemDC()

HDC GUIAPI CreateMemDC	(	int	width,
		int	height,
		int	depth,
		DWORD	flags,
		Uint32	Rmask,
		Uint32	Gmask,
		Uint32	Bmask,
		Uint32	Amask
	)

inlinestatic

Creates a memory DC.

This function creates a memory DC which have the specified flags and pixel format.

Parameters

width	The expected width of the result memory DC.
height	The expected height of the result memory DC.
depth	The expected color depth of the memory DC.
flags	The memory DC flags, can be or'ed values of the following flags:

MEMDC_FLAG_SWSURFACE
Creates the surface of memory DC in the system memory.
MEMDC_FLAG_HWSURFACE
Creates the surface of memory DC in the video memory.
MEMDC_FLAG_SRCCOLORKEY
The created memory DC will use a source color key to blit to other DC.
MEMDC_FLAG_SRCALPHA
The created memory DC will use a source alpha blending to blit to other DC.
MEMDC_FLAG_RLEACCEL
The memory DC will be RLE encoded.

Parameters

Rmask	The bit-masks of the red components in a pixel value.
Gmask	The bit-masks of the green components in a pixel value.
Bmask	The bit-masks of the blue components in a pixel value.
Amask	The bit-masks of the alpha components in a pixel value.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

See also: CreateMemDCEx, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap, CreateCompatibleDCEx

Definition at line 1787 of file gdi.h.

◆ CreateMemDCEx()

HDC GUIAPI CreateMemDCEx	(	int	width,
		int	height,
		int	depth,
		DWORD	flags,
		Uint32	Rmask,
		Uint32	Gmask,
		Uint32	Bmask,
		Uint32	Amask,
		void *	bits,
		int	pitch
	)

Creates a memory DC.

This function creates a memory DC which have the specified flags and pixel format, and uses the pre-allocated buffer as the surface if bits is not NULL.

Parameters

width	The expected width of the result memory DC.
height	The expected height of the result memory DC.
depth	The expected color depth of the memory DC.
flags	The memory DC flags, can be or'ed values of the following flags:

MEMDC_FLAG_SWSURFACE
Creates the surface of memory DC in the system memory.
MEMDC_FLAG_HWSURFACE
Creates the surface of memory DC in the video memory.
MEMDC_FLAG_SRCCOLORKEY
The created memory DC will use a source color key to blit to other DC.
MEMDC_FLAG_SRCALPHA
The created memory DC will use a source alpha blending to blit to other DC.
MEMDC_FLAG_RLEACCEL
The memory DC will be RLE encoded.

Parameters

Rmask	The bit-masks of the red components in a pixel value.
Gmask	The bit-masks of the green components in a pixel value.
Bmask	The bit-masks of the blue components in a pixel value.
Amask	The bit-masks of the alpha components in a pixel value.
bits	The pointer to the pre-allocated surface. If this is NULL, MiniGUI will try to allocate the surface from video memory or system memory.
pitch	The pitch (the number of bytes of one scan line) of the surface.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

Note: If you pass a pre-allocated surface buffer to this function, MiniGUI will not free the buffer when you delete the memdc by calling DeleteMemDC.

See also: CreateMemDC, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap, CreateCompatibleDCEx

◆ CreateMemDCFromBitmap()

HDC GUIAPI CreateMemDCFromBitmap	(	HDC	hdc,
		const BITMAP *	bmp
	)

Creates a memory DC from a reference DC and a BITMAP object.

This function creates a memory DC compatible with the specified DC, and use the bits of the BITMAP object as the surface of the memory DC. The created memory DC will have the same geometry as the BITMAP object.

Parameters

hdc	The reference DC.
bmp	The BITMAP object.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

See also: CreateMemDCFromMyBitmap, DeleteMemDC, BITMAP

◆ CreateMemDCFromMyBitmap()

HDC GUIAPI CreateMemDCFromMyBitmap	(	const MYBITMAP *	my_bmp,
		const RGB *	pal
	)

Creates a memory DC from a device independent MYBITMAP object.

This function creates a memory DC which have the same pixel format as the MYBITMAP object my_bmp, and use the bits of the MYBITMAP object as the surface of the memory DC. The created memory DC will have the same geometry as the MYBITMAP object. If the depth of my_bmp is 8-bit, the function will use pal to initialize the palette of the memory DC.

Note that the color depth of a memory DC can not be less than 8. Thefore, if the color depth of the MYBITMAP object is less than 8, this function will return HDC_INVALID.

Note that if the MYBITMAP object has the flag MYBMP_FLOW_UP, this function will return HDC_INVALID as well.

Parameters

my_bmp	The device independent MYBITMAP object.
pal	The palette of the MYBITMAP object. If the depth of my_bmp is larger than 8-bit, this argument can be NULL.

Returns: The handle to the memory DC, HDC_INVALID indicates an error.

See also: CreateMemDCFromBitmap, DeleteMemDC, MYBITMAP

◆ CreatePrivateClientDC()

HDC GUIAPI CreatePrivateClientDC ( HWND hwnd )

Creates a private client DC of a window.

This function creates a private client DC of the window hwnd and returns the handle to the DC.

When you calling CreatePrivateClientDC function to create a private client DC, MiniGUI will create the DC in the system heap, rather than allocating one from the DC pool. Thus, you can keep up the DC in the life cycle of the window, and are not needed to release it for using by other windows.

Since 5.0.0, if the main window which contains the window has secondary DC, this function will make the private data using the memory surface for the secondary DC.

Parameters

hwnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: DeletePrivateDC

◆ CreatePrivateDC()

HDC GUIAPI CreatePrivateDC ( HWND hwnd )

Creates a private window DC of a window.

This function creates a private window DC of the window hwnd and returns the handle to the DC.

When you calling CreatePrivateDC function to create a private DC, MiniGUI will create the DC in the system heap, rather than allocating one from the DC pool. Thus, you can keep up the private DC in the life cycle of the window, and are not needed to release it for using by other windows.

Since 5.0.0, if the main window which contains the window has secondary DC, this function will make the private data using the memory surface for the secondary DC.

Parameters

hwnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: DeletePrivateDC

◆ CreatePrivateSubDC()

HDC GUIAPI CreatePrivateSubDC	(	HDC	hdc,
		int	off_x,
		int	off_y,
		int	width,
		int	height
	)

Creates a private SubDC of a window.

This function creates a private sub DC of the DC and returns the handle of the SubDC.

When you calling CreatePrivateSubDC function to create a private a sub DC, MiniGUI will create the DC in the system heap, rather than allocating one from the DC pool. Thus, you can keep up the DC in the life cycle of the window, and are not needed to release it for using by other windows.

Parameters

hdc	The handle of the DC.
off_x	The x-coordinate of the sub DC in the parent DC (in device coordinate system).
off_y	The y-coordinate of the sub DC in the parent DC (in device coordinate system).
width	The expected width of the sub DC.
height	The expected height of the sub DC.

Returns: The handle to SubDC, HDC_INVALID indicates an error.

See also: DeletePrivateDC

◆ CreateSecondaryDC()

HDC GUIAPI CreateSecondaryDC ( HWND hwnd )

Creates a secondary DC for a main window.

This function creates a secondary DC for the main window hwnd and returns the handle to the secondary DC.

When you calling CreateSecondaryDC function, MiniGUI will create a memory DC which is compatible with HDC_SCREEN.

When a main window has set a secondary DC, MiniGUI will use the off-screen surface of the secondary DC to render the content of the main window and its descendants.

When a main window have the extended style WS_EX_AUTOSECONDARYDC, MiniGUI will create a secondary DC for this main window in the creation progress of the main window, and destroy the DC when you destroy the window.

Parameters

hwnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: DeleteSecondaryDC

◆ CreateSubMemDC()

HDC GUIAPI CreateSubMemDC	(	HDC	parent,
		int	off_x,
		int	off_y,
		int	width,
		int	height,
		BOOL	comp_to_parent
	)

Creates a sub memory DC in the given memory DC.

This function creates a sub memory DC in the given memory DC (the parent memory DC). Note that the new sub memdc will have the same DC attributes as the parent memdc.

Parameters

parent	The handle to the parent memory DC.
off_x	The x-coordinate of the sub memory DC in the parent DC (in device coordinate system).
off_y	The y-coordinate of the sub memory DC in the parent DC (in device coordinate system).
width	The expected width of the sub memory DC.
height	The expected height of the sub memory DC.
comp_to_parent	The flag indicates whether the sub memdc is compliant to the parent dc.

Returns: The handle to the memory DC; HDC_INVALID indicates an error.

Note: Only defined for _USE_NEWGAL.

See also: CreateMemDC

◆ DeleteMemDC()

void GUIAPI DeleteMemDC ( HDC mem_dc )

Deletes a memory DC.

This function deletes the memory DC mem_dc, and frees the surface of the DC. For the memory DC created from BITMAP object or MYBITMAP object, the bits used by the surface of the DC will be reserved.

Parameters

mem_dc The device context to be deleted.

See also: CreateMemDC, CreateMemDCFromBitmap, CreateMemDCFromMyBitmap

◆ DeletePrivateDC()

void GUIAPI DeletePrivateDC ( HDC hdc )

Deletes the DC returned by CreatePrivateDC or CreatePrivateClientDC or CreatePrivateSubDC.

Parameters

hdc	The handle to the DC.

See also: CreatePrivateDC, CreatePrivateClientDC

◆ DeleteSecondaryDC()

void GUIAPI DeleteSecondaryDC ( HWND hwnd )

Deletes the secondary DC of the window.

Parameters

hwnd	The handle to the window.

See also: CreateSecondaryDC

◆ GetClientDC()

HDC GUIAPI GetClientDC ( HWND hWnd )

inlinestatic

Get a client DC of a window.

This function gets a client DC of the specified hwnd, and returns the handle to the DC. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocating a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

Parameters

hWnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

Note: You should call ReleaseDC to release the DC when you are done.

See also: GetDC, ReleaseDC

Definition at line 1512 of file gdi.h.

◆ GetDC()

HDC GUIAPI GetDC ( HWND hWnd )

inlinestatic

Get a window DC of a window.

This function gets a window DC of the specified hwnd, and returns the handle to the DC. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocating a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

Parameters

hWnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

Note: You should call ReleaseDC to release the DC when you are done.

See also: GetClientDC, ReleaseDC

Definition at line 1490 of file gdi.h.

◆ GetDCEx()

HDC GUIAPI GetDCEx	(	HWND	hWnd,
		BOOL	bClient
	)

Get a window or client DC of a window.

This function gets a window or a client DC of the specified hwnd, and returns the handle to the DC. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocating a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

Parameters

hWnd	The handle to the window.
bClient	Whether to initialize as a window or a client DC; TRUE for client DC, FALSE for window DC.

Returns: The handle to the DC, HDC_INVALID indicates an error.

Note: You should call ReleaseDC to release the DC when you are done.

See also: GetClientDC, ReleaseDC

Since 5.0.0

◆ GetDCInSecondarySurface()

HDC GUIAPI GetDCInSecondarySurface	(	HWND	hWnd,
		BOOL	bClient
	)

Get a window or client DC by using the secondary surface if possible.

This function gets a window DC or a client DC by using the surface of the secondary DC created by the main window which contains the specified window hWnd. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocating a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

If the main window which contains this window does not have secondary DC, this function acts as GetDCEx.

Parameters

hWnd	The handle to the main window.
bClient	Whether to initialize as a window or client DC. TRUE for client DC, FALSE for window DC.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: GetDCEx, ReleaseDC

◆ GetEffectiveCDC()

HDC GUIAPI GetEffectiveCDC ( HWND hwnd )

Get the effective client DC of a window.

This function returns an effective client DC of the specified window by using the following rules:

If the window has private client DC, returns it.
If the main window contains the window has a secondary DC, returns a client DC by calling GetDCInSecondarySurface.
Returns a client DC by calling GetClientDC.

You should release the client DC as soon as possible when you are done with it.

Parameters

hwnd	The handle to the window.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: GetPrivateClientDC, GetDCInSecondarySurface, GetClientDC, ReleaseDC

Since 5.0.0

◆ GetGDCapability()

Uint32 GUIAPI GetGDCapability	(	HDC	hdc,
		int	iItem
	)

Returns a capability of a DC.

This function returns the capability of the specified item iItem of the DC hdc.

Parameters

hdc	The handle to the DC.
iItem	An integer presents the capablity, can be one of the following values:

GDCAP_COLORNUM
Tell GetGDCapability to return the colors number of the DC. Note the for a DC with 32-bit depth, the function will return 0xFFFFFFFF, not 0x100000000.
GDCAP_HPIXEL
Tell GetGCapability to return the horizontal resolution of the DC.
GDCAP_VPIXEL
Tell GetGDCapability to return the vertical resolution of the DC.
GDCAP_MAXX
Tell GetGDCapability to return the maximal visible x value of the DC.
GDCAP_MAXY
Tell GetGDCapability to return the maximal visible y value of the DC.
GDCAP_DEPTH
Tell GetGDCapability to return the color depth of the DC. The returned value can be 1, 4, 8, 15, 16, 24, or 32.
GDCAP_BITSPP
Tell GetGDCapability to return the bits number for storing a pixle in the DC.
GDCAP_BPP
Tell GetGDCapability to return the bytes number for storing a pixle in the DC.
GDCAP_RMASK
Tell GetGDCapability to return the pixel red color mask for the DC.
GDCAP_GMASK
Tell GetGDCapability to return the pixel green color mask for the DC.
GDCAP_BMASK
Tell GetGDCapability to return the pixel blue color mask for the DC.
GDCAP_AMASK
Tell GetGDCapability to return the pixel alpha color mask for the DC.
GDCAP_PITCH
Tell GetGDCapability to return the pitch (the bytes of one scan line) of the DC.
GDCAP_DPI
Tell GetGDCapability to return the DPI (the dots per inch) of the DC.

Returns: The capbility.

◆ GetPrivateClientDC()

HDC GUIAPI GetPrivateClientDC ( HWND hwnd )

Returns the private client DC of a window.

This function returns the private client DC of the window hwnd which have extended style WS_EX_USEPRIVATECDC.

When a main window have the extended style WS_EX_USEPRIVATECDC, or a control class have the style CS_OWNDC, MiniGUI will create a private client DC for this window in the creation progress of the window, and destroy the DC when you destroy the window, and use this private client DC in default message handlers. So there will be some improvments on drawing/repaint performance. You can alos call this function to get the private client DC, and use it to draw anything in your window.

Parameters

hwnd	The handle to the window.

Returns: The handle to the private client DC, HDC_INVALID indicates an error.

See also: CreatePrivateClientDC

◆ GetSecondaryClientDC()

HDC GUIAPI GetSecondaryClientDC ( HWND hwnd )

inlinestatic

Get a client DC of a window by using the secondary surface if possible.

This function gets a client DC by using the surface of the secondary DC created by the main window which contains the specified window hWnd. MiniGUI will try to return an unused DC from the internal DC pool, rather than allocating a new one from the system heap. Thus, you should release the DC when you finish drawing as soon as possible.

If the main window which contains this window (or itself) does not have a secondary DC, this function acts as GetClientDC.

Parameters

hwnd	The handle to a main window or a control.

Returns: The handle to the DC, HDC_INVALID indicates an error.

See also: GetDCInSecondarySurface

Definition at line 2332 of file gdi.h.

◆ GetSecondaryDC()

HDC GUIAPI GetSecondaryDC ( HWND hwnd )

Retrieve and return the secondary DC of a specific window.

This function retrieves and returns the secondary DC of the main window which contains the specified window hwnd.

When a main window has been set the secondary DC, MiniGUI will use the off-screen surface of the secondary DC to render the content of the main window and its descendants.

Parameters

hwnd	The handle to the window.

Returns: The handle to the secondary DC; HDC_SCREEN indicates that the window has no secondary DC.

See also: CreateSecondaryDC, SetSecondaryDC

◆ GetSubDC()

HDC GUIAPI GetSubDC	(	HDC	hdc,
		int	off_x,
		int	off_y,
		int	width,
		int	height
	)

This function gets a sub DC which is compliant to the specified client DC.

This function creates a sub client DC, which is restricted in the specified rectangle and compliant to the specified client DC hdc. Note that you should release the returned dc by calling ReleaseDC.

Parameters

hdc	The handle to the parent client DC.
off_x	The x-coordinate of the sub DC in the parent DC (in device coordinate system).
off_y	The y-coordinate of the sub DC in the parent DC (in device coordinate system).
width	The expected width of the sub DC.
height	The expected height of the sub DC.

Returns: The handle to the new sub DC, HDC_INVALID indicates an error.

Note: You should call ReleaseDC to release the DC when you are done.

See also: GetDC, GetClientDC, ReleaseDC

◆ IsCompatibleDC()

BOOL GUIAPI IsCompatibleDC	(	HDC	hdc1,
		HDC	hdc2
	)

Check whether a given DC is compliant to a specific DC.

This function checks whether a give DC hdc2 is compliant to the specific DC hdc1.

Parameters

hdc1	The handle to a DC.
hdc2	The handle to another DC.

Returns: TRUE when hdc2 is compiliant to hdc1, otherwise FALSE.

See also: CreateCompatibleDCEx

◆ IsMemDC()

BOOL GUIAPI IsMemDC ( HDC hdc )

Check whether a given DC is a memory DC.

This function checks whether a give DC hdc is a memory DC.

Parameters

hdc	The handle to the DC.

Returns: TRUE for memory DC, otherwise FALSE.

See also: CreateMemDCEx

◆ IsScreenDC()

BOOL GUIAPI IsScreenDC ( HDC hdc )

Check whether a given DC is a screen DC.

This function checks whether a give DC hdc is a screen DC.

Parameters

hdc	The handle to the DC.

Returns: TRUE for screen DC, otherwise FALSE.

See also: CreateMemDCEx

◆ IsWindowDC()

BOOL GUIAPI IsWindowDC ( HDC hdc )

Check whether a given DC is a window DC.

This function checks whether a give DC hdc is a window DC.

Parameters

hdc	The handle to the DC.

Returns: TRUE for window DC, otherwise FALSE.

See also: CreateMemDCEx

◆ LockDC()

Uint8 *GUIAPI LockDC	(	HDC	hdc,
		const RECT *	rw_rc,
		int *	width,
		int *	height,
		int *	pitch
	)

Locks a dc to get direct access to pixels in the DC.

Calling this function will try to lock the DC hdc to directly access the pixels of the DC. You should tell this function the rectangle to be accessed, and the function will return the requested width, height and pitch of the DC. The access beyond requested width and height will be invalid.

Locking a DC which uses screen surface will lock some global objects, such as mouse cursor, and so on. All GDI calls of other threads (in MiniGUI-Threads) or other process (in MiniGUI-Processes) will be blocked as well. So you should call UnlockDC to unlock the DC as soon as possible, and should not call any system function in the duration of locking the DC.

Parameters

hdc	The handle to the device context.
rw_rc	The rectangle in device coordinate system to be accessed in the DC.
width	The width of the effective rectangle can access will be returned through this pointer.
height	The height of the effective rectangle can access will be returned through this pointer.
pitch	The pitch of the scan line of the DC will be returned through this pointer. Pitch means the length of the scan line in bytes.

Returns: The bits pointer to the upper-left corner of the requested rectangle, NULL on error.

See also: UnlockDC, LockDCEx

Example:

    /*
     * lock the dc and draw the scan line with random color.
     */
 
    int i, width, height, pitch;
    RECT rc = {0, 0, 200, 200};
    int bpp = GetGDCapability (hdc, GDCAP_BPP);
    Uint8* frame_buffer = LockDC (hdc, &rc, &width, &height, &pitch);
    Uint8* row = frame_buffer;
 
    for (i = 0; i < *height; i++) {
        memset (row, rand ()%0x100, *width * bpp);
        row += *pitch;
    }
 
    UnlockDC (hdc);

◆ LockDCEx()

BOOL GUIAPI LockDCEx	(	HDC	hdc,
		const PCLIPRGN	region,
		void *	context,
		CB_DIRECT_DRAW_RECT	cb
	)

directly access the pixels in a DC.

This function fill region by function cb that directly accesses pixels in a DC. This function is used to draw region more effiently. The function that lock __mg_gdilock should not be invoked any more after invoking this function, or else it will cause deadlock. UnlockDC should be invoked after invoking this function that will call back CB_DIRECT_DRAW_RECT, other process could not draw any more until the DC has been unlocked.

Parameters

hdc	the device context.
region	the visible region to draw.
context	the context provided by application, which is as a parameter of cb.
cb	the direct draw function that directly accesses pixels which should be implemented by application. if cb is NULL, the region will be filled by current brush color.

Returns: if LockDCEx success return TRUE, else return FALSE;

See also: UnlockDC, LockDC

◆ ReleaseDC()

void GUIAPI ReleaseDC ( HDC hdc )

Releases a DC from DC pool.

This function releases the DC returned by GetDC or GetClientDC.

Parameters

hdc	The handle to the DC.

See also: GetDC, GetClientDC, GetSubDC

◆ ReleaseSecondaryDC()

void GUIAPI ReleaseSecondaryDC	(	HWND	hwnd,
		HDC	hdc
	)

inlinestatic

Release the DC returned by GetSecondaryClientDC.

Parameters

hwnd	The handle to the window.
hdc	The handle to the secondary DC.

Note: Deprecated; use ReleaseDC instead.

See also: ReleaseDC

Definition at line 2348 of file gdi.h.

◆ RestoreDC()

BOOL GUIAPI RestoreDC	(	HDC	hdc,
		int	saved_dc
	)

Restores a device context (DC) to the specified state.

This function restores a device context (DC) to the specified state. The DC is restored by popping state information off a stack created by earlier calls to the SaveDC function.

Parameters

hdc	The handle to the DC.
saved_dc	Specifies the saved state to be restored. If this parameter is positive, saved_dc represents a specific instance of the state to be restored. If this parameter is negative, saved_dc represents an instance relative to the current state. For example, -1 restores the most recently saved state.

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

Note: The stack can contain the state information for several instances of the DC. If the state specified by the specified parameter is not at the top of the stack, RestoreDC deletes all state information between the top of the stack and the specified instance.

See also: SaveDC

◆ SaveDC()

int GUIAPI SaveDC ( HDC hdc )

Saves the current state of a device context.

This function saves the current state of the specified device context (DC) by copying data describing selected objects and graphic modes (such as pen, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack.

Parameters

hdc	The handle to the DC whose state is to be saved.

Returns: If the function succeeds, the return value identifies the saved state. If the function fails, the return value is zero.

Note: This function can be used any number of times to save any number of instances of the DC state. A saved state can be restored by using the RestoreDC function.

See also: RestoreDC

◆ SetMemDCAlpha()

BOOL GUIAPI SetMemDCAlpha	(	HDC	mem_dc,
		DWORD	flags,
		Uint8	alpha
	)

Set the alpha value for the entire surface of a DC, as opposed to using the alpha component of each pixel.

This function sets the alpha value for the entire surface of the DC mem_dc, as opposed to using the alpha component of each pixel. This value measures the range of transparency of the surface, 0 being completely transparent to 255 being completely opaque. An alpha value of 255 causes blits to be opaque, the source pixels copied to the destination (the default). Note that per-surface alpha can be combined with colorkey transparency.

If flags is 0, alpha blending is disabled for the surface. If flags is MEMDC_FLAG_SRCALPHA, alpha blending is enabled for the surface. OR'ing the flag with MEMDC_FLAG_RLEACCEL requests RLE acceleration for the surface; if MEMDC_FLAG_RLEACCEL is not specified, the RLE acceleration will be removed. If flags is MEMDC_FLAG_SRCPIXELALPHA, per-pixel alpha blending is enabled for the surface.

Parameters

mem_dc	The device context.
flags	The alpha value specific memory DC flags.
alpha	the alpha value for the entire surface of the DC mem_dc.

Returns: TRUE on success, otherwise FALSE.

See also: SetMemDCColorKey

◆ SetMemDCColorKey()

BOOL GUIAPI SetMemDCColorKey	(	HDC	mem_dc,
		DWORD	flags,
		Uint32	color_key
	)

Set the color key (transparent pixel) of a memory DC.

This function sets the color key (transparent pixel) of the memory DC mem_dc. If flags is MEMDC_FLAG_SRCCOLORKEY (optionally OR'ed with MEMDC_FLAG_RLEACCEL), color_key will be the transparent pixel in the source DC of a blit. MEMDC_FLAG_RLEACCEL requests RLE acceleration for the source of the DC if present, and removes RLE acceleration if absent. If flags is 0, this function clears any current color key.

Parameters

mem_dc	The device context.
flags	The color key specific memory DC flags.
color_key	The color_key of the memory DC.

Returns: TRUE on success, otherwise FALSE.

See also: SetMemDCAlpha

◆ SetSecondaryDC()

HDC GUIAPI SetSecondaryDC	(	HWND	hwnd,
		HDC	secondary_dc,
		ON_UPDATE_SECONDARYDC	on_update_secondarydc
	)

Set a window's secondary DC and the callback procedure for the secondary DC update.

This function set the secondary DC of the main window hwnd and returns the handle to the old seconadary DC.

Parameters

hwnd	The handle to the main window.
secondary_dc	The secondary DC which will be the new secondary DC of the main window.
on_update_secondarydc	The callback procedure for the secondary DC update. You can pass one of two sepcial values: ON_UPDSECDC_DEFAULT The default operation to update the secondary DC to the real DC of the main window. ON_UPDSECDC_DONOTHING No any operation occures.

Returns: The handle to the old secondary DC, HDC_SCREEN indicates the main window has no secondary DC before calling this function.

See also: DeleteSecondaryDC

◆ SyncUpdateDC()

BOOL GUIAPI SyncUpdateDC ( HDC hdc )

Synchronize the update rectangles of the surface corresponding to a DC to screen.

This function synchronizes the update rectangles of the surface corresponding to the DC specified by hdc to screen.

Parameters

hdc	The handle to the DC.

Returns: TRUE when there are rectangles to be synchronized and updated; FALSE when it is not necessory to update.

◆ SyncUpdateSurface()

BOOL GUIAPI SyncUpdateSurface ( HWND hwnd )

Synchronize the update rectangles of the backing surface of a window to screen.

This function synchronizes the update rectangles of the backing surface of the window specified by hwnd to screen.

Parameters

hwnd	The handle to the window.

Returns: TRUE when there are rectangles to be synchronized and updated; FALSE when hwnd is invalid, or it is not necessory to update.

◆ UnlockDC()

void GUIAPI UnlockDC ( HDC hdc )

Unlocks a locked DC.

Parameters

hdc	The locked DC.

See also: LockDC, LockDCEx

◆ WindowFromDC()

HWND GUIAPI WindowFromDC ( HDC hdc )

Get the window handle from DC.

This function returns the handle to a window according to the handle to DC of the window.

Parameters

hdc	The handle to the DC.

Note: Do not call this function on memory DC.

See also: GetDC.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CreateCompatibleDC

◆ DeleteCompatibleDC

◆ HDC_INVALID

◆ HDC_SCREEN

Typedef Documentation

◆ CB_DIRECT_DRAW_RECT

◆ ON_UPDATE_SECONDARYDC

Function Documentation

◆ ConvertMemDC()

◆ CreateCompatibleDCEx()

◆ CreateMemDC()

◆ CreateMemDCEx()

◆ CreateMemDCFromBitmap()

◆ CreateMemDCFromMyBitmap()

◆ CreatePrivateClientDC()

◆ CreatePrivateDC()

◆ CreatePrivateSubDC()

◆ CreateSecondaryDC()

◆ CreateSubMemDC()

◆ DeleteMemDC()

◆ DeletePrivateDC()

◆ DeleteSecondaryDC()

◆ GetClientDC()

◆ GetDC()

◆ GetDCEx()

◆ GetDCInSecondarySurface()

◆ GetEffectiveCDC()

◆ GetGDCapability()

◆ GetPrivateClientDC()

◆ GetSecondaryClientDC()

◆ GetSecondaryDC()

◆ GetSubDC()

◆ IsCompatibleDC()

◆ IsMemDC()

◆ IsScreenDC()

◆ IsWindowDC()

◆ LockDC()

◆ LockDCEx()

◆ ReleaseDC()

◆ ReleaseSecondaryDC()

◆ RestoreDC()

◆ SaveDC()

◆ SetMemDCAlpha()

◆ SetMemDCColorKey()

◆ SetSecondaryDC()

◆ SyncUpdateDC()

◆ SyncUpdateSurface()

◆ UnlockDC()

◆ WindowFromDC()