WORD RealizeObject(LPPDEVICE lpDestDev, WORD wStyle, LPVOID lpInObj,
LPVOID lpOutObj, LPTEXTXFORM lpTextXForm);
Creates or deletes a physical object. The function creates a physical object by filling a structure provided by GDI with device-specific data that corresponds to the attributes of a given logical pen, brush, bitmap, or font; it deletes the physical object by removing any memory or resources it allocated when creating the object.
Condition | Return value |
For solid brushes for a monochrome DC | 8001h |
For solid brushes for a color DC | 8002h |
For all other brush styles and objects | 8000h |
If unsuccessful, returns zero.
lpDestDev
Address of a PDEVICE or PBITMAP structure that specifies the device or bitmap to create the physical object for.
wStyle
One of the following objects:
Value | Meaning |
OBJ_PEN (1) | Realizes a physical pen. |
OBJ_BRUSH (2) | Realizes a physical brush. |
OBJ_FONT (3) | Realizes a device font. If the device has no device fonts or cannot realize the requested font, the RealizeObject function returns zero. |
OBJ_PBITMAP (5) | Realizes a device bitmap. GDI passes this value only if the RC_DEVBITS value is set in the dpRaster member of the driver's GDIINFO structure. |
If the wStyle parameter is negative, the function deletes the specified object.
lpInObj
Address of an LOGPEN, LOGBRUSH, LOGFONT, or PBITMAP structure specified by the wStyle parameter. The structure describes the logical attributes of the object to be realized.
If wStyle is negative, the lpInObj parameter points to the PPEN, PBRUSH, FONTINFO, or PBITMAP structure that specifies the physical object to be deleted.
lpOutObj
Address of a buffer to receive the realized object, or points to the physical object to delete. The meaning of this parameter depends on the value of the wStyle parameter.
If wStyle is positive, the lpOutObj parameter points to a buffer. The function fills the buffer with device-specific data that defines a physical object corresponding to the logical object pointed to by the lpInObj parameter. If lpOutObj is NULL, the function returns the size, in bytes, of the physical object.
If wStyle is negative, lpOutObj points to the physical object to delete. Although GDI frees the memory pointed to by lpOutObj when the function returns, the RealizeObject function must free any other memory or resources associated with the physical object.
lpTextXForm
Address of a TEXTXFORM structure or specifies a POINT structure as specified by the wStyle parameter.
If wStyle is OBJ_BRUSH, the lpTextXForm parameter is a POINT structure that contains the x- and y-coordinates (relative to an 8-bit boundary) on which to align the start of the brush's pattern.
If wStyle is OBJ_FONT, lpTextXForm points to a TEXTXFORM structure that contains information about the appearance of a realized font. Both the realized font and the contents of the TEXTXFORM structure are later passed to the ExtTextOut function, allowing more capable devices to make changes to the standard font.
The export ordinal for this function is 10.
GDI may call this function when an application calls functions such as CreateDC, SelectObject, and DeleteObject.
Every graphics driver must export the RealizeObject function.
GDI manages the physical object and makes the object available to the device driver as necessary to draw output. When GDI no longer needs the object, it directs RealizeObject to delete the object.
To create an object, GDI calls this function twice. It first requests the size, in bytes, of the physical object. Then it allocates space for the object and calls RealizeObject again passing a pointer to the allocated space. The lpOutObj parameter specifies which action to take. If it is NULL, the function returns the size; if it is not NULL, the function fills the corresponding structure.
The format and content of a physical object depends entirely on the device driver. For pens and brushes, the recommended formats are the PPEN and PBRUSH structures. For fonts, the structure must contain the dfType through dfFace members of the FONTINFO structure, and dfDevice and dfFace must have valid pointers to device and font strings.
When realizing pens, GDI may request a width or styled line even though the driver does not support such pens. (The dpCurves and dpLines members of the driver's GDIINFO structure specify whether the driver supports wide and styled lines.) In such cases, the RealizeObject function should create a nominal pen, that is, a physical pen that is solid and one-pixel wide. GDI uses this nominal pen that is used to carry out its own styling and wide-line operations.
When realizing brushes, RealizeObject sets the foreground and background colors for hatch and solid brushes, but not for patterned brushes if the patterned brush uses a monochrome bitmap. For these patterned brushes, GDI provides a DRAWMODE structure that specifies the foreground and background colors for the brush. If the color specified for a solid brush does not exactly match a physical color, the function can create a dithered color for the brush. The function realizes hollow brushes. When a hollow brush is passed to a drawing routine, the driver does no filling at all.
If the lpTextXForm parameter specifies a POINT structure, it represents the physical object's pattern reference point. This reference point specifies where to start a patterned brush (relative to a 8-bit boundary) so that the brush pattern aligns with areas previously filled using the brush. The parameter contains values, in the range 0 to 7, that specify on which bits to start the pattern.
Display drivers generally do not realize fonts. Instead, they require GDI to realize the fonts to be used with the display. In this case, the display driver's RealizeObject must returns zero whenever the wStyle parameter is OBJ_FONT.
When realizing bitmaps, RealizeObject must create a device bitmap, storing the bitmap bits in device memory (such as RAM on the device adapter) rather than main memory. When GDI requests the size of the physical bitmap, the function must include space for at least a PBITMAP structure, but any additional space is up to the driver. Although no space for the bitmap bits is required, RealizeObject must include some value to indicate the location of the bitmap bits in device memory. GDI intercepts all requests to create monochrome bitmaps. This means RealizeObject is never called to create a monochrome device bitmap.
If wStyle is OBJ_PBITMAP, the return value can be zero to direct GDI to create a main memory bitmap instead of a device bitmap. The return value will be 0x80000000L to indicate an error, and prevent GDI from creating a main memory bitmap.
See also PDEVICE, PBITMAP, LOGBRUSH, LOGFONT, LOGPEN, TEXTXFORM, POINT, FONTINFO