Jump to content

GreQueryDeviceCaps

From EDM2
Revision as of 03:00, 29 November 2019 by Martini (talk | contribs) (Created page with "; Simulation support: None. This function is mandatory for all drivers. GreQueryDeviceCaps supports DevQueryCaps() at the API. See Presentation Manager Programming Reference...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Simulation support
None. This function is mandatory for all drivers.

GreQueryDeviceCaps supports DevQueryCaps() at the API. See Presentation Manager Programming Reference, Volume 1 for more information about DevQueryCaps(). The handling routine returns the required information in the device capabilities buffer addressed by paOutData.

This function must be supported by the presentation driver. GreQueryDeviceCaps is called by DevQueryCaps(), and is used to return information regarding the general capabilities of the device.

Syntax

GreQueryDeviceCaps(hdc, lIndex, paOutData, cOutData, pInstance, lFunction);

Parameters

hdc (HDC) - input
Device context handle.
lIndex (LONG) - input
Identifies the first item required.

Indicates the element within the device capabilities array at which the presentation driver must begin returning information. Device capabilities are held by the system in an array of ULONG fields:

  • CAPS_FAMILY Device type.
  • CAPS_IO_CAPS Device input/output capability. Has the following values:
    • CAPS_IO_DUMMY
Dummy device
    • CAPS_SUPPORTS_OP
Device supports output
    • CAPS_SUPPORTS_IP
Device supports input
    • CAPS_SUPPORTS_IO
Device supports output and input.
  • CAPS_TECHNOLOGY Technology. Has the following values:
    • CAPS_TECH_UNKNOWN
Unknown
    • CAPS_TECH_VECTOR_PLOTTER
Vector plotter
    • CAPS_TECH_RASTER_DISPLAY
Raster display
    • CAPS_TECH_RASTER_PRINTER
Raster printer
    • CAPS_TECH_RASTER_CAMERA
Raster camera
    • CAPS_TECH_POSTSCRIPT
PostScript device.
  • CAPS_DRIVER_VERSION
Version identifier of the presentation driver. The high-order WORD of the version identifier is 0. The low-order WORD identifies the release. For example, 0x0120 is Release 1.2.
  • CAPS_WIDTH
Media width in pels of a full-screen, maximized window for displays.
  • CAPS_HEIGHT
Media depth in pels of a full-screen, maximized window for displays. For a plotter, a pel is defined as the smallest possible displacement of the pen and can be smaller than a pen width.
  • CAPS_WIDTH_IN_CHARS
Media width in default character columns of a full-screen, maximized window for displays.
  • CAPS_HEIGHT_IN_CHARS
Media depth in default character rows of a full-screen, maximized window for displays.
  • CAPS_HORIZONTAL_RESOLUTION
Horizontal resolution of device in pels per meter.
  • CAPS_VERTICAL_RESOLUTION
Vertical resolution of device in pels per meter.
  • CAPS_CHAR_WIDTH
Default character-box width for VIO, in pels
  • CAPS_CHAR_HEIGHT
Default character-box height for VIO, in pels.
  • CAPS_SMALL_CHAR_WIDTH
Default small-character box width for VIO, in pels. If 0, there is only one character-box size.
  • CAPS_SMALL_CHAR_HEIGHT
Default small-character box height for VIO, in pels. If 0, there is only one character-box size.
  • CAPS_COLORS
Number of distinct colors supported at the same time, including reset. (Note that gray scales count as distinct colors.) If loadable color tables are supported, this is the number of entries in the device color table. For plotters, the value returned is the "number of pens + 1" (for the background).
  • CAPS_COLOR_PLANES
Number of color planes.
  • CAPS_COLOR_BITCOUNT
Number of adjacent color bits for each pel within one plane.
  • CAPS_COLOR_TABLE_SUPPORT
Loadable color table support. Has the following values:
    • CAPS_COLTABL_RGB_8
If 1, the RGB color table can be loaded with a minimum support of eight bits each for red, green, and blue.
    • CAPS_COLTABL_RGB_8_PLUS
If 1, the color table can be loaded with more than eight bits for each primary color.
    • CAPS_COLTABL_TRUE_MIX
If 1, true mixing occurs when the logical color table has been realized, providing that the size of the logical color table is not greater than the number of distinct colors supported (see CAPS_COLORS).
    • CAPS_COLTABL_REALIZE
If 1, a loaded color table can be realized.
  • CAPS_MOUSE_BUTTONS
Number of buttons available. A returned value of 0 indicates that there are no buttons available.
  • CAPS_FOREGROUND_MIX_SUPPORT
Foreground mix support. Has the following values:
    • CAPS_FM_OR
Logical OR.
    • CAPS_FM_OVERPAINT
Overpaint.
    • CAPS_FM_XOR
Logical XOR.
    • CAPS_FM_LEAVEALONE
Leave alone.
    • CAPS_FM_AND
Logical AND.
    • CAPS_FM_GENERAL_BOOLEAN
All other mix modes.

The value returned is the sum of the values appropriate to the mixes supported. A device capable of supporting OR must at least return CAPS_FM_OR + CAPS_FM_OVERPAINT + CAPS_FM_LEAVEALONE to signify support for the mandatory mixes OR, Overpaint, and Leave Alone.

These numbers correspond to the decimal representation of a bit string that is six bits long with each bit set to 1 if the appropriate mode is supported. Mixes that are returned as supported are guaranteed for all primitive types. For more information, refer to the function "GpiSetMix" in the Presentation Manager Programming Reference.

  • CAPS_BACKGROUND_MIX_SUPPORT
Background mix support. Has the following values:
    • CAPS_BM_OR
Logical OR.
    • CAPS_BM_OVERPAINT
Overpaint.
    • CAPS_BM_XOR
Logical XOR.
    • CAPS_BM_LEAVEALONE
Leave alone.
    • CAPS_BM_AND
Logical AND.
    • CAPS_BM_SCRTRANSPARENT
Provides for a transparent overlay function by not copying pels that match the presentation space background color from the source bit map to the output bit map.
    • CAPS_BM_DESTTRANSPARENT
Provides for a transparent underlay function by only copying pels that match the presentation space background color from the source bit map to destination pels.
    • CAPS_BM_GENERAL_BOOLEAN
All other mix modes.

If CAPS_BM_SCRTRANSPARENT and CAPS_BM_DESTTRANSPARENT are supported, these values can be selected by calling the function GpiSetBackMix and specifying them as the mix mode. The presentation driver then performs any BitBlt operations (for GreBitblt or GreDrawBits) by first checking the background mix for one of the transparent mix modes. Note that these mixes are performed only on BitBlt operations that do not include a pattern, that is, raster operations that include only the source or destination, or both. If the source bit map is not given, CAPS_BM_SCRTRANSPARENT does not operate and the entire bit map operation area is used.

The returned value is the sum of the values appropriate to the mixes supported. A device must at least return CAPS_BM_OVERPAINT + CAPS_BM_LEAVEALONE to signify support for the mandatory background mixes Overpaint and Leave Alone. These numbers correspond to the decimal representation of a bit string that is four bits long, with each bit set to 1 if the appropriate mode is supported. Mixes that are returned as supported are guaranteed for all primitive types.

CAPS_VIO_LOADABLE_FONTS Number of fonts that can be loaded for VIO.

CAPS_WINDOW_BYTE_ALIGNMENT Indicates whether the client area of VIO windows should be byte-aligned. Has the following values:

CAPS_BYTE_ALIGN_REQUIRED Must be byte-aligned. CAPS_BYTE_ALIGN_RECOMMENDED More efficient if byte-aligned, but not required. CAPS_BYTE_ALIGN_NOT_REQUIRED Does not matter whether byte-aligned.

CAPS_BITMAP_FORMATS Number of bit-map formats supported by device.

CAPS_RASTER_CAPS Capability for device raster operations. Has the following values:

CAPS_RASTER_BITBLT If 1, GpiBitBlt and GpiWCBitBlt are supported. CAPS_RASTER_BANDING If 1, banding is supported. CAPS_RASTER_BITBLT_SCALING If 1, GpiBitBlt and GpiWCBitBlt (with scaling) are supported. CAPS_RASTER_SET_PEL If 1, GpiSetPel is supported. CAPS_RASTER_FONTS If 1, this device can draw raster fonts. CAPS_RASTER_FLOOD_FILL If 1, GpiFloodFill is supported.

CAPS_MARKER_HEIGHT Default marker-box height in pels.

CAPS_MARKER_WIDTH Default marker-box width in pels.

CAPS_DEVICE_FONTS Number of device-specific fonts.

CAPS_GRAPHICS_SUBSET Graphics drawing subset supported; for example, 3 indicates GOCA DR/3.

CAPS_GRAPHICS_VERSION Graphics architecture version number supported; for example, 1 indicates Version 1.

CAPS_GRAPHICS_VECTOR_SUBSET Graphics vector drawing subset supported; for example, 2 indicates GOCA VS/2.

CAPS_DEVICE_WINDOWING Device windowing support. Has the following values:

CAPS_DEV_WINDOWING_SUPPORT If 1, this device supports windowing. Other bits are reserved (0).

CAPS_ADDITIONAL_GRAPHICS Additional graphics support. Has the following values:

CAPS_GRAPHICS_KERNING_SUPPORT If 1, device supports kerning. CAPS_FONT_OUTLINE_DEFAULT If 1, device has a default outline font. CAPS_FONT_IMAGE_DEFAULT If 1, device has a default image font. CAPS_SCALED_DEFAULT_MARKERS If 1, default markers are to be scaled by the marker-box attribute. CAPS_COLOR_CURSOR_SUPPORT If 1, device supports colored cursors. CAPS_PALETTE_MANAGER If 1, device supports palette functions. CAPS_COSMETIC_WIDELINE_SUPPORT If 1, device supports cosmetic thick lines. CAPS_ENHANCED_TEXT If 1, device supports full-font file description and text alignment. Other bits are reserved (0). CAPS_CLIP_FILLS If 1, changes the behavior of the graphics engine to call GrePolyScanline with the COM_PRECLIP flag set. The lines are preclipped when filling areas. This flag should only be returned to the graphics engine version number 0x202 or later (see GreQueryEngineVersion).

CAPS_PHYS_COLORS Maximum number of distinct colors available on the device.

CAPS_COLOR_INDEX Maximum logical color-table index supported for this device. For EGA and VGA drivers, this value is 63.

CAPS_GRAPHICS_CHAR_WIDTH Default graphics character-box width in pels.

CAPS_GRAPHICS_CHAR_HEIGHT Default graphics character-box height in pels.

CAPS_HORIZONTAL_FONT_RES Effective horizontal device resolution in pels per inch (for selecting fonts). For printers, this is the actual device resolution. For displays, it can differ from the actual resolution for reasons of legibility.

CAPS_VERTICAL_FONT_RES Effective vertical device resolution in pels per inch (for selecting fonts).

CAPS_DEVICE_FONT_SIM Identifies which simulations are valid on device fonts. Valid flags are: CAPS_DEVICE_FONT_SIM_BOLD CAPS_DEVICE_FONT_SIM_ITALIC CAPS_DEVICE_FONT_SIM_UNDERSCORE CAPS_DEVICE_FONT_SIM_STRIKEOUT

  • CAPS_LINEWIDTH_THICK
Cosmetic thickness of lines and arcs on this device when fxLineWidth is LINEWIDTH_THICK (refer to the function "GpiSetLineWidth" in the Presentation Manager Programming Reference). The units are in pels. A value of 0 is interpreted as two pels.

Additional information is provided in the device capabilities array for communication between the presentation driver and the graphics engine. For example, the parameter CAPS_ADDITIONAL_GRAPHICS has two extra flags and a CAPS_DEVICE_FONT_SIM field is provided.

The additional flags in CAPS_ADDITIONAL_GRAPHICS are used (in conjunction with the CAPS_FONT_OUTLINE_DEFAULT and CAPS_FONT_IMAGE_DEFAULT flags) by the presentation driver to indicate when the graphics engine manages the transforms and mappings for the default fonts supplied by the driver. These flags are:

  • CAPS_FONT_OUTLINE_MANAGE
Set by the presentation driver to indicate that the graphics engine must manage the default outline font
  • CAPS_FONT_IMAGE_MANAGE
Set by the presentation driver to indicate that the graphics engine must manage the default image font
Note
If the presentation driver supplies the fonts but wants the graphics engine to manage them, it must pass the font address to the graphics engine using GreQueryDevResource.

The CAPS_DEVICE_FONT_SIM field contains flags that the presentation driver sets so that the graphics engine will handle simulations for the default fonts supplied by the driver:

  • CAPS_DEV_FONT_SIM_BOLD
Indicates that the graphics engine should simulate CDEF_BOLD for device fonts
  • CAPS_DEV_FONT_SIM_ITALIC
Indicates that the graphics engine should simulate CDEF_ITALIC for device fonts
  • CAPS_DEV_FONT_SIM_UNDERSCORE
Indicates that the graphics engine should simulate CDEF_UNDERSCORE for device fonts
  • CAPS_DEV_FONT_SIM_STRIKEOUT
Indicates that the graphics engine should simulate CDEF_STRIKEOUT for device fonts.
Note
The font attributes CDEF_xxx are identified by the cdef.fFlags field in the "Character Attributes" bundle (see Character Attributes). In the presentation driver, routines that write character strings should check the cdef.fFlags field to determine whether the call should be passed to the default handling routine in the graphics engine.
paOutData (PLONG) - input
Pointer to an array where information is returned.
cOutData (LONG) - input
Number of items of information to be returned at paOutData.
pInstance (PVOID) - input
Pointer to instance data.
lFunction (ULONG) - input
High-order WORD=flags; low-order WORD=NGreQueryDeviceCaps.

Returns

rc (BOOL) - returns
Return Code.

On completion, the handling routine must return a BOOLEAN value to indicate success or an error.

  • TRUE Successful
  • FALSE Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include: 

PMERR_DEV_FUNC_NOT_INSTALLED 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_QUERY_ELEMENT_NO

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

Calls to GreQueryDeviceCaps would not usually require the handling routine to return data in all fields in the buffer. The parameters lIndex and cOutData identify the offset to the first field and the count of consecutive field for returned data.

Note
In OS/2 2.0, if GreQueryDeviceCaps returns data in the CAPS_DRIVER_VERSION field, the return value must be hex 00000200.

Sample

#define INCL_GRE_DEVICE
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
LONG     lIndex;     /*  Identifies the first item required. */
PLONG    paOutData;  /*  Pointer to an array where information is returned. */
LONG     cOutData;   /*  Number of items of information to be returned at paOutData. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreQueryDeviceCaps. */
BOOL     rc;         /*  Return Code. */

rc = GreQueryDeviceCaps(hdc, lIndex, paOutData,
       cOutData, pInstance, lFunction);
Retrieved from "https://www.edm2.com/index.php?title=GreQueryDeviceCaps&oldid=65677"