Jump to content

Graphics Adapter Device Driver Reference: Difference between revisions

From EDM2
← Older editNewer edit →
Ak120 (talk | contribs)
35,819 edits
Ak120 (talk | contribs)
35,819 edits
No edit summary
Line 17: Line 17:
;[[VIDEOPMI.DLL Exported Functions]]:This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
;[[VIDEOPMI.DLL Exported Functions]]:This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
;[[VIDEO Protect-Mode Interface]]:This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.
;[[VIDEO Protect-Mode Interface]]:This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.
;[[Installing Video Configuration Manager for OS/2]]:This chapter discussed the Video Configuration Manager (VCMAN), the OS/2 operating-system-service module VIDEOCFG.DLL, how video installation and configuration information is stored in a persistent namespace in the Registry; this discussion includes the functions used to install and configure video adapters and monitors.
;[[VIDEOCFG.DLL Exported Functions|Installing Video Configuration Manager for OS/2]]:This chapter discussed the Video Configuration Manager (VCMAN), the OS/2 operating-system-service module VIDEOCFG.DLL, how video installation and configuration information is stored in a persistent namespace in the Registry; this discussion includes the functions used to install and configure video adapters and monitors.


'''Appendixes'''
'''Appendixes'''
Line 51: Line 51:
*The Printer Device Driver Reference
*The Printer Device Driver Reference
*The MMPM/2 Device Driver Reference (Multimedia)
*The MMPM/2 Device Driver Reference (Multimedia)
==VIDEOCFG.DLL Exported Functions==
The VIDEOCFG.DLL shared library represents the video configuration module in OS/2. Resolution, monitor, and refresh configuration methods are standardized, meaning that IBM- and vendor-shipped drivers for different video devices have the same user interface for the video configuration. The configuration of the resolution is handled by Page 1 of the System Icon notebook. The monitor configuration is handled by Page 2 of the System icon notebook. Page 2 is offered whenever the PMI subsystem contains timing information in its mode table and the attached monitor does not support the VESA DDC standard. For DDC monitors, Page 2 is not offered, because the DDC standard provides a software interface for retrieving monitor specifications and no user interaction is required.
Resolution listbox entries are based on the mode table supported by the display driver, as retrieved via the DspQueryDisplayResolutions API. Refresh listbox on Page 1 is offered for each display driver supported mode that has timing information (VerticalRefresh other than 0xFFFF) in the PMI subsystem mode table.
User configuration is recorded at closing of the System object in VIDEO.CFG , a private profiling file. This is a flat file with syntax similar to that of the PMI. The very first VIDEO.CFG is created by the SVGA.EXE utility (both the IBM-shipped version and the SVGAOEM.EXE provided in the DDK for vendor modification) and reflects the detected monitor configuration at install time. The only generic monitor detection built into the utility is that of the VESA DDC standard. For adapter-specific current monitor configuration, the utility has to be modified to "read" the current settings. An alternative approach is to choose and hard code some standard settings as the default monitor configuration. All of the legacy monitors, as well as the original default settings, are stored in the monitor database. The monitor database is composed of MONITOR.DIF and the optional PRIVATE.DIF. The PRIVATE.DIF can be created by vendors performing RIPL install who prefer to leave MONITOR.DIF as a read-only file. .DIF files are flat files with PMI-like syntax and can be edited to correct or add new legacy monitor entries.
VIDEOCFG.DLL also supports a generic display driver configuration, which allows display drivers to declare one or more settings, the type of each setting, possible values, as well as current value of each setting. When the display driver does have a need to handle some user interface, this feature is the preferred method to any custom configuration. The reason it is preferred is that, in the future, with dynamic resolution change and adapter change, the configuration manager will be able to save and restore all of the display driver custom settings. Note that VIDEOCFG does not attempt to understand the nature of each setting, nor is it performing any profiling of the setting changes.
When the feature is exported by the display driver via a DevEscape (see [[#Generic Video Configuration Interface]]), VIDEOCFG provides a "Capabilities" button on Page 1 that opens a notebook with one page dedicated to each declared setting. Help for each setting, if desired, has to be exported by the display driver via a resource module and a resource ID for the help. As the user makes changes to the settings, the display driver is notified at the time the System Icon changes and is responsible for recording ( profiling) the new value. Each time the pages of the settings are opened, VIDEOCFG will query the display driver for the current value of each exported setting.
Current monitor and mode configuration can be queried and changed via the VIDEOCFG's exported APIs, all of which are listed here and prototyped in h\svgadefs. h.
=== Exported Functions ===
The following API services are exported by VIDEOCFG.DLL:
*AddMonitorData
*GetAllMonitors
*GetCurrentCFG
*GetCurrentDesktopMode
*QueryNumMonitors
*SetCurrentCFG
The format and syntax of each of the above functions is shown on the following pages.
=== AddMonitorData ===
====Syntax====
Description:
''AddMonitorData'' adds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR.DIF file.
<pre>#include <svgadefs.h>
MONITORINFO    *pNewMonitorInfo;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;                /*  Return codes. */
rc = AddMonitorData(*pNewMonitorInfo);</pre>
====Parameters====
'''*pNewMonitorInfo'''([[#MONITORINFO]]) - input Pointer to the MONITORINFO data structure.
This parameter points to the [[#MONITORINFO]] data structure that specifies the new monitor definition to add to the database.
'''rc'''(ULONG) - returns Return codes.
0 Function is successful <br />Nonzero Returns one of the following errors:
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT
====Remarks====
None.
=== GetAllMonitors ===
====Syntax====
Description:
''GetAllMonitors'' retrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.
<pre>#include <svgadefs.h>
MONITORINFO    *pMonitors;    /*  Pointer to the array of MONITORINFO data structures. */
PULONG        pulBufferSize;  /*  Specifies the size of the pMonitors buffer, in bytes. */
ULONG          rc;            /*  Return codes. */
rc = GetAllMonitors(*pMonitors, pulBufferSize);</pre>
====Parameters====
'''*pMonitors'''(MONITORINFO) - output Pointer to the array of [[#MONITORINFO]] data structures.
This parameter points to the array of MONITORINFO data structures that receive all the monitor definitions in the MONITOR.DIF file.
'''pulBufferSize'''(PULONG) - output Specifies the size of the ''pMonitors''buffer, in bytes.
If the buffer size is too small to contain all monitor definitions, the ERROR_NOT_ENOUGH_MEMORY error is returned. The variable is then given the size of the buffer required in order to contain all monitor definitions.
'''rc'''(ULONG) - returns Return codes.
0 Function is successful <br />Nonzero Returns one of the following errors:
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT <br />ERROR_NOT_ENOUGH_MEMORY
=== GetAllMonitors - Remarks ===
None.
=== GetCurrentCFG ===
Description:
''GetCurrentCFG''gets the current video configuration stored in the Registry.
<pre>#include <svgadefs.h>
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
rc = GetCurrentCFG(*pAdapter, *pMonitor);</pre>
=== GetCurrentCFG - Parameters ===
'''*pAdapter'''(ADAPTERINFO) - output Pointer to the [[#ADAPTERINFO]] data structure.
This parameter points to the data structure receiving the current video adapter information.
'''*pMonitor'''(MONITORINFO) - output Pointer to the [[#MONITORINFO]] data structure.
This parameter points to the data structure receiving the current video monitor information.
'''rc'''(ULONG) - returns Return codes.
0 Function is successful <br />Nonzero Returns one of the following errors:
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
=== GetCurrentCFG - Remarks ===
None.
=== GetCurrentDesktopMode ===
Description:
''GetCurrentDesktopMode''retrieves the current desktop mode information stored in the Registry. The desktop mode information includes X and Y resolutions, bits per pixel, vertical and horizontal refresh rates, vertical and horizontal polarity positives, and screen top, bottom, left, and right.
<pre>#include <svgadefs.h>
VIDEO_ADAPTER    *pVideoAdapter;  /*  Pointer to the VIDEO_ADAPTER data structure. */
ULONG            rc;              /*  Return codes. */
rc = GetCurrentDesktopMode(*pVideoAdapter);</pre>
=== GetCurrentDesktopMode - Parameters ===
'''*pVideoAdapter'''(VIDEO_ADAPTER) - output Pointer to the [[#VIDEO_ADAPTER]] data structure.
This parameter points to the data structure receiving the desktop mode information.
'''rc'''(ULONG) - returns Return codes.
TRUE Function is successful <br />FALSE Function is unsuccessful.
=== GetCurrentDesktopMode - Remarks ===
None.
=== QueryNumMonitors ===
Description:
''QueryNumMonitors'' queries the number of monitor defintions available.
<pre>#include <svgadefs.h>
PULONG    pulNumMonitors;  /*  Pointer to variable receiving the number of monitor definitions. */
ULONG    rc;              /*  Return codes. */
rc = QueryNumMonitors(pulNumMonitors);</pre>
=== QueryNumMonitors - Parameters ===
'''pulNumMonitors'''(PULONG) - output Pointer to variable receiving the number of monitor definitions.
'''rc'''(ULONG) - returns Return codes.
0 Function is successful <br />Nonzero Returns the following error:
<br />ERROR_NO_MONITOR_SUPPORT
=== QueryNumMonitors - Remarks ===
None.
=== SetCurrentCFG ===
Description:
''SetCurrentCFG''sets the current video configuration in the Registry.
<pre>#include <svgadefs.h>
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
rc = SetCurrentCFG(*pAdapter, *pMonitor);</pre>
=== SetCurrentCFG - Parameters ===
'''*pAdapter'''(ADAPTERINFO) - input Pointer to the [[#ADAPTERINFO]] data structure.
This parameter points to the data structure that specifies the current adapter configuration to be set in the Registry.
'''*pMonitor'''(MONITORINFO) - input Pointer to the [[#MONITORINFO]] data structure.
This parameter points to the data structure that specifies the current monitor configuration to be set in the Registry.
'''rc'''(ULONG) - returns Return codes.
0 Function is successful <br />Nonzero Returns one of the following errors:
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
=== SetCurrentCFG - Remarks ===
None.
==Generic Video Configuration Interface==
The Video Configuration Manager supports a generic video configuration interface that allows any display driver to interface with the user via notebook settings in the System icon. The driver needs to export DevEscape calls that identify the capability. The driver also needs to provide DevEscape calls that allow the VIDEOCFG to query the current value and notify the driver when the user sets the value. The DevEscape functions are invoked as Ring3. The method of recording the current setting, as well as default values, is at the driver's discretion.
=== GreEscape DEVESC_QUERYDRIVERCAPS ===
'''Simulation support:'''
This function is optional for display drivers and has no simulation support .
Description:
''GreEscape DEVESC_QUERYDRIVERCAPS''returns the capabilities descriptions. The values for each capability are not yet allocated and are queried later. The #define DEVESC_QUERYDRIVERCAPS (4010L) is defined in SVGADEFS.H.
<pre>#define INCL_GRE_DEVICE
#include <GRADD.h>
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPS */
LONG    lInCount;    /*  Not used. */
PBYTE    pbInData;    /*  Not used. */
PLONG    plOutCount;  /*  The number of bytes of data pointed to by pbOutData. */
PBYTE    pbOutData;  /*  The address of a buffer that will contain a ULONG variable
                          specifying the number of capabilities. */
LONG    rc;          /*  Return Code. */
rc = GreEscape(hdc, lCode, lInCount, pbInData, plOutCount, pbOutData);</pre>
;Parameters
:'''hdc'''(HDC) - input A handle to the device context.
:'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPS
:'''lInCount'''(LONG) - input Not used.
:'''pbInData'''(PBYTE) - input Not used.
:'''plOutCount'''(PLONG) - output The number of bytes of data pointed to by ''pbOutData.''
::On return, this is updated to the number of bytes returned.
:'''pbOutData'''(PBYTE) - output The address of a buffer that will contain a ULONG variable specifying the number of capabilities.
::On return, this buffer contains a ULONG variable that specifies the number of capabilities that the driver supports, immediately followed by an array of [[#DRIVERCAPS]] structures.
:;Note:This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System icon).
:'''rc'''(LONG) - returns Return Code.
::Returns NO_ERROR.
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST ===
'''Simulation support:'''
This function is optional for display drivers and has no simulation support .
Description:
''GreEscape DEVESC_QUERYDRIVERCAPSLIST''fills the ''pValueList, pCurrentValue,''and ''pDefaultValue''in the [[#DRIVERCAPS]] data structure. The members must be 0 padded up to the ''ulValueMemberSize''in the ''pValueList.''
There are three kind of data types that we are supporting at the present time-boolean, aggregate of int values, and aggregate of strings. These data types are defined as follows:
<pre>  #define  CAPSTYPE_BOOLEAN                  1L
  #define  CAPSTYPE_AGGREGATE_INT        2L
  #define  CAPSTYPE_AGGREGATE_STRING    3L</pre>
<pre>#define INCL_GRE_DEVICE
#include <GRADD.h>
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPSLIST */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
;Parameters
:'''hdc'''(HDC) - input A handle to the device context.
:'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPSLIST
:'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
:'''pbInData'''(PBYTE) - input Pointer to a [[#DRIVERCAPS]] data structure.
::The DRIVERCAPS data structure specifies the driver capability to query. Storage is already allocated for ''pValueList, pCurrentValue,''and ''pDefaultValue.''
::When ''ulCapsType''= CAPSTYPE_BOOLEAN, the driver does not have to fill ''pValueList.''
:'''plOutCount'''(PLONG) - output Not used.
:'''pbOutData'''(PBYTE) - output Not used.
:'''rc'''(LONG) - returns Return Code.
::Returns NO_ERROR.
=== GreEscape DEVESC_SETDRIVERCAPSVALUE ===
'''Simulation support:'''
This function is optional for display drivers and has no simulation support .
Description:
''GreEscape DEVESC_SETDRIVERCAPSVALUE''will set the value that user has selected. The new value is specified in ''pCurrentValue.''
When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type -Boolean type is represented by a check box and aggregate type is represented by a listbox. The capability description appears as the title for that control.
If the driver is going to support these capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggreate strings, if applicable, from a resource module that contains already- translated strings.
<pre>#define INCL_GRE_DEVICE
#include <GRADD.h>
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_SETDRIVERCAPSVALUE */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
rc = GreEscape(hdc, lCode, lInCount, pbInData, plOutCount, pbOutData);</pre>
;Parameters
:'''hdc'''(HDC) - input A handle to the device context.
:'''lCode'''(LONG) - input DEVESC_SETDRIVERCAPSVALUE
:'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
:'''pbInData'''(PBYTE) - input Pointer to a [[#DRIVERCAPS]] data structure.
::The DRIVERCAPS data structure specifies the driver capability to set.
:'''plOutCount'''(PLONG) - output Not used.
:'''pbOutData'''(PBYTE) - output Not used.
:'''rc'''(LONG) - returns Return Code.
::Returns NO_ERROR.
=== How to Write to Windows Profiling Files in OS/2 ===
Some display drivers must perform windows profiling (updates to SYSTEM.INI or WIN.INI file). The following sample source file can be included in display driver source and executed at ring 3 only.
<pre>
    typedef ULONG APIENTRY WPF1(VOID);
    typedef WPF1 *PWPF1;
    typedef BOOL  APIENTRY WPF2(ULONG, BOOL);
    typedef WPF2 *PWPF2;
    typedef BOOL  APIENTRY WPF3(ULONG, PSZ);
    typedef WPF3 *PWPF3;
    BOOL UpdateWindowsIniFiles(VOID)
    {
      BOOL    result = TRUE;
      BOOL    res1;
      ULONG  hWpf;
      CHAR    szUpdateString[256];
      PWPF1  pWpfOpenProfileList;
      PWPF2  pWpfCloseProfileList;
      PWPF3  pWpfWriteProfileListLine;
      HMODULE hMod;
      if (DosLoadModule(NULL, 0, "WINPRF", &hMod) ||
          DosQueryProcAddr(hMod, 0, "WPFOPENPROFILELIST", (PFN *)&pWpfOpenProfileList) ||
          DosQueryProcAddr(hMod, 0, "WPFCLOSEPROFILELIST", (PFN *)&pWpfCloseProfileList) ||
          DosQueryProcAddr(hMod, 0, "WPFWRITEPROFILELISTLINE", (PFN *)&pWpfWriteProfileListLine))
      {
          return FALSE;
      }
      // Open the profile handler.
      if (hWpf = (*pWpfOpenProfileList)())
      {
      /*
      ** szUpdateString has the following format
      **
      ** <profile name>  <section>  <keyword>  [value]
      **
      ** ex.  "system.ini boot sdisplay.drv wd3116sl.drv"  will insert the line
      **    sdisplay.drv=wd3116sl.drv in the boot section of system.ini
      **
      ** if [value] is omitted, the <keyword> is deleted from the section
      */
          if (!(*pWpfWriteProfileListLine)(hWpf, szUpdateString))
          {
            result = FALSE;          // Win Ini update failed!
          }
          res1 = (*pWpfCloseProfileList)(hWpf, result); // Close or abort the updates
          result &= res1;
      }
      else
      {
          result = FALSE;
      }
      return result;
  }</pre>
==Most Frequently Asked Video Configuration Questions and Answers==
How does the user configure monitor, resolution, and refresh in OS/2? The user interface for video configuration is located in the System object member of the System Setup folder, which can be brought up by clicking the right mouse button on the desktop area.
Why use the System Icon monitor configuration vs. custom configuration? System Icon provides a large pool of legacy monitors and a consistent device-independent resolution/refresh/monitor configuration. The OS/2 Warp, Version 3.0 System Icon configuration support can be installed on OS/2 2.1 and will be supported on future versions of OS/2. The Sysem Icon's initial configuration reflects the configuration that was performed by the BIOS.
What other video configuration features are supported by the System Icon? VIDEOCFG, the binary module that owns the System's video pages, also has a generic capability interface. This generic interface allows for expansion of configuration if a vendor needs additional pages, such as a page for font selection, orientation selection, or any other discrete value configuration.
What is needed to get the System Icon to display the monitor list? The mode table exported by the PMI subsystem has to have at least one graphics mode with a [MonitorModeInfo] section. The presence of this graphics mode indicates that the base video system can take into account monitor capabilities.
What is needed to get the System Icon to display the Monitor size button? The PMI subsystem mode table has to have at least one mode with startup values for ScreenLeftEdge, ScreenRightEdge and so forth. The support for monitor sizing is disabled in the DDK version of the VIDEOCFG, but a refresh of the VIDEOCFG is available on request.
How are monitor capabilities described in OS/2? OS/2 has a pre-built database of about 300 monitors. The list is ordered alphabetically by monitor manufacturer name. Each monitor is described in terms of the resolutions it supports and the maximum refresh value for each resolution. The syntax does not allow for optimum or multiple timing choices. The database is a flat file, MONITOR.DIF, that can be modified. VIDEOCFG.DLL exports APIs that allow for monitor database queries and expansion.
Where is the current configuration stored? Current monitor configuration capabilities, as well as the current refresh for each mode and screen sizing information, are stored in a flat file, VIDEO.CFG, whose syntax is very similar to PMI. The content can be queried or changed by calling VIDEOCFG.DLL's configuration APIs.
Where does the default monitor come from? SVGA.EXE (SVGAOEM.EXE) formats the very first VIDEO.CFG that communicates to the configurator the current refresh configuration, as left by the BIOS. We have assembled per-adapter information that lets us understand how each vendor records its refresh configuration. These values are formatted into the VIDEO.CFG. If SVGA.EXE does not format the file, the very first monitor from the MONITOR.DIF database is chosen. Otherwise, the original (default) VIDEO.CFG monitor capabilities are added to the MONITOR.DIF so that the customer can go back to the BIOS-configured monitor capabilities.
Is there DDC support? SVGA.EXE (and SVGAOEM.EXE) and the configuration do support the DDC1 standard. SVGA.EXE formats the VIDEO.CFG with the DDC1- queried capabilities and marks the monitor as DDC. This automatically excludes any monitor from the database. As a result, the customer is not offered monitor selection page, but does have refresh choices per mode on Page 1. In order to change from a DDC monitor to a non-DDC monitor, the customer has to do one of the following:
*Change the current VIDEO.CFG's monitor name from the "DDC" keyword to anything else
*Issue a SetCurrentCFG API into the VIDEOCFG.DLL and specify a name other than DDC for the current monitor's name
*Remove VIDEO.CFG will also enable the monitor selection.
Where do the refresh values in the refresh listbox on Page 1 come from? The resolutions offered represent the resolutions returned by the display driver that are also available from the PMI subsystem. The match is done on horizontal and vertical resolution and color depth (NOT pixel depth).
If at least one of the resolutions in this group has a [MonitorModeInfo] section, the refresh box will be offered. The content of the refresh box is tied into the currently selected resolution. The refresh values are those found in the VIDEOPMI's mode query list that are within the range of the currently selected monitor. The highlight (default) is on the highest value in the listbox (unless overridden by the customer). Changing the selected monitor affects the range and elicits immediate change if the range has been diminished. If the range is increased, the configured refresh remains the same and has to be increased by the customer, if so desired.
What does "DEFAULT" entry in the refresh listbox mean? If the very first VIDEO.CFG has 0xFF for the resolutions vertical refresh, the entry "DEFAULT" will be highlighted in the refresh box. The actual set mode will also pass the 0xFF in the mode structure, so that the selection of the refresh is entirely up to the PMI subsystem (PMI file or imported binary that handles the setmode function). The "DEFAULT" can be used in places where the startup configuration of an adapter is not known at first, but the base video subsystem has ways of setting appropriate (non-harmful) refresh values. If the SVGADATA.PMI contains [MonitorModeInfo] sections with refresh entries other than 0xFF, the refresh listbox will also contain those, but the customer has to override the default highlight. As soon as an actual (non-DDC) monitor is chosen, the DEFAULT will no longer be a valid option in the refresh listbox. Going back to the original monitor "DEFAULT" would put the "DEFAULT" refresh entry into the listbox.
How could a vendor be noncommittal about the refresh values it supports? The vendor could provide a single [MonitorModeInfo] section that represent its highest refresh capability. This information will be filtered against the monitor's capabilities (the monitor's range is always the highest refresh entry), which effectively notifies the customer that only one ( highest capability of the monitor) refresh can be offered. The vendor could specify its [MonitorModeInfo] entry to be so high that no monitor is discriminated against. However, we strongly recommend that the monitor's refresh value passed into the setmode be respected and set as close as possible. There is the potential for some legal problems if the values requested are not within a margin. Regulations, such as ISO 9000 specifications, are established and enforced by countries where our product is sold, not by IBM.
Could the OS/2 configuration serve to configure BIOS/WIN-OS2? If the setmode function servicing the requested refresh also sets configuration registers used by the BIOS / WIN-OS2 driver before or after it changes the clock registers, this will affect non-OS2 mode sets as well. It is not recommended that non-OS2 applications read the VIDEO.CFG, as its format is open to change. The GetCurrentCFG and GetCurrentDesktopMode APIs are exported by the VIDEOCFG.DLL for OS/2 applications so that the current monitor capabilities and current resolution/refresh/monitor sizing values can be read.
How can new monitors be added to the list? A new monitor can be added by using the AddMonitorData API exported by the VIDEOCFG or by manually editing the MONITOR.DIF file. A PRIVATE.DIF file with new monitor entries will accomplish the same thing while keeping MONITOR.DIF as read-only.
Are customers configuring their monitors or the refresh in OS/2? The answer is both, if the vendor's PMI file has more than one [MonitorModeInfo] section per mode. In other words, after selecting the monitor, the customer still has multiple refresh choices if the PMI file had multiple refresh entries for the current mode below the monitor's end-of-range. Some vendors have utilities that are geared towards monitor configuration (a somewhat limited monitor list is usually the problem) and some are geared towards the refresh value setting (most users have a hard time understanding what the refresh means). We have a two-pronged configuration which, in the absence of DDC, lets the user choose a monitor as a way of limiting the highest refresh, and still select one of the more standard timings for a given resolution.
How can the System Icon refresh support be installed on OS/2 2.1? In order to install VIDEOCFG on OS/2 2.x, the VCFGINST.EXE utility provided in the video\bin directory should be executed first. This utility installs WPVIDSYS.DLL, which subclassed WPSYSTEM class to VIDEOCFG.DLL. Both WPVIDSYS.DLL and VIDEOCFG.DLL should be copied into the LIBPATH and will become active upon a reboot following the VCFGINST.EXE. There used to be a version of VIDEOCFG for OS/2 2.x called VIDEOCFG.206. This version is now consolidated into VIDEOCFG.DLL, so a single library can be installed on both versions of the operating system.
You can also download the S3_864.ZIP from CompuServe, OS2SUP library 23 ( search for 86C84 and UPGRADE keywords). This package supports S3 864/964 and 764 and showcases the installation on OS/2 2.x. The 764 driver also uses VIDEOPMI's software interrupt services.


==OS/2 Version Compatibility Considerations==
==OS/2 Version Compatibility Considerations==
Line 470: Line 58:
'''OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)'''
'''OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)'''


'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:'''INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:''' INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.


This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

Revision as of 20:14, 12 July 2019

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

About This Book

The Graphics Adapter Device Driver (GRADD) Reference supports OS/2 Warp on the Intel hardware platform. The information in this book describes the GRADD driver model, how the related components work together, and why the GRADD model enhances OS/2 Warp device-driver support.

Detailed descriptions of control structures, data structures, and I/O formats have been included to help you understand and use the interfaces.

Developers using this book should be familiar with the C or assembler programming language and the OS/2 operating system.

How This Book is Organized

This book includes the following chapters and supporting appendixes:

Introduction to Graphics Adapter Device Drivers
This chapter briefly describes the design philosophy of the GRADD Model.
GRADD Model Components
This chapter provides details on each of the components and how they work together within the GRADD Model.
Video Manager
This chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each.
Graphics Adapter Device Drivers
This chapter describes the device driver interface (DDI) for a GRADD, how and when to add extensions, and detailed description of each Graphics Hardware Interface function. In addition, this chapter describes the Enhanced Direct Interface Video Extension (EnDIVE) functions.
VIDEOPMI.DLL Exported Functions
This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
VIDEO Protect-Mode Interface
This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.
Installing Video Configuration Manager for OS/2
This chapter discussed the Video Configuration Manager (VCMAN), the OS/2 operating-system-service module VIDEOCFG.DLL, how video installation and configuration information is stored in a persistent namespace in the Registry; this discussion includes the functions used to install and configure video adapters and monitors.

Appendixes

Appendix A. OS/2 Version Compatibility Considerations
This appendix describes information in terms of version compatibility.
Appendix B. Syntax Conventions
This appendix indicates the conventions that have been used for the parameter names found in the data types.
Appendix C. Data Types
This appendix contains a description of the parameters for all the data types called by the Video Manager Interface, the Graphics Hardware Interface, the Video Configuration Manager, and the Protect-Mode Interface.
Appendix D. Notices
This appendix contains legal notices.
Miscellaneous
A glossary and an index are included.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE." You are encouraged to use the DUDE to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DUDE, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com
US/Canada: 800-627-8363
International: 770-835-9902
International Fax: 770-835-9444

Ordering Information

For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.

  • The Physical Device Driver Reference
  • The Storage Device Driver Reference
  • The Input/Output Device Driver Reference
  • The Pen for OS/2 Device Driver Reference
  • The Virtual Device Driver Reference
  • The Presentation Device Driver Reference
  • The Display Device Driver Reference
  • The Printer Device Driver Reference
  • The MMPM/2 Device Driver Reference (Multimedia)

OS/2 Version Compatibility Considerations

This version of the GRADD Reference was written to support OS/2 Warp on the Intel hardware platform.

Notices

OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(C) Copyright International Business Machines Corporation 1996. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both: 

IBM
Multimedia Presentation Manager/2
OS/2
OS/2 Warp 
Personal System/2
PowerPC 
Presentation Manager 
PS/2
WIN-OS/2
Workplace Shell 
XGA

The following terms are trademarks of other companies:

Trademark Owner
ATI ATI Technologies, Inc.
Cirrus Logic Cirrus Logic, Inc.
MASM Microsoft Corporation
PCMCIA Personal Computer Memory Card International Association
S3 S3 Incorporated
SVPMI Super VGA Protect Mode Interface
VDM Geographics Systems, Ltd.
VESA Video Electronics Standards Association
Viper VLB Diamond Computer Systems, Inc.
Weitek Weitek Corporation

Windows is a trademark of Microsoft Corporation

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

Retrieved from "https://www.edm2.com/index.php?title=Graphics_Adapter_Device_Driver_Reference&oldid=63406"