L_GetBitmapRgnHandle (original) (raw)

Summary

Creates a Windows region that is a snapshot of the bitmap region and assigns the handle to a variable that you supply.

Syntax

#include "l_bitmap.h"

L_LTDIS_API L_INT L_GetBitmapRgnHandle(pBitmap, pXForm, phRgn)

Parameters

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle referencing the bitmap that has the region.

pRGNXFORM pXForm

Pointer to an RGNXFORM structure that LEADTOOLS uses to translate between display coordinates and bitmap coordinates.

If you specify NULL in this parameter, the scalar fields default to 1, the offsets default to 0, and the view perspective defaults to the bitmap's view perspective.

L_HRGN* phRgn

Pointer to the Windows region handle. You do not have to create the region. You just declare the HRGN variable and pass its address.

Returns

Comments

Before calling this function, you must declare an RGNXFORM structure and set its values, which LEADTOOLS uses to translate between device context coordinates and bitmap coordinates. For details about how the structure works refer to the RGNXFORM structure description. For a description of common usage, refer to Translating Coordinates for a Bitmap Region.

If you want to assign a region from one bitmap to another, you must use the L_GetBitmapRgnHandle function to get region from the first bitmap; then use the L_SetBitmapRgnHandle function to assign the region to the second bitmap.

Because this function updates some members of the BITMAPHANDLE structure, it is not safe to call it from multiple threads using the same pBitmap.

You are responsible for deleting the Windows region to free memory when the region is no longer needed. To do so, use the Windows DeleteObject function. The following is a list of Windows functions that relate to Windows regions:

• CombineRgn creates a region by combining two regions.
• CreateEllipticRgn creates an elliptical region.
• CreateEllipticRgnIndirect creates and elliptical region.
• CreatePolygonRgn creates a polygonal region.
• CreatePolyPolygonRgn creates a region consisting of polygons.
• CreateRectRgn creates a rectangular region.
• CreateRectRgnIndirect creates a rectangular region using a RECT structure.
• CreateRoundRectRgn creates a rectangular region with round corners.
• DeleteObject deletes a Windows GDI object, such as a region.
• EqualRgn compares two regions for equality.
• FillRgn fills a region with the specified brush.
• FrameRgn draws a border around a region.
• GetRgnBox retrieves the bounding rectangle for a region.
• InvertRgn inverts the colors in a region.
• OffsetRgn moves a region by the specified offsets.
• PaintRgn fills a region with the brush in the device context.
• PtInRegion queries whether a point is in a region.
• RectInRegion queries whether a rectangle overlaps a region.
• SetRectRgn changes a region into a specified rectangle.

Required DLLs and Libraries

• LTDIS
• For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64, Linux.

See Also

Functions

• L_SetBitmapRgnHandle

Topics

• Raster Image Functions: Creating and Using a Region
• Raster Image Functions: Region Processing
• Defining and Using a Bitmap Region

Example

For an example, refer to L_SetBitmapRgnHandle.
For a complete sample code, refer to the DRAW example.