DDDR/2 - DBCS Video Driver Support

From EDM2
(Redirected from DBCS Video Driver Support)
Jump to: navigation, search
Display Device Driver Reference
  1. 16-Bit VGA Display Driver
  2. 8514/A Display Driver
  3. 32-Bit VGA Display Driver
  4. 32-Bit Super VGA Display Driver
  5. SVGA Base Video Subsystem
  6. Physical Video Device Drivers
  7. Virtual Video Device Drivers
  8. Seamless Windows Support
  9. PM Palette Management Support
  10. Distributed Console Access Facility (DCAF)
  11. DBCS Video Driver Support
  12. Installing and Configuring Display Device Drivers
  13. Graphics Test Suites
  14. Display Test Tool
  15. VIDEOCFG.DLL Exported Functions
  16. VIDEOPMI.DLL Exported Functions
  17. VIDEO Protect-Mode Interface
  18. Data Types
  19. S3 Display Driver
  20. Notices
  21. Glossary

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

Contents

DBCS Video Driver Support

This chapter describes double-byte character set (DBCS) video driver support. It covers:

  • Developing PM display drivers and making the modifications to implement DBCS enabling
-The device driver font manager and the device font drivers
-Font manager functions
-Font driver functions
  • Modifications to the physical device driver (SCREENDD)
  • Modifications to the base video subsystem components

The glyph points, IDs, and character descriptions for all double-byte character sets except for Kanji pattern and SBCS characters are in Glyph Codes.

PM Display Drivers

DBCS PM display drivers are International Language Support drivers, which means they support both SBCS and DBCS. The PM display driver developed from the DBCS sample code can run on both the SBCS and DBCS versions of OS/2. Developers whose target is a worldwide market (DBCS as well as SBCS countries) can use the DBCS sample code as the base code.

The IBM Developer Connection Device Driver Kit for OS/2 includes samples of 32-bit PM display drivers for VGA and Super VGA. The 32-bit display driver runs only with the 32-bit graphics engine (GRE), but a 16-bit display driver will work with both the 32-bit and 16-bit GREs.

For detailed information on the 32-bit PM display drivers for VGA and Super VGA, see 32-Bit VGA Display Driverand 32-Bit Super VGA Display Driver.

Development of PM Display Drivers

This section covers the development of DBCS 16-bit and 32-bit PM display drivers and the modifications necessary for the display adapter cards and for DBCS enabling. The developer should have a basic knowledge of the PDI ( Presentation Driver Interface), which defines the interface between the graphics engine and the presentation driver. For further information on the PDI, refer to the OS/2 Presentation Device Driver Reference.

Overview of Modifications

There are two kinds of modifications to consider:

Modifications to the display hardware
Modifications to implement enabling of DBCS, which allows the DBCS characters to be displayed on the screen

There are three types of character sets:

DBCS (Double-Byte Character Set)-2-byte Kanji, Hiragana, and Katakana (etc .) character set
SBCS (Single-Byte Character Set)-1-byte alphanumeric (and special characters) character set
MBCS (Mixed-Byte Character Set)-character set containing both DBCS and SBCS characters

Hardware modifications are required when developing a PM display driver for a display card that is not supported by the IBM PM display drivers. If the developer models the display driver design on the VGA/SVGA drivers supplied, then further modifications for DBCS enabling are not necessary because these are provided in the device-independent component.

Hardware Modifications

Generally to support any kind of display card besides VGA, hardware modifications will be required. Most of the functions will need to be checked and modified when a hardware modification is made. Performance may be improved by using the functions supported by the hardware for each individual card.

A PM display driver must support the memory for a bit map and the physical display screen as the target device context. The format of the memory bit map is tailored to the definition of the video memory structure to improve performance. For example, VGA has a four-plane memory structure, and it has the reflective memory bit-map format. This is called planer pixel. There is also a format where one pixel consists of multiple bits in one plane as in the 8514/A. This is called packed pixel. The BITBLT routine for the memory bit map in the sample code does not have any dependencies on the hardware. If the appropriate base code is selected, then it does not have to be modified for differences in the hardware. The BITBLT routine for the physical display screen must be modified depending on the display adapter card.

DBCS Enabling

The sample code (IBMVGA32.DLL) already includes DBCS enabling. If the VGA/ SVGA driver is chosen as the base code then no adaptation for DBCS enabling is required. This is because this code does not have any hardware dependencies. To maintain compatibility among display drivers DO NOT change the enabled code for DBCS. If the VGA/SVGA driver is not used as the base code, then modifications will be necessary to provide DBCS enabling.

The PM display driver handles DBCS characters by calling the font manager (PMNLSFM.DLL). Using the font manager and font driver (PMNLSFD.FDR) for DBCS fonts results in the handling of SBCS proportional fonts. The interface for the font manager is described in Device Driver Font Manager Interface.

Modification Note

It is expected that the modified PM display driver will work in an SBCS environment. This means that the driver will work as an SBCS driver when the OS/2 U.S. version is installed. The following table explains how the PM display driver works under various environments.

Environment (1) (2) (3)
DBCS system code page * * * *
PMNLS.DLL available * * * *
PMNLSFM.DLL available * * * *

DBCS system code page The primary code page in CONFIG.SYS is the DBCS code page

PMNLS.DLL available PMNLS.DLL is loaded

PMNLSFM.DLL available The font manager, PMNLSFM.DLL, is loaded

(1) The PM display driver works as a DBCS driver. The default font is the DBCS font.

(2) The PM display driver works as an SBCS driver. The default font is the SBCS font. When the application requests DBCS fonts, using the appropriate API, like GpiCreateLogFont, DBCS fonts will be displayed.

(3) The PM display driver works as an SBCS driver. The default font is the SBCS font.

PMNLS.DLL This component is unique in the OS/2 DBCS version. It handles unique things for DBCS, such as the code page range of DBCS characters.

Change Items for OS/2 J2.0

This section describes new features added since OS/2 J1.X.

The following changes are common to both SBCS and DBCS.

  • Multiple Virtual DOS Machine (MVDM) is supported.
-Sharing the video resource with the virtual video device driver. ( Coexistence of PM and multiple DOS graphics.) Development of the virtual video device driver is required.
-Seamless Windows is supported. Development of a Windows display driver is required.
  • The bit-map function is extended.
-Windows-compatible bit map format is supported (including run length encoded bit map).
-Changing the size of the bit map is supported.
  • The line mix attribute is extended.
-PolyLine
-PolyShortLine
-PolyScanLine
  • The Palette Manager is supported.
(This function is available only in the 32-bit 256-color display driver.)
-It is possible to program palette functions, like creating, selecting, and realizing palettes.
-Palette color animation is provided.
  • Some parts of the source code are translated to 80386.
-32-bit data handling
-Use of 80386 instructions
-Use of the GS segment register
-Use of the FS segment register (Refer to the OS/2 J2.0 Technical Library Control Program Programming Reference.)
  • The Presentation Driver Interface (PDI) data structure is modified and extended.
-The device context (DC) data structure is modified (the DxxBUNDLE structure is extended).
-The FONTMETRICS data structure is changed.
-The PDI function entries are added.
-Device caps definition is extended. (CAPS_LINE_WIDTH_THICK 3)
  • The size of the device standard icon is changed.
-On a VGA system, it is 32 x 32 dot.
-On a high resolution system (ex. 8514), it is 40 x 40 dot. (In the U.S. OS /2 version, it has been 40 x 40 since OS/2 1.3. On OS/2 1.2, it was 64 x 64 dot.)
  • The font resolution is changed.
-In the VGA system, it is 96 dpi.
-In the high-resolution system (8514, for example), it is 120 dpi.
To support this resolution, the font point size is changed.

The following changes are unique to DBCS.

  • Font support is expanded.
-Proportional fonts are supported.
-Non-zero descender fonts are supported.
-The font selection has expanded (8, 10, 12, 14, 18, and 24 point fonts are provided for each typeface and display resolution).
-The standard point size of the system default font is changed (from 18 point to 12 point).
-Switching to a different system default font is now supported (to support the old applications which have dependencies on fixed pitch fonts).
-Switching VIO fonts (for example, switching between MINCHO and GOTHIC) is supported.
  • DBCS character handling
-More logical handling of MBCS character strings in the PM display driver is supported. (The handling of MBCS characters results in the handling of SBCS proportional fonts by the font manager.)
  • Font Manager is supported. (The part that handles DBCS is separated from the PM display driver and becomes one component.) It handles:
-Management of the font segments for both SBCS and DBCS.
-Management of the font cache.
-Management of the font drivers.

Font drivers are required to support EFDI (Extended Font Drivers Interface) Version 3.

PM Display Driver Fonts

In PM, there are basically two kinds of fonts-raster fonts and outline fonts. Outline fonts are processed by the graphics engine (GRE) using the Intelligent Font Interface (IFI). The images of DBCS raster fonts are managed by the PM device font drivers. These font drivers are managed by the device driver font manager (PMNLSFM.DLL). A PM display driver can process DBCS characters by communicating with the font manager. The font manager was included in PM display drivers to process fonts in versions prior to OS/2 2.0. The following is a description of the relationship between the PM display driver and the font manager.

PM Display Driver and Font Manager Interface

There is no initialization interface between the PM display driver and the font manager. When the PM display driver loads the font manager (using DosLoadModule), the initialization routine runs automatically in the font manager. At initialization the font manager loads the system default fonts. When the PM display driver gets the request to load/unload the font driver from the application, the PM display driver calls the font manager using the load/unload font drivers requests.

To call the font manager, the PM display driver has to get the address of the dispatch table using DosGetProcAddr and then use the function addresses provided in this table. Refer to Device Driver Font Manager Interface for details on this process.

Glyphs

The following section gives an overview of managing the DBCS font environment by using the universal glyph list (UGL) concept.

The glyph codes are defined in the chapter titled Glyph Codes.

UGL Font Resources

PM worldwide version assumes that all countries can manage the font environment by using the UGL (universal glyph list) concept. To implement this concept in a DBCS environment, a DBCS glyph index and UGL MBCS font resources are defined, which consists of 383 SBCS characters and all of the DBCS characters. It is the same as the worldwide versions of DBCS country- unique SBCS characters like KATAKANA. PM already has UGL SBCS font resources, which include 383 characters (for example, Courier, Roman, Swiss).

DBCS/PM implements multiple code page fonts using glyph lists of 383 SBCS characters and DBCS glyphs. DBCS glyph lists extend the glyph set of 'PM383 ' to support the DBCS character set. DBCS glyph list names are defined as follows.

PMJPN-Japanese glyph base
PMKOR-Korean glyph base
PMCHT-Taiwan glyph base

The following figure shows the PM font resources.

DBCSGlyps.png

PM Device Font Drivers

The PM device font driver is the 16-bit DLL that supplies SBCS and DBCS fonts to a PM display driver. The IBM Developer Connection Device Driver Kit for OS/2 includes source code for the following font drivers:

PMNLSFD1.FDR-MINCHO System Font Driver
PMNLSFD2.FDR-MINCHO Draft Font Driver
PS55DM28.FDR-MINCHO 28-dot Font Driver
PS55DM32.FDR-MINCHO 32-dot Font Driver
PS55DM36.FDR-MINCHO 36-dot Font Driver
PMNLSFD3.FDR-GOTHIC System Font Driver
PS55DG28.FDR-GOTHIC 28-dot Font Driver
PS55DG32 FDR-GOTHIC 32-dot Font Driver
PS55DG36.FDR-GOTHIC 36-dot Font Driver

Refer to Device Driver Font Manager Interface for details of the interface to the font drivers.

Gaiji Fonts Support

Gaiji means the font image that the user defines. Sometimes it is referred to as "User Fonts" or "User Defined Fonts."

The Gaiji font support in the PM display driver is actually handled by the font drivers. This is because it is easy to make the font typeface correspond to the Gaiji font resource in the font driver. The font driver has information on handling Gaiji fonts.

The font driver provides the following general functions:

Returning SBCS and DBCS font metrics information
Supplying SBCS font images
Supplying DBCS font images excluding Gaiji
Supplying DBCS Gaiji font images

By expanding the font driver's functions, one PM font can have multiple font data resources. Since Gaiji support is handled by the font driver, it picks up these expanded functions. In OS/2 2.0, the font driver returns the Gaiji font using the following rule: The standard Gaiji data is Gaiji fonts resources for the system default font in OS/2 fullscreen mode (16-dot and 24-dot fonts).

Gaiji font data is handled as follows:

If there is private Gaiji font data, the font driver returns private Gaiji font data.
If there is a standard same-size Gaiji font data, the font driver returns standard Gaiji font data.
If there is standard different-size font data, the font driver returns standard Gaiji font data after scaling.
If there is no Gaiji font data, the font driver returns the default character (double byte space character).

Device Driver Font Manager Interface

PMFONTMAN.png

This section provides:

An overview of font management
Programming information on the PM display driver, the device driver font manager, and DBCS device font drivers.
Descriptions of the programming interfaces and functions

Overview

The DBCS device font is the font that was originally provided by the font driver and managed by the PM display driver. The device driver font manager provides a basic function set to load and manage those DBCS device fonts.

Once a font is loaded, there are no differences between the engine font and the DBCS device font. If the function request is for a DBCS device font, the graphics engine also makes queries for details to the display device driver.

The figure on the right shows how the PM font management mechanism works with the device driver font manager: The figure on the right shows the PM font management mechanism.

Programming Information

The following sections contain DBCS-related information about the PM display driver, the device driver font manager, and the device font drivers.

PM Display Driver

The PM display driver no longer has any DBCS device fonts. All of the DBCS device fonts are provided by the font drivers and supplied to the PM display driver by the font manager.

The PM display driver needs to handle:

Notification to the engine to handle device font management on the device driver side. (This is not true for SBCS drivers.)
Font manager initialization at startup time
Default font selection for GPI and VIO fonts
Font manager invocation according to the PDI (Presentation Driver Interface) function called
SBCS device fonts (system proportional fonts) management

Additionally, the display device driver should include the following functions:

Text query functions (such as TextBox, CharPositions, and WidthTable functions, which are not included in SBCS drivers)
Text parsing according to the code page to use (the parser must call the font manager to construct a valid fontseg when the string includes DBCS code points)

The following functions are no longer needed:

Loading and unloading DBCS device font drivers
Creating and destroying DBCS logical fonts. (These functions are handled by the font manager.)
DBCS handling in text output routine. (The fontseg passed from the font manager is always in the form of SBCS proportional.)
Device Driver Font Manager

The font manager pulls the requested character image from the font driver, caches the image locally, and constructs the SBCS proportional fontseg for the display device driver. The font index for DBCS characters is assigned in the reserved area of the glyph list index space (256 indexes are reserved). The list of font indexes (virtual font indexes) translated by the font manager is then returned to the display device driver.

DBCS Device Font Drivers

Because the font manager requires both the SBCS and DBCS portions of the DBCS device fonts, the font driver must provide both SBCS and DBCS characters for the font.

The DBCS-only font drivers are no longer supported by the font manager for system font purposes.

Initialization

The DBCS device fonts for display device drivers are provided by DBCS font drivers through the device driver font manager. Any DBCS-unique font resources are not bound in the display device driver in resource form.

The system font drivers for system fonts are loaded at initialization time by the font manager. The other optional font drivers can be registered and loaded by the user with WinDBCS APIs. The font drivers to be loaded are described in the OS2.INI profile as follows:

System Font Drivers
ApplicationName: PMNLSFNT
KeyName: font_driver_filename#1
String fully_qualified_pathname#1
KeyName: font_driver_filename#2
String: fully_qualified_pathname#2
Optional Public Font Drivers
ApplicationName: PMNLSFNT_FD
KeyName: font_driver_filename#1
String fully_qualified_pathname#1
KeyName: font_driver_filename#2
String: fully_qualified_pathname#2

The default settings for system font drivers are:

ApplicationName: PMNLSFNT
KeyName: PMNLSFD1
String C:\OS2\DLL\PMNLSFD1.FDR

Note that the device driver font manager supports only font drivers that provide both SBCS and DBCS font resources.

FMDISPATCH

This is the exported address that points to the function dispatch table of the font manager APIs.

DispatchTable

typedef struct _FMDISPATCH {
    LONG (FAR PASCAL*)()    FmQueryFonts;
    LONG (FAR PASCAL*)()    FmOpenFont;
    LONG (FAR PASCAL*)()    FmCloseFont;
    LONG (FAR PASCAL*)()    FmQueryCharAttr;
    LONG (FAR PASCAL*)()    FmCharStr;
    LONG (FAR PASCAL*)()    FmMapCharGlyph;
    LONG (FAR PASCAL*)()    FmLoadFontDriver;
    LONG (FAR PASCAL*)()    FmUnloadFontDriver;
    LONG (FAR PASCAL*)()    FmFlushCache;
} FMDISPATCH;
Remarks

This entry point is exported because the ordinal linking method to the font manager APIs is by DosloadModule / DosGetProcAddr. This entry saves runtime linking operation steps. Do not modify the table content.

Font Manager Functions

This section covers the font manager functions that are pointed to from the dispatch table, FMDISPATCH. They are presented in alphabetic order.

FmCharStr-prepares the font segment for a given list of glyph list indexes
FmCloseFont-notifies the font manager that the font will not be used again until another FmOpenFont is issued for this font
FmFlushCache-flushes the cache for a specified font
FmLoadFontDriver-loads the specified font driver
FmMapCharGlyph-converts the list of code points into glyph list indexes
FmOpenFont-searches for and returns the matching font, using specified font attributes
FmQueryCharAttr-returns the font for the specified glyph list index
FmQueryFonts-returns an array of currently loaded font information that belongs to the set specified
FmUnloadFontDriver-unloads the specified font driver

FmCharStr

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmCharStr (hfm, flOptions, pIndex, count)             |
|                                                          |
+----------------------------------------------------------+

This function prepares the font segment for a given list of glyph list indexes. After that, the font segment will be the same as an SBCS proportional PM font. This is a privileged interface only for a display device driver.

hfm(HFM) (in) 
The font handle returned by FmOpenFont
flOptions(BIT32) (in) 
Option flags
FM_WITH_FONT-Updates glyph list indexes and font definitions. The font images are not constructed.
FM_WITHOUT_FONT-Updates glyph list indexes and font definitions. The font images are also loaded and constructed.
count(LONG) (in) 
Count of indexes. Must be less than or equal to 256. When the font is FM_CACHE_FONT, the length is limited by cbCache in the FMFONTINFO structure, returned by FmOpenFont and FmQueryFonts.
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS
Remarks 
The purpose of this function is to improve display device driver performance. The display device driver has a privilege level that can use the font segment as a cache without copying its contents into the data area locally allocated in the display device driver.

The Font Manager replaces DBCS glyph indexes (and SBCS indexes when FM_ CACHE_FONT is selected) by dynamically defining new SBCS glyph list indexes . Also DBCS font images at the offset address where the new SBCS glyph list index points must be prepared.

After that, the display device driver can treat all of the font images as PM font SBCS proportional characters.

FmCloseFont

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FmCloseFont (hfm)                     |
|                                                          |
+----------------------------------------------------------+

This function notifies the font manager that the font will no longer be used until FmOpenFont is issued for this font.

hfm(HFM) (in) 
The font handle returned by FmOpenFont
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

FmFlushCache

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FmFlushCache (hfm, index)             |
|                                                          |
+----------------------------------------------------------+

This function flushes the cache for a specified font.

hfm (HFM) (in) 
The font handle returned by FmOpenFont
index (ULONG) (in) 
Font glyph list index or -1
Glyph index -Flush cache for specified code point
-1 -Flush cache for all code points
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

FmLoadFontDriver

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmLoadFontDriver (flOptions, szFontDriver)            |
|                                                          |
+----------------------------------------------------------+

This function loads the specified font driver.

flOptions (BIT32) (in) 
Option flags
FM_PUBLIC loads the font driver as public
FM_PRIVATE loads the font driver as private
szFontDriver (PSZ) (in) 
The full path name of the font driver. The maximum length is 128 bytes.
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

FmMapCharGlyph

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmMapCharGlyph (hfm, codepage, pStr, pIndex, strlen)  |
|                                                          |
+----------------------------------------------------------+

This function converts the list of code points into glyph list indexes. It is an optional function because the device driver can do it by itself.

hfm(HFM) (in) 
The font handle returned by FmOpenFont
codepage (LONG) (in) 
The code page of the character string
pStr (PBYTE) (in) 
The address of the character string
pIndex (PINDEX) (in/out) 
The address of the buffer to receive the list of glyph list indexes that was converted. The buffer length is at least two times longer than the string length. This is because the 1-byte SBCS code points are converted to the word glyph indexes.
strlen (LONG) (in) 
The character string length in bytes.
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

FmOpenFont

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FmOpenFont (pfat, pfmFont)            |
|                                                          |
+----------------------------------------------------------+

This function searches for and returns the matching font using specified font attributes, such as facename, average width, and maximum height.

pfat(PFATTR) (in) 
The address of the font attributes. The font attributes structure is the same structure that is passed by Gpi/VioCreateLogFont.
             typedef struct _FATTRS  {
                 USHORT  usRecordLength;            /* length of record        */
                 USHORT  fsSelection;               /* selection indicator     */
                 LONG    lMatch;                    /* match identifier        */
                 CHAR    szFacename[FACESIZE];      /* typeface name           */
                 USHORT  idRegistry;                /* registry identifier     */
                 USHORT  usCodePage;                /* code page               */
                 LONG    lMaxBaselineExt;           /* maximum baseline extent */
                 LONG    lAveCharWidth;             /* average character width */
                 USHORT  fsType;                    /* type indicators         */
                 USHORT  fsFontUse;                 /* font use indicators     */
             } FATTRS;
pfmFont(PFMFONTINFO) (in/out) 
The address of the buffer to receive the matching font information. The font handle is saved in the hfmfield, and the handle value is always the same as pFont (font segment address).
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS
Remarks 
All of the size values returned in font metrics are in device coordinates.

FmQueryCharAttr

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FmQueryCharAttr (hfm, index, pfmData) |
|                                                          |
+----------------------------------------------------------+

This function returns the font for the specified glyph list index.

hfm(HFM) (in) 
The font handle returned by FmOpenFont
index 
Font glyph list index
pfmData(PFMQUERYDATA) (in/out) 
The address of query data. There are three types of query that should be specified in lQuery.
FM_FONT_SIZE-Queries how many bytes the device driver has to allocate to receive the font image and font size. For example, the device driver can get cell width, cell height, and cbLen for a fixed-pitch font.
FM_FONT_IMAGE-Requests font image. The device driver has to allocate the buffer (pointed to by pBuffer) for a font.
FM_FONT_NULL-Requests the null character image. The device driver has to allocate the buffer (pointed to by pBuffer) for a font.
             typedef struct _FMQUERYDATA {
                 BIT32   lQuery;           /* query type                      */
                 LONG    sizl_cx;          /* cell width                      */
                 LONG    sizl_cy;          /* cell height                     */
                 LONG    a_space;          /* A space                         */
                 LONG    b_space;          /* B space                         */
                 LONG    c_space;          /* C space                         */
                 ULONG   cbLen;            /* buffer length for font image    */
                 PBYTE   pBuffer;          /* address of font image buffer    */
             } FMQUERYDATA
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

FmQueryFonts

This function returns an array of currently loaded font information that belongs to the set specified.

flOptions(BIT32) (in) 
Enumeration options
FM_PUBLIC Enumerate public fonts
FM_PRIVATE Enumerate private fonts
pfmFont(PFMFONTINFO) (in/out) 
The address of the buffer to receive an array of font information. If a NULL is specified for this parameter, the function returns the number of fonts currently loaded by the font manager. The returned font segments always have PM font compatible font metrics. The accessibility of font definitions is dependent on the font segment type returned in flType.
FM_PM_FONT-Indicates that the returned font segment is SBCS/PM font compatible. When the font is opened by FmOpenFont, the device driver can read both font metrics and SBCS font definitions directly. The DBCS font definitions are valid just after the font segment is validated with specified glyph indexes by FmCharstr.
FM_CACHE_FONT-Indicates that the font definitions are not resident in this segment. The font definitions are valid just after the font segment is validated with specified glyph indexes by FmCharStr.
The cbCache shows the number of fonts that can be loaded in this font segment at once. This value limits the length of the glyph list index array to be passed to the FmCharStr call. Note that this field is valid only when the font is FM_CACHE_FONT.
             typedef struct _FMFONTINFO {
                 HFM     hfm;                /* font manager font handle        */
                 PBYTE   pFont;              /* pointer to the font segment     */
                 ULONG   ulLen;              /* length of font segment          */
                 BIT32   flType;             /* type flag                       */
                 CHAR    szGlyphlist[16];    /* glyph list name                 */
                 LONG    lMatch;             /* match identifier                */
                 USHORT  cbCache;            /* cache size (FM_CACHE_FONT only) */
             } FMFONTINFO;
hfm (HFM) (in) 
The font handle returned by FmOpenFont. This parameter is used to get the specified font information. When this parameter is specified, it is not necessary to fill the startFont and reqFont parameters . The flOptions parameter should also be specified in this case.
startFont (LONG) (in) 
Starting number of the font that the device driver requests. It begins at 1.
reqFont (LONG) (in) 
The number of fonts that the device driver requests.
RETURN (LONG) 
The number of fonts (if NULL specified for pfmFont) or return codes:
FM_ERROR
FM_SUCCESS
Remarks 
All of the size values returned in font metrics are in device coordinates. The device driver must select GPI/VIO default fonts from the returned list of fonts at initialization time.

FmUnloadFontDriver

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmLoadFontDriver (flOptions, szFontDriver)            |
|                                                          |
+----------------------------------------------------------+

This function unloads the specified font driver.

flOptions (BIT32) (in) 
Option flags
FM_PUBLIC loads the font driver as public
FM_PRIVATE loads the font driver as private
szFontDriver (PSZ) (in) 
The full path name of the font driver. The maximum length is 128 bytes.
RETURN (LONG) 
Return Codes
FM_ERROR
FM_SUCCESS

PM Device Font Driver Interface

A PM device font driver (hereafter referred to as font driver) is a 16-bit ring 3 DLL that supplies DBCS/SBCS raster fonts to the font manager. A font driver expects to be called only from the font manager. The behavior of a font driver is unpredictable when it is called from other modules. Extended Font Driver Interface (EFDI) version 3 is defined as the interface between font drivers and the font manager. EFDI version 1 was used for OS/2 J1.1 and version 2 was used for OS/2 J1.2 and J1.3.

Font drivers are initialized as DLLs at system initialization by the font manager. The entry point name is DynaLinkInit (dllinit.asm).

FONT_ENABLE is the only call gate in the font driver that communicates with the font manager. The font manager loads the font drivers with DosLoadModule and gets each FONT_ENABLE address with DosGetProcAddr.

The following is the general sequence of calling the font drivers.

   ...

   /* Load a font driver. */

   Num = FONT_ENABLE (DBE_FD_OPEN,,,);

   ...

   /* Get information for each font.  */

   for (i = 1; i < Num; i++) {

      ...

      FONT_ENABLE (DBE_FD_GET_INFO,,,i);

      ...

   }

   /* Call each function, specifying the ResourceID for requested fonts */

   ...

   FONT_ENABLE (DBE_FD_GET_INFO,,,);

   ...

   FONT_ENABLE (DBE_FD_QUERY,,,);

   ...

   FONT_ENABLE (DBE_FD_READ,,,);

   ...

   /* Unload a font driver  */

   FONT_ENABLE (DBE_FD_CLOSE,,,);

FONT_ENABLE Function Call Description

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

FONT_ENABLE is the call gate in the font driver that communicates with the font manager

ul1 (ULONG) (in) 
The first input parameter. The meaning of this parameter will change depending on ulFunction.
ul2 (ULONG) (in) 
The second input parameter. The meaning of this parameter will change depending on ulFunction.
ul3 (ULONG) (in) 
The third input parameter. The meaning of this parameter will change depending on ulFunction.
ulFunction (ULONG) (in) 
Function name.
DBE_FD_CLOSE-Closes the font driver
DBE_FD_GET_INFO-Returns information about the fonts specified
DBE_FD_GET_VERSION-Returns the version of the font driver
DBE_FD_OPEN-Opens the font driver
DBE_FD_QUERY-Returns information about the cell of the font specified
DBE_FD_READ-Returns the image of the font specified
DBE_FD_WRITE-Renews the image of the font specified
RETURN (ULONG) 
Return Codes
DBE_FD_NORMAL-Success
DBE_FD_NO_MORE_FONT-No more fonts to return
DBE_FD_ERROR-Error

DBE_FD_CLOSE

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_CLOSE function closes the font driver.

ul1 (ULONG) (in) 
It is not used and will be ignored.
ul2 (ULONG) (in) 
It is not used and will be ignored.
ul3 (ULONG) (in) 
It is not used and will be ignored.
ulFunction (ULONG) (in) 
Function name-DBE_FD_CLOSE
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL -Success
DBE_FD_ERROR -Error

DBE_FD_GET_INFO

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_GET_INFO function returns the attributes of the specified fonts.

ul1 (ULONG) (in) 
Font resource ID.
ul2 (ULONG) (in/out) 
Pointer(PFONT_INFO).

The structure name FONT_INFO is defined in the H_DBCS\OS2NLSFD.H file as follows:

                      typedef struct _FONT_INFO {
                          PFOCAFONT font_info_ptr;
                          ULONG     option;
                      } FONT_INFO, FAR *PFONT_INFO

_FONT_INFO Struct Values of option

        #define DBE_FD_FONT_DEFAULT    0x00000000
        #define DBE_FD_FONT_NO_CACHE   0x00000004
ul3 (ULONG) (in) 
It is not used and will be ignored.
ulFunction (ULONG) (in) 
Function name-DBE_FD_GET_INFO
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL-Success
DBE_NO_MORE_FONT-No font to return
DBE_FD_ERROR-Error

DBE_FD_GET_VERSION

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_GET_VERSION function returns the version of the font driver.

ul1 (ULONG) (in) 
It is not used and will be ignored.
ul2 (ULONG) (in/out) 
Pointer(PFONT_DRIVER_VERSION)

The structure name FONT_DRIVER_VERSION is defined in H_DBCS\OS2NLSFD.H file as follows:

                      typedef struct _FONT_DRIVER_VERSION {
                          ULONG     version_number;
                          PFD_DESC  fd_desc;
                      } FONT_DRIVER_VERSION, FAR *PFONT_DRIVER_VERSION;

The FD_DESC structure is defined in H_DBCS\OS2NLS.H as follows:

                      typedef struct _FD_DESC {
                          ULONG     flType;
                          CHAR      str64Desc[64];
                      } FD_DESC, FAR *PFD_DESC;
ul3 (ULONG) (in) 
It is not used and will be ignored.
ulFunction (ULONG) (in) 
Function name-DBE_FD_GET_VERSION
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL-Success
DBE_FD_ERROR-Error

DBE_FD_OPEN

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_OPEN function opens the font driver.

ul1 (ULONG) (in) 
It is not used and will be ignored.
ul2 (ULONG) (in) 
It is not used and will be ignored.
ul3 (ULONG) (in) 
It is not used and will be ignored.
ulFunction (ULONG) (in) 
Function name-DBE_FD_OPEN
RETURN (ULONG) 
The number of fonts that can be used.

DBE_FD_QUERY

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_QUERY function returns information about the font cell specified by the glyph index.

ul1 (ULONG) (in) 
Font resource ID
ul2 (ULONG) (in/out) 
Pointer(PFONT_QUERY)

The structure name FONT_QUERY is defined in the H_DBCS\OS2NLSFD.H file as follows:

            typedef struct _FONT_QUERY {
                ULONG     QueryID;
                ULONG     xCellWidth;
                ULONG     yCellHeight;
                ULONG     xCellA;
                ULONG     xCellB;
                ULONG     xCellC;
                ULONG     date_length;
            } FONT_QUERY, FAR *PFONT_QUERY;

The values of QueryID are defined as follows:

                      #define DBE_FD_QUERY_WIDTHHEIGHT   0x00000001L
                      #define DBE_FD_QUERY_ABC           0x00000002L
                      #define DBE_FD_QUERY_LENGTH        0x00000004L
ul3 (ULONG) (in) 
Glyph index.
ulFunction (ULONG) (in) 
Function name-DBE_FD_QUERY
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL-Success
DBE_FD_ERROR-Error

DBE_FD_READ

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_READ function returns the font specified by the glyph index.

ul1 (ULONG) (in) 
Font resource ID. This value should be from 1 to the value returned by DBE_FD_OPEN.
ul2 (ULONG) (in/out) 
Pointer(PFONT_MAP).

The structure name FONT_MAP is defined in the H_DBCS\OS2NLSFD.H file as follows:

                      typedef struct _FONT_MAP {
                          USHORT    buffer_length;
                          PUSHORT   buffer_ptr;
                          USHORT    reserved1;
                          PVOID     reserved2;
                          ULONG     input_width;
                          ULONG     input_height;
                          ULONG     output_width;
                          ULONG     output_height;
                      } FONT_MAP, FAR *PFONT_MAP
ul3 (ULONG) (in) 
Glyph index.
For SBCS, the character code should be in the low byte, and 0x00 should be in the high byte.
For DBCS, the leading byte should be in the low byte, and the trailing byte should be in the high byte.
ulFunction (ULONG) (in) 
Function name-DBE_FD_READ
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL-Success
DBE_FD_ERROR-Error

DBE_FD_WRITE

+--- FUNCTION ---------------------------------------------+
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
+----------------------------------------------------------+

The DBE_FD_WRITE function renews the image of the font specified by the glyph index.

ul1 (ULONG) (in) 
Font resource ID.
ul2 (ULONG) (in/out) 
Pointer(PFONT_MAP).
ul3 (ULONG) (in) 
Glyph index.
ulFunction (ULONG) (in) 
Function name-DBE_FD_WRITE
RETURN (ULONG) 
Return codes
DBE_FD_NORMAL-Success
DBE_FD_ERROR-Error

Using the Accelerator Function Between PM and WIN-OS2

When both your PM display driver and your WIN-OS/2 seamless display driver use the graphic accelerator function, you need a proper semaphore control.

The supplement file HWS2S.BLT is the sample for BitBlt handling using hardware assist. HWS2S.BLT is in the \DDK_x86\SRC_DBCS\SEAMLESS directory. The WIN-OS2 display driver should wait until the RAM semaphore pmdd_screen_ busy is not zero before doing BitBlt handling. (The pmdd_screen_busy sempahore is common to the PM display driver and the WIN-OS2 display driver.) After BitBlt handling completes, the hardware-busy flag is set to let the PM display driver use the hardware assist.

It is possible to make a semaphore common to the PM driver and the WIN-OS/2 driver as shown in the sample that follows, where the pmdd_screen_busy semaphore is in the structure PMDD_IO in IPC.INC for the WIN-OS2 driver and in the structure _SM_WINDRV for the PM driver. The sample shows "pmdd_ screen_busy" in a shared RAM area between the PM driver and the WIN-OS2 driver.

Shared RAM Area of PM side (in \DDK_x86\SRC_DBCS\VGA32\VGAINC\SEAMLESS.INC file):

 _SM_WINDRV      struct
     signature           db  "VG01" ; string to synchronize interface to VDM
     exclude             dd  ?      ; pointer to cursor far_exclude() function
     .
     .
     .
     ulLastPalUpdate     dd  ?      ; time stamp of last palette update
     pHWPalette          dd  ?      ; 16:16 ptr to copy of PM driver
HWPalette

     pmdd_screen_busy    dd  ?      ; 16:16 ptr of screen_busy.
<==SEMAPHORE      .
     .
 _SM_WINDRV      ends
 

Shared RAM Area of WIN-OS2 side (in IPC.INC file):

 PMDD_IO  struc
     signature           dd  ?       ; 4bytes to synch interface to PMDD
     pfexclude           dd  ?       ; ptr to PMDD's exclude() function
     .
     .
     .
     ulLastPalUpdate     dd  ?       ; time stamp of last palette update
     pHWPalette          dd  ?       ; 16:16 ptr to copy of PM's HWPalette

     pmdd_screen_busy    dd  ?       ; 16:16 ptr of screen_busy. <==SEMAPHORE
     .
 PMDD_IO  ends

By using the pmdd_screen_busy semaphore field, you can implement exclusive access of the accelerator function as follows:

       .
       .
       .
       mov     ax,DataBASE
       mov     ds,ax
       assumes ds,Data
       lds     si,init_struct.pmdd_io
       lds     si, [si].pmdd_screen_busy
       xor     ax, ax
@@:
       xchg    al, [si]         ; Get the access right.
       or      al, al                     ; Check
       jz      @B                         ; If 1 then OK, else loop.
       .
       .
       .
     ********************************
     * Access Accelerator Function  *
     ********************************
       .
       .
       .
       mov     byte ptr [si], 1 ; Release the access right.

The Physical Device Driver-SCREENDD

To build SCREEN01.SYS and SCREEN02.SYS, run NMAKE.EXE in the DDK_x86\SRC_ DBCS\ DEV\SCREENDD directory.

All source code is included in the IBM Developer Connection Device Driver Kit for OS/2, so modifications to any code can be done, if necessary.

MEMHELP.ASM and DDK_x86\INC_DBCS\MEMHELP.INC are the files newly added for DBCS support.

To support BVHVGA2.DLL, FNTCALLS.DLL and VFNTV.SYS, the new IOCtl and interface to the virtual device driver are added. The following section describes the interfaces added to SCREENDD.

Modifications to SCREENDD for IBM Japan

The following are the major modifications done for DBCS support. In the future, the code may be changed without notice.

  • A new IOCtl is added to allocate a BVHVGA2.DLL shadow buffer and DBCS font buffer in the global memory. There is no API that allocates the ring 3 global memory from the ring 3 program. By using this IOCtl, it is possible to get global memory for a ring 3 program.
  • The interface that maps the local memory to global and releases the global memory called from VDD are added. They are used for sharing the DBCS font resource between VFNTV.SYS and FNTCALLS.DLL.
  • The new IOCtl is added to access the ROM font in the DOS/V machine from ring 3 FNTCALLS.DLL.

IOCtl Added to SCREENDD

The following functions in category 03h IOCtl are added. In the future, the number and function of this IOCtl may be changed.

function 7Eh-Allocate video buffer
function 7Fh-Get address to ROM font

For information on these IOCtl functions, see OS/2 Physical Device Driver Reference.

Interface to VDD Added to SCREENDD

For VFNTV.SYS, the following interface is added. In the future, the number and function of this interface may be changed.

Function 0h Register VDD entry point
Function 1h Map local memory to global
Function 2h Release global memory

Register VDD Entry Point (function 00H)

The "success" return code (AX=1) will always be returned.

Map Local Memory to Global (function 01H)

Parameter 1 (Input):

Field Length
Linear address to be mapped DWORD
Length of memory DWORD

Parameter 2 (Output):

Field Length
Linear address mapped DWORD

Return: AX = 1 Success

AX = 0 Error

Release Global Memory (function 02H)

Parameter 1 (Input):

Field Length
Linear address to be released DWORD

Parameter 2 (Output): None

Return: AX = 1 Success

AX = 0 Error

Base Video Subsystem

The following sections describe changes to the base video subsystem for Japanese support.

Base Video Handler

The Base Video Handler controls the video hardware in OS/2 protect mode. It means that all applications that set the video mode call BVH indirectlty. BVH consists of multiple DLLs.

When the display adapter is VGA, the BVH consists of BVHVGA.DLL and BVHVGA2 .DLL. BVHVGA2.DLL handles the DBCS fonts and BVHVGA.DLL handles the other functions. BVHVGA2I.DLL is the mini BVH used only at system installation.

BVHSVGA.DLL is the BVH for super VGA and is compatible with many kinds of the super VGA chip sets.

BVHWNDW.DLL is the BVH for windowed VIO session.

For more details see OS/2 Physical Device Driver Reference.

Virtual Video Device Driver

The virtual video device driver (Video VDD) handles the virtualization of the video hardware and INT 10H BIOS function for each DOS session.

VVGA.SYS is the video VDD for VGA.
VSVGA.SYS is the video VDD for super VGA.
V8514A.SYS is the video VDD for 8514/A.

SVGA.EXE is the utility program executed from a DOS full screen session. It supplies the mode data, trap register, lock and unlock data to the BVH and VSVGA.SYS.

VVGA.SYS and VSVGA.SYS are enabled for Japanese DBCS and DOS-V support. The combined source can generate both SBCS and DBCS versions. For more details, see Using OS/2 J 2.0. V8514A.SYS is not enabled for Japanese support. For SVGA.EXE, it does not need to be enabled. The DBCS source files contain no adapter-specific references. Enabling new adapters requires changes only to an adapter-specific file such as VVS3.C.

SVGA.EXE sets all possible video modes for BIOS in the video adapter and writes the value of the registers into the \boot drive\OS2\SVGADATA.PMI file.

The statement is as follows:

 SVGA ON|OFF

ON means creating \OS2\SVGADATA.PMI and enabling SVGA support, and OFF means deleting SVGADATA.PMI. When SVGA ON is executed from the DOS window, BIOS cannot set the appropriate SVGA mode because of the virtualization being done by the system. Therefore SVGA.EXE should be run in DOS full screen mode.

The DOS session needs the SVGADATA.PMI file. When the first DOS session is created, the system reads the SVGADATA.PMI file. The existence of this file means that SVGA support is enabled by the SVGA ON command.

SVGADATA.PMI includes the following information.

The current SVGA adapter chip set
SVGA mode that the adapter can set

The following modes are supported:

-640 x 480 / 256 colors
-800 x 600 / 16 colors
-800 x 600 / 256 colors
-1024 x 768 / 16 colors
-1024 x 768 / 256 colors
-132 x 25 text (See Note)
-132 x 43 or 44 text (See Note)

Note: It is text mode on an SBCS code page. Text mode on a DBCS code page will be done by simulation in graphics mode.

  • The values of the video register for each mode. This data will be used for the save and restore of the registers when the session is switched to a different SVGA mode.

For more the details about video VDD, see OS/2 Virtual Device Driver Reference and OS/2 Version 2.0 Volume 2: DOS and Windows Environment. For more details about the Japanese virtual device drivers and the DOS session window manager, see Using OS/2 J2.0.

BVHWNDW.DLL

BVHWNDW.DLL is the module called from BVSCALLS.DLL when a VioXXX API is called in AVIO and the window session (OS/2 Window). It emulates the Vio API call to the Gpi API call on the PM desktop.