Jump to content

Display Device Driver Reference for OS/2: Difference between revisions

From EDM2
← Older editNewer edit →
No edit summary
No edit summary
Line 13: Line 13:
[[#8514/A Display Driver]] This chapter covers the differences between the 16- bit VGA display driver and the 8514.
[[#8514/A Display Driver]] This chapter covers the differences between the 16- bit VGA display driver and the 8514.


[[#32-Bit VGA Display Driver]] This chapter presents the 32-bit VGA driver, contained in two Dynamic Link Libraries: one hardware-independent, the other hardware-dependent.
[[32-Bit VGA Display Driver]] This chapter presents the 32-bit VGA driver, contained in two Dynamic Link Libraries: one hardware-independent, the other hardware-dependent.


Also described are the responsibilities of the driver to the Presentation Manager graphics engine, which loads the Dynamic Link Libraries for the display driver.
Also described are the responsibilities of the driver to the Presentation Manager graphics engine, which loads the Dynamic Link Libraries for the display driver.
Line 438: Line 438:
     |                                                        |
     |                                                        |
1023 \--------------------------------------------------------/</pre>
1023 \--------------------------------------------------------/</pre>
== 32-Bit VGA Display Driver ==
The 32-bit VGA display driver, like all display drivers, provides hardware independence for OS/2 application programs needing to perform I/O to a display device.
=== Overview ===
The 32-bit VGA display driver is contained in a pair of DLLs, which are divided into hardware-dependent and hardware-independent sections. When an application needs to perform I/O to a display device, it calls a system DLL , which in turn calls the OS/2 Presentation Manager graphics engine, PMGRE. DLL. PMGRE is the component that loads the display-driver DLLs.
The display driver has certain responsibilities to the graphics engine (GRE ). Specifically, there are a number of entry points (''external functions'') in the graphics engine that the display driver is required to hook and support . There are other entry points in the graphics engine that can be optionally hooked by the display driver, when required, for special processing.
Each entry point is a 32-bit pointer to a specific routine in the graphics engine. The graphics engine uses a ''dispatch table''to call the entry points within the display driver. Essentially, the dispatch table is a block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. The graphics engine then refers to the dispatch table anytime it calls a function in the display driver.
Initially, however, the dispatch table entries point back to routines in the graphics engine. Therefore, the display driver must replace some of the existing pointers with new pointers that point to corresponding routines in the display driver. This action is mandatory for some routines, optional for others. The display driver hooks the entry points in the dispatch table the first time the driver is called at its OS2_PM_DRV_ENABLE entry point for the first subfunction, FillLogicalDeviceBlock.
The ''ring level''(privilege level) of all the entries in the dispatch table can be selected by exporting a table called OS2_PM_DRV_RING_LEVELS. If this table is not exported, all 32-bit functions are dispatched as conforming to Ring 2.
=== 32-Bit VGA Display Driver Architecture ===
The 32-bit VGA display driver consists of two fundamental components. They are:
*IBMVGA32.DLL
*IBMDEV32.DLL.
This architecture was chosen to make the driver more easily portable among various hardware video cards. Super VGA support is provided by using this architecture.
The device-independent functions of the driver are contained in the base DLL, IBMVGA32.DLL. This DLL satisfies entry points common to different hardware cards. The device-specific functions are contained in the device- specific DLL, IBMDEV32.DLL. This DLL satisfies entry points specific to video adapter cards. The graphics engine calls entry points in both DLLs. Also, the two DLLs call exported entry points within each other. In order to port this driver to other video cards, you must write code that supplies the functionality for the entry points in the device-specific DLL. Fonts are now built in a separate DLL, DSPRES.DLL.
DSPRES.DLL is the dynamic link library that supplies the resources such as fonts, pointers, etc. to the display driver. DSPRES.DLL includes resources for both high resolution and low resolution. The IBMDEV32.DLL exports the pointers to the structures for FONT_RES, defFontChar, and defFontMarker, which have the resource IDs of the necessary resources. IBMVGA32.DLL loads DSPRES.DLL, gets the resources with DosGetResource (using the resource ID in defFontXX imported from IBMDEV32.DLL) and saves the pointer to the resources in defFontXX.
The architecture of the 32-bit VGA display driver is illustrated in the following figure: [Artwork not shown]
=== Base DLL Function Imports ===
The GRE uses entry points in both IBMVGA32.DLL and IBMDEV32.DLL. IBMVGA32. DLL also calls entry points in IBMDEV32.DLL. The device-specific DLL contains a number of entry points required by the GRE and a number of device-specific API calls.
These device-specific API calls supply the functionality expected by the base DLL. In order to port this driver to other video cards, the developer must write code which supplies the functionality for the entry points in the device-specific API. These routines are discussed in the following pages.
'''Note:'''All functions in the base and device-specific DLLs run at Ring 2 with the exception of ''QueryDeviceBitmaps, QueryDeviceCaps, QueryHardcopyCaps,''and ''QueryDevResource2'', which run at Ring 3.
The following functions are imported by the base DLL from the device-specific DLL:
init_hw_regs =IBMDEV32.4000 <br />rgb_to_ipc =IBMDEV32.4004 <br />physical_enable =IBMDEV32.4011 <br />physical_disable =IBMDEV32.4012 <br />device_specific_init =IBMDEV32.4013 <br />device_specific_post_init =IBMDEV32.4014 <br />copy_bits_to_pattern =IBMDEV32.4017 <br />PolyShortLine =IBMDEV32.4023 <br />SaveScreenBits =IBMDEV32.4026 <br />PolyScanline =IBMDEV32.4028 <br />RestoreScreenBits =IBMDEV32.4030 <br />Pixel =IBMDEV32.4034 <br />far_exclude =IBMDEV32.4037 <br />far_unexclude =IBMDEV32.4038 <br />SetColorCursor =IBMDEV32.4039 <br />DeviceSetCursor =IBMDEV32.4040 <br />SetScreenBusy =IBMDEV32.4041 <br />CharRect =IBMDEV32.4200 <br />CharStr =IBMDEV32.4201 <br />DeviceSetAVIOFont2 =IBMDEV32.4202 <br />ScrollRect =IBMDEV32.4204 <br />UpdateCursor =IBMDEV32.4205 <br />DeviceSeamlessInit =IBMDEV32.4206 <br />deselect_bitmap =IBMDEV32.4301 <br />save_bitmap =IBMDEV32.4302 <br />DeviceCreateBitmap =IBMDEV32.4303 <br />DeviceSelectBitmap =IBMDEV32.4304 <br />DeviceDeleteBitmap =IBMDEV32.4305 <br />GetBitmapBits =IBMDEV32.4306 <br />SetBitmapBits =IBMDEV32.4307 <br />DrawLinesInPath =IBMDEV32.4308 <br />DisJointLines =IBMDEV32.4309 <br />PolyLine =IBMDEV32.4310 <br />GetCurrentPosition =IBMDEV32.4311 <br />SetCurrentPosition =IBMDEV32.4312 <br />CharString =IBMDEV32.4313 <br />Drawbits =IBMDEV32.4314 <br />ImageData =IBMDEV32.4315 <br />CharMarkerPos =IBMDEV32.4316 <br />CharStringPos =IBMDEV32.4317 <br />Bitblt =IBMDEV32.4318 <br />DrawBorder =IBMDEV32.4319 <br />PolyMarker =IBMDEV32.4320 <br />alloc_brush =IBMDEV32.5201 <br />free_brush =IBMDEV32.5202 <br />copy_brush =IBMDEV32.5203 <br />QueryRealColors =IBMDEV32.5300 <br />QueryColorIndex =IBMDEV32.5301 <br />QueryNearestColor =IBMDEV32.5302 <br />QueryColorData =IBMDEV32.5303 <br />UnrealizeColorTable =IBMDEV32.5304 <br />RealizeColorTable =IBMDEV32.5305 <br />deselect_lct =IBMDEV32.5306 <br />QueryLogColorTable =IBMDEV32.5307 <br />save_lct =IBMDEV32.5308 <br />QueryRGBColor =IBMDEV32.5309 <br />CreateLogColorTable =IBMDEV32.5310 <br />PropagateSysClrChange =IBMDEV32.5311 <br />MakeColorsValid =IBMDEV32.5312 <br />MakeBrushValid =IBMDEV32.5313 <br />MakePassedColorsValid =IBMDEV32.5314 <br />device_enter_driver =IBMDEV32.5315 <br />ResetLogColorTable =IBMDEV32.5316
=== Base DLL Function Exports ===
The following functions are exported by the base DLL. Exports beyond @1001 are also imported by the device-specific DLL.
MoveCursorDescription @103 <br />OS2_PM_DRV_ENABLE @1 RESIDENTNAME <br />OS2_PM_DRV_ENABLE_LEVELS @998 <br />OS2_PM_DRV_RING_LEVELS @999 <br />CheckCursor @104 <br />SEAMLESSTERMINATE @350 RESIDENTNAME 2 <br />private_alloc @1000 <br />private_free @1001 <br />enter_driver @1002 <br />leave_driver @1003 <br />save_that_error @1004 <br />perform_rip @1005 <br />ddc_validate @1006 <br />enter_driver_sem @1007 <br />GetVRAMR0Pointer @1008 <br />ring3_CriticalError @1010 <br />InnerAccumulateBounds @1014 <br />correlate_for_point_si @1016 <br />enter_driver_sem_only @1017 <br />leave_driver_sem_only @1018 <br />do_sl_corr @1019 <br />check_sem @1029 <br />get_clip_rects @1031 <br />ShortlineCorrelate @1032 <br />far_clip_line @1033 <br />ComputeShortlineBounds @1034 <br />save_that_warning @1042 <br />Force_Valid_CP @1202 <br />Vio32SetState @3000 <br />Vio32SetMode @3001 <br />free_bm @4100 <br />alloc_bm @4101 <br />AllocMem @4102 <br />FreeMem @4103 <br />recalc_correlate_rect @4104 <br />pfnDefDisJointLines @4105 <br />pfnDefPolyLine @4106 <br />pfnDefSetCurrentPosition @4107 <br />convert_world_screen @4108 <br />convert_screen_world @4109 <br />pfnDefRectVisible @4110 <br />pfnDefCharStringPos @4111 <br />pfnDefBitblt @4112 <br />pfnDefGetClipRects @4113 <br />pfnDefQueryTextBox @4114 <br />double_enter_driver @4115 <br />validate_rectl @4116 <br />intersect_rcl @4117 <br />intersect_with_corr @4118 <br />AccumBoundsInDevCoords @4119 <br />pfnDefDrawbits @4120 <br />convert_rectl @4121 <br />pfnDefPolyMarker @4122
=== Device-Specific DLL Function Imports ===
The following functions are duplicates of the base DLL exports beyond @1001 . They are imported by the device-specific DLL from the base DLL.
enter_driver =IBMVGA32.1002 <br />leave_driver =IBMVGA32.1003 <br />save_that_error =IBMVGA32.1004 <br />perform_rip =IBMVGA32.1005 <br />ddc_validate =IBMVGA32.1006 <br />enter_driver_sem =IBMVGA32.1007 <br />GetVRAMR0Pointer =IBMVGA32.1008 <br />ring3_CriticalError =IBMVGA32.1010 <br />InnerAccumulateBounds =IBMVGA32.1014 <br />correlate_for_point_si =IBMVGA32.1016 <br />enter_driver_sem_only =IBMVGA32.1017 <br />leave_driver_sem_only =IBMVGA32.1018 <br />do_sl_corr =IBMVGA32.1019 <br />check_sem =IBMVGA32.1029 <br />get_clip_rects =IBMVGA32.1031 <br />ShortlineCorrelate =IBMVGA32.1032 <br />far_clip_line =IBMVGA32.1033 <br />ComputeShortlineBounds =IBMVGA32.1034 <br />save_that_warning =IBMVGA32.1042 <br />Force_Valid_CP =IBMVGA32.1202 <br />Vio32SetState =IBMVGA32.3000 <br />Vio32SetMode =IBMVGA32.3001 <br />free_bm =IBMVGA32.4100 <br />alloc_bm =IBMVGA32.4101 <br />AllocMem =IBMVGA32.4102 <br />FreeMem =IBMVGA32.4103 <br />recalc_correlate_rect =IBMVGA32.4104 <br />pfnDefDisJointLines =IBMVGA32.4105 <br />pfnDefPolyLine =IBMVGA32.4106 <br />pfnDefSetCurrentPosition =IBMVGA32.4107 <br />convert_world_screen =IBMVGA32.4108 <br />convert_screen_world =IBMVGA32.4109 <br />pfnDefRectVisible =IBMVGA32.4110 <br />pfnDefCharStringPos =IBMVGA32.4111 <br />pfnDefBitblt =IBMVGA32.4112 <br />pfnDefGetClipRects =IBMVGA32.4113 <br />pfnDefQueryTextBox =IBMVGA32.4114 <br />double_enter_driver =IBMVGA32.4115 <br />validate_rectl =IBMVGA32.4116 <br />intersect_rcl =IBMVGA32.4117 <br />intersect_with_corr =IBMVGA32.4118 <br />AccumBoundsInDevCoords =IBMVGA32.4119 <br />pfnDefDrawbits =IBMVGA32.4120 <br />convert_rectl =IBMVGA32.4121 <br />pfnDefPolyMarker =IBMVGA32.4122
=== Device-Specific DLL Function Exports ===
The following functions are duplicates of the base DLL import functions. They are exported by the device-specific DLL.
init_hw_regs @4000 <br />rgb_to_ipc @4004 <br />physical_enable @4011 <br />physical_disable @4012 <br />device_specific_init @4013 <br />device_specific_post_init @4014 <br />copy_bits_to_pattern @4017 <br />PolyShortLine @4023 <br />SaveScreenBits @4026 <br />PolyScanline @4028 <br />RestoreScreenBits @4030 <br />Pixel @4034 <br />far_exclude @4037 <br />far_unexclude @4038 <br />SetColorCursor @4039 <br />DeviceSetCursor @4040 <br />SetScreenBusy @4041 <br />CharRect @4200 <br />CharStr @4201 <br />DeviceSetAVIOFont2 @4202 <br />ScrollRect @4204 <br />UpdateCursor @4205 <br />DeviceSeamlessInit @4206 <br />deselect_bitmap @4301 <br />save_bitmap @4302 <br />DeviceCreateBitmap @4303 <br />DeviceSelectBitmap @4304 <br />DeviceDeleteBitmap @4305 <br />GetBitmapBits @4306 <br />SetBitmapBits @4307 <br />DrawLinesInPath @4308 <br />DisJointLines @4309 <br />PolyLine @4310 <br />GetCurrentPosition @4311 <br />SetCurrentPosition @4312 <br />CharString @4313 <br />Drawbits @4314 <br />ImageData @4315 <br />CharMarkerPos @4316 <br />CharStringPos @4317 <br />Bitblt @4318 <br />DrawBorder @4319 <br />PolyMarker @4320 <br />alloc_brush @5201 NONAME <br />free_brush @5202 NONAME <br />copy_brush @5203 NONAME <br />QueryRealColors @5300 <br />QueryColorIndex @5301 <br />QueryNearestColor @5302 <br />QueryColorData @5303 <br />UnrealizeColorTable @5304 <br />RealizeColorTable @5305 <br />deselect_lct @5306 <br />QueryLogColorTable @5307 <br />save_lct @5308 <br />QueryRGBColor @5309 <br />CreateLogColorTable @5310 <br />PropagateSysClrChange @5311 <br />MakeColorsValid @5312 <br />MakeBrushValid @5313 <br />MakePassedColorsValid @5314 <br />device_enter_driver @5315 <br />ResetLogColorTable @5316
=== Base GRE Entry Points ===
The base DLL supplies functionality for the following calls from the Graphics Engine. For further information see the ''Presentation Device Driver Reference''.
AccumulateBounds <br />Death <br />DeviceGetAttributes <br />DeviceInvalidateVisRegion <br />DeviceQueryFontAttributes <br />DeviceQueryFonts <br />DeviceSetAttributes <br />DeviceSetDCOrigin <br />DeviceSetGlobalAttribute <br />ErasePS <br />Escape <br />GetBoundsData <br />GetCodePage <br />GetCurrentPosition <br />GetDCOrigin <br />GetLineOrigin <br />GetPairKerningTable <br />GetPel <br />GetPickWindow <br />GetScreenBits <br />GetStyleRatio <br />LockDevice <br />NotifyClipChange <br />NotifyTransformChange <br />QueryDeviceBitmaps <br />QueryDeviceCaps <br />QueryDevResource2 <br />QueryHardcopyCaps <br />RealizeFont <br />ResetBounds <br />Resurrection <br />SetCodePage <br />SetCurrentPosition <br />SetLineOrigin <br />SetPel <br />SetPickWindow <br />SetScreenBits <br />SetStyleRatio <br />UnLockDevice
=== Device-Specific GRE Entry Points ===
The device-specific DLL also supplies functionality for the following calls from the Graphics Engine.
Refer to the ''Presentation Device Driver Reference''for additional information on these calls.
Bitblt <br />CharRect <br />CharStr <br />CharString <br />CharStringPos <br />CreateLogColorTable <br />DeviceCreateBitmap <br />DeviceDeleteBitmap <br />DeviceSelectBitmap <br />DeviceSetCursor <br />DrawBits <br />DrawBorder <br />DrawLinesInPath <br />GetBitmapBits <br />ImageData <br />MoveCursor <br />Polyline <br />PolyMarker <br />PolyScanline <br />PolyShortLine <br />PropagateSysClrChange <br />QueryColorData <br />QueryColorIndex <br />QueryLogColorTable <br />QueryNearestColor <br />QueryRealColors <br />QueryRGBColor <br />RealizeColorTable <br />RestoreScreenBits <br />SaveScreenBits <br />ScrollRect <br />SetBitmapBits <br />SetColorCursor <br />StretchBlt <br />UnrealizeColorTable <br />UpdateCursor
The device-specific DLL also supplies functionality for the ''DeviceSetAVIOFont''call from GRE. In the device-specific DLL, the function must be named ''DeviceSetAVIOFont2''.
Refer to the ''Presentation Device Driver Reference''for additional information.
=== The Device-Specific API ===
These are functions that are created by the developer of the device- specific driver:
copy_bits_to-pattern <br />deselect_bitmap <br />device_enter_driver <br />deselect_lct <br />device_specific_post_init <br />device_specific_init <br />far_exclude <br />far_unexclude <br />init_hw_regs <br />physical_disable <br />physical_enable <br />Pixel <br />PropagateSysClrChange <br />save_bitmap <br />save_lct
Each of these functions must behave exactly as described.
For the descriptions of the register contents, the equal &quot; = &quot; sign means that the register contains the value named. For example:
'''ECX = number of bytes per scan'''means that the register contains the actual number of bytes per scan.
The arrow &quot; � &quot; sign means that the register contains a pointer to the value, and not the actual value itself. For example:
'''ECX � number of bytes per scan'''means that the value in the register is a pointer to the memory location that contains the number of bytes per scan.
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    copy_bits_to_pattern                                  |
|                                                          |
|    void copy_bits_to_pattern(void)                      |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Copy a source pattern bit map to a destination pattern bit map .
Entry:
<pre class="western">AL  = Number of color planes in source bit map
AH  = Width of bit map in pels (significance through eight)
EBX � DDC
ECX = Number of bytes per scan of source bit map
EDX = Height of bit map
ESI � First byte of the destination buffer
EDI � First byte of the source buffer</pre>
Return Values: None
Error Returns: None
Registers Preserved: EBX, EBP, ESP
Registers Preserved: EAX, ECX, EDX, ESI, EDI, FLAGS
Invoked From:
<pre class="western">SetPatternFont        (Winattrs.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_bitmap                                      |
|                                                          |
|    void deselect_bitmap(void)                            |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Decrements selection count in the bit map, clears the pointer to the surface device, and clears the following DDC bits:
�DDC_PRESENT - indicating that there is no surface. <br />�DDC_CLIP_NOTIFY - indicating clipping is invalid <br />�DDC_VISIBLE - indicating nothing is showing.
If the selection count is 0, it clears the handle to DDC, indicating a free bit map.
Entry: ESI � DDC
Return Values: None
Error Returns: None
Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP
Registers Destroyed: EBX, FLAGS
Invoked From:
<pre class="western">restore_ddc_state      (Enable.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_enter_driver                                  |
|                                                          |
|    void device_enter_driver(void)                        |
|                                                          |
\----------------------------------------------------------/</pre>
Description: ''device_enter_driver''is a null function.
Entry: None
Return Values: None
Error Returns: None
Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS
Registers Preserved: None
Invoked From:
<pre class="western">enter_driver (enter.asm)</pre>
Routines Called: Dependent on processing
Video Semaphore Required for Processing: Dependent on processing
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_lct                                          |
|                                                          |
|    void deselect_lct(void)                              |
|                                                          |
\----------------------------------------------------------/</pre>
Description: ''deselect_lct''decrements the usage count in the logical color table.
When the usage count is 0, deselect_lct frees the memory of the ''logical_ color_table''by calling ''private_free''with the ECX pointing to the memory to be released and sets the default color table.
''private_free''is an exported function contained in IBMVGA32.DLL.
Entry: ESI � DDC
Return Values: None
Error Returns: None
Registers Preserved: EAX, EDX, ESI, EDI, ESP, EBP, FLAGS
Registers Preserved: EBX, ECX
Invoked From:
<pre class="western">disable_ddc            (Enable.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_post_init                            |
|                                                          |
|    void device_specific_post_init(void)                  |
|                                                          |
\----------------------------------------------------------/</pre>
Description: ''device_specific_post_init''is a null function.
Entry: None
Return Values: None
Error Returns: None
Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS
Registers Preserved: None
Invoked From:
<pre class="western">one_time_init      (init.asm)</pre>
Routines Called: Dependent on processing
Video Semaphore Required for Processing: Dependent on processing
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_init                                  |
|                                                          |
|    void device_specific_init(void)                      |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Initializes ''gsspScreen.cb''to the size of screen memory (64KB), ''gsspScreen.pPhysMem''to the address of screen memory (0A0000h). Sets the marker width and height in the device capabilities buffer (adDevCapsData[ CAPS_MARKER_WIDTH ], adDevCapsData[ CAPS_MARKER_HEIGHT ]). See the ''Presentation Manager Programming Reference, Volume 1'', &quot;DevQueryCaps&quot;, for additional information.
Set ''padBitmapFormats''to the address of the table containing bit map format types.
The table is in the form (# planes, bits/pel). The first pair in the table must be the format that most closely resembles the device.
(For additional information see the ''Presentation Device Driver Reference'', &quot; GreQueryDeviceBitmaps&quot;).
Get a Ring 0 alias for screen memory pointer and save in ''Curdata.pVRAMRing0'' .
The following code segment illustrates the sequence described above:
Basically, you open PMDD.SYS via DosOpen and communicate with PMDD.SYS via DosDevIOCtl.
<pre class="western">GetVRAMR0Pointer PROC SYSCALL USES EDI
        LOCAL  hSVGA:DWORD
        LOCAL  ulAction:DWORD
        LOCAL  scrnTx:SCRNTX
        LOCAL  scrnRx:SCRNRX
        LOCAL  fAttach:BYTE
        INVOKE  DosOpen,
                ADDR szSQ,        ;lpDevice � device
                                    name string
                ADDR hSVGA,        ;pass � handle
                                    return value
                ADDR ulAction,    ;dAction return value
                0,                ;filesize (zero)
                0,                ;file attribute (zero)
                1,                ;open flag (open
                                    existing file)
                0000000011000000b, ;open mode
                0                  ;reserved
        or      eax,eax
        jnz    getvram_error
        mov    eax,gsspScreen.pPhysMem
        mov    scrnTx.stx_Address,eax
        mov    eax,gsspScreen.cb
        mov    scrnTx.stx_Size,eax
        mov    scrnTx.stx_flFlag,1
        INVOKE  DosDevIOCtl,
                hSVGA,            ;hDevice
                03h,              ; ulCat
                7eh,              ; ulFunction
                ADDR scrnTx,      ; pParmList
                SIZEOF scrnTx,    ; cbParmList
                0,                ; plReserved
                ADDR scrnRx,      ; pData
                SIZEOF scrnRx,    ; cbData
                0                  ; plReserved
        mov    ebx,eax            ;save return code
        INVOKE  DosClose, hSVGA
        mov    eax,scrnRx.srx_ScrnPtr
@@:
;/*
;** check return from dosdevioctl call
;*/
        or      ebx,ebx
        jz      getvram_exit
getvram_error:
        mov    eax,0              ;error return
getvram_exit:
        ret</pre>
Entry: None
Return Values: None
Error Returns: None
Registers Preserved: ESP, EBP
Registers Destroyed: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS
Invoked From:
<pre class="western">DllLoadProc            (Init.asm)</pre>
Routines Called:
<pre class="western">CursorInit            (Cursor2.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_exclude                                          |
|                                                          |
|    void far_exclude(void)                                |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Removes the pointer image if the exclusion area of the screen currently includes the pointer.
Entry:
<pre class="western">ECX = X coordinate of left edge
EDX = Y coordinate of top edge
ESI = X coordinate of right edge (inclusive)
EDI = Y coordinate of bottom edge (inclusive)</pre>
Return Values: None
Error Returns: None
Registers Preserved: ESP, EBP
Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS
Invoked From:
<pre class="western">OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits        (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init  (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine              (Major01.asm)</pre>
Routines Called:
<pre class="western">pointer_off            (Pointer.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_unexclude                                        |
|                                                          |
|    void far_unexclude(void)                              |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Removes the exclusion rectangle defined by ''far_exclude''. Do not redraw the cursor because it might have to be removed for the next call. Redrawing the pointer is the responsibility of ''MoveCursor''.
Entry: None
Return Values: None
Error Returns: None
Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, FLAGS
Registers Preserved: None
Invoked From:
<pre class="western">OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits        (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init  (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine              (Major01.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    init_hw_regs                                          |
|                                                          |
|    void init_hw_regs(void)                              |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Initializes the state required to save and restore the VGA's registers and processor latches, and the default VGA state assumed by the rest of the display driver code. Call this code immediately after the VGA has been programmed for graphics mode and the palette registers set. This code is called at initialization, resurrection, and after a DOS session to ensure a known state of the VGA.
Entry: None
Return values: None
Error Returns: None
Registers Destroyed: EAX, ECX, EDX, FLAGS
Registers Preserved: EBX, ESI, EDI, EBP, ESP
Invoked From:
<pre class="western">physical_enable        (Egainit.asm)
req_controller        (Enter.asm)</pre>
Routines Called:
<pre class="western">set_test_locs          (Egastate.asm)
set_misc_regs          (Egastate.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_disable                                      |
|                                                          |
|    void physical_disable(void)                          |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Inhibits all drawing to the screen by the VDD and VDM and PM. ''physical_disable''is called from Death, signifying a switch to a non-PM screen group. ''physical_disable''saves the physical screen and hardware state .
Entry: None
Return Values: None
Error Returns: None
Registers Preserved: ESI, EDI, EBP, ESP
Registers Destroyed: EAX, EBX, ECS, EDX, FLAGS
Invoked From:
<pre class="western">Death                  (Winattrs.asm)</pre>
Routines Called:
<pre class="western">enter_driver_sem_only  (Enter.asm)
leave_driver_sem_only  (Enter.asm)
notify_vdd            (Egainit.asm)
notify_vwin            (Egainit.asm)
save_textvram          (Egainit.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_enable                                      |
|                                                          |
|    DWORD physical_enable (DWORD fInitMem, DWORD cbDirty) |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Enables the appropriate graphics mode. Attempts a fast video ram restore if ''fInitMem''does not equal INIT_VRAM.
Entry: ''fInitMem''is a flag set by ''fill_phys_dev_blk''or Resurrection.
A value of 1 indicates original initialization procedures, indicating that screen memory should be initialized to zeros. Any other value indicates restoration from a previously saved state. ''cbDirty''is the number of VRAM bytes to restore for a fast video restore. ''physical_enable''receives ''cbDirty''from resurrection. ''cbDirty''indicates the number of bytes of video RAM damaged since Death. If the amount dirtied is less than the amount saved at Death then a fast video RAM restore is performed.
Ignore this value if ''fInitMem''contains 1. ''physical_disable''saves the physical screen and hardware state to improve screen restoration performance. If the screen state remains unchanged at resurrection time, the driver can display a saved state quicker than it can reconstruct and redraw the previous state (fast video ram restore).
Return Values: EAX = 0 if successful
Error Returns:
<pre class="western">EAX = Vio Error code if not successful (EAX &lt;&gt; 0)
      or result of video RAM restoration if fInitMem was FALSE</pre>
Registers Preserved: ESI, EDI, EBP, ESP
Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS
Invoked From:
<pre class="western">fill_phys_dev_blk      (Enable.asm)
Resurrection          (Winattrs.asm)</pre>
Routines Called:
<pre class="western">Vga32CallBack          (32callbk.asm)
restore_textvram      (Egainit.asm)
init_hw_regs          (Egastate.asm)
notify_vdd            (Egainit.asm)
notify_vwin            (Egainit.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    Pixel                                                |
|                                                          |
\----------------------------------------------------------/</pre>
<br /><br />
<pre class="western">LONG Pixel (LONG lX, LONG lY, LONG lPhysColor,
                    LONG lMixMode);</pre>
<br /><br />
<pre class="western">lx:                    x coordinate of pel
ly:                    y coordinate of pel
lPhysColor:            Physical color to set pel to
lMixMode:              Raster operation code or -1 if get pel</pre>
Description: Sets a pel to a given color or returns a pel's internal physical color. The physical device may be the screen, or a monochrome or color bit map.
If ''mix_mode''equals -1, Pixel returns the pel's IPC (Internal Physical Color ). If ''mix_mode''is any other value, the value indicates the Raster operation (ROP).
During a set pel operation, Pixel sets the pel to the color that corresponds to the internal physical color indicated in the ''lPhysColor''parameter, combined with the internal physical color of the pel currently at that location. Pixel combines the colors according to the ROP in ''mix_ mode''. Background and clipping are not a consideration.
Entry:
<pre class="western">ESI � DDC
VGA registers in default state</pre>
Return Values: EAX = IPC if ''GetPixel''or Positive if ''SetPixel''
Error Returns: EAX = 080000000H
Registers Preserved: ESI, EDI, EBP, ESP
Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS
Invoked From:
<pre class="western">GetPel                (Pelsup.asm)
SetPel                (Pelsup.asm)</pre>
Routines Called:
<pre class="western">far_exclude            (Cursor2.asm)
far_unexclude          (Cursor2.asm)
ipc_to_index          (Clrconv.asm)</pre>
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    PropagateSysClrChange                                |
|                                                          |
|    void PropagateSysClrChange(void)                      |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Called after at least one system color changes. Since the driver has no way of knowing which color changed, it must assume that all system colors have changed. Color table indices 0 and 7 default to certain system colors.
If these system colors change and the default mapping is still in effect, the driver must update the corresponding IPC (internal physical color) from the default color table.
The default mapping is in effect unless the driver explicitly changes it. In that case, DDC_CLR_0_USERS or DDC_CLR_7_USERS is set, as appropriate. The driver must update any attribute bundle that has a system color selected, by marking the IPC as invalid so that it won't be realized again until necessary.
Entry: ESI � DDC
Return Values: None
Error Returns: None
Registers Preserved: EBX, ECX, EDX, ESI, EDI, EBP, ESP
Registers Destroyed: EAX, FLAGS
Invoked From:
<pre class="western">GetPel                (Pelsup.asm)
SetPel                (Pelsup.asm)
DrawBorder            (Drawbord.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine              (Polyline.asm)
Bitblt                (Winbits . asm )
ImageData                ( Winbits . asm )
CharStringPos            ( Winstr . asm )
CharMarkerPos            ( Winstr . asm )
CharString                ( Winstr . asm )
ipc _ to _ index              ( Clrconv . asm )
RGBToNearestIndex        ( Colortbl . asm )
QueryLogColorTable      ( Colortbl . asm )
QueryRGBColor            ( Colortbl . asm )
PolyScanline              ( Scanline . asm )
PolyShortline            ( Shortln . asm ) </pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_bitmap                                          |
|                                                          |
|    void save_bitmap(void)                                |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Increments the select count in the bit map.
Entry: ESI � DDC
Return Values: None
Error Returns: None
Registers Preserved: EAX, ECX, EDX, ESI, EDI, EBP, ESP
Registers Destroyed: EBX, FLAGS
Invoked From:
<pre class="western">save_ddc_state        (Enable.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
<br /><br />
<pre class="western">/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_lct                                              |
|                                                          |
|    void save_lct(void)                                  |
|                                                          |
\----------------------------------------------------------/</pre>
Description: Increments the usage count in the logical color table.
Entry: ESI � DDC
Return Values: None
Error Returns: None
Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP
Registers Destroyed: FLAGS
Invoked From:
<pre class="western">save_ddc_state        (Enable.asm)</pre>
Routines Called: None
Video Semaphore Required for Processing: No
=== GRE Functions ===
The following is a list of the functions in the graphics engine that are hooked by the 32-bit VGA display driver.
�Graphics Engine Attribute Functions
�Graphics Engine AVIO Functions
�Graphics Engine Bit-Map Functions
�Graphics Engine Color Table Functions
�Graphics Engine Device Functions
�Graphics Engine Escape Functions
�Graphics Engine Line Functions
�Graphics Engine Marker Functions
�Graphics Engine Miscellaneous Device Functions
�Graphics Engine Miscellaneous Screen Functions
�Graphics Engine Query Functions
�Graphics Engine String Functions
For more information about these functions and their descriptions, see [[01187.htm|Graphics Engine Functions]].
=== Debugging Support ===
Debugging support is provided through a macro that sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the ''Developer's Toolkit for OS/2''. By inserting the DebugMsg2&lt;&gt; macro, the supplied string will be routed to the debugging port.
<pre class="western">ifdef FIREWALLS
        DebugMsg2      &lt; This will be printed at the debugging terminal. &gt;
endif ;FIREWALLS</pre>
Current debug messages in the code are placed inside the conditional compilation ''ifdef FIREWALLS''. This value is defined when compiling the debug version of the driver.
=== Thunking ===
Although the display driver is written in 32-bit flat model, there still is a need to call certain 16-bit routines. To accommodate this need, ''thunk layer''interfaces are provided. The thunk layer converts 32-bit parameters to 16-bits, and maps linear addresses to segmented addresses. For detailed information about thunking and thunk layers, see the ''OS/2 Application Design Guide''.
Thunk layers are provided for the 16-bit functions listed in the table below, so that they can be available to the 32-bit display driver.
<pre class="western">/-------------------------------------------------------------\
|16-Bit Function        |32-Bit Function from VGA Display    |
|                        |Driver                              |
|------------------------+------------------------------------|
|VIS16REGIONCALLBACK    |Vis32RegionCallBack                |
|------------------------+------------------------------------|
|GetPmddCodeSelector    |Get32PmddCodeSelector              |
|------------------------+------------------------------------|
|GetScreenSelector      |Get32ScreenSelector                |
|------------------------+------------------------------------|
|VioGetPhysBuf          |Vio32GetPhysBuf                    |
|------------------------+------------------------------------|
|VioSetState            |Vio32SetState                      |
|------------------------+------------------------------------|
|VioSetMode              |Vio32SetMode                        |
|------------------------+------------------------------------|
|VioGetConfig            |Vio32GetConfig                      |
|------------------------+------------------------------------|
|VioGetPSAddress        |VioGetPSAddress32                  |
|------------------------+------------------------------------|
|FSRSemEnter            |FSRSemEnter32                      |
|------------------------+------------------------------------|
|FSRSemLeave            |FSRSemLeave32                      |
|------------------------+------------------------------------|
|FSRSemExit              |FSRSemExit32                        |
|------------------------+------------------------------------|
|FSRSemCheck            |FSRSemCheck32                      |
\-------------------------------------------------------------/</pre>
The 32-bit display driver functions listed in the table below have 16-bit thunk interfaces that are provided to the 16-bit WIN-OS/2 display driver so that it can cooperate with the 32-bit VGA display driver.
<pre class="western">/-------------------------------------------------------------\
|16-bit Functions Called by    |32-Bit Functions in VGA      |
|WIN-OS/2                      |Display Driver                |
|------------------------------+------------------------------|
|far_unexclude16              |far_unexclude                |
|------------------------------+------------------------------|
|FAR_EXCLUDE16                |far_exclude                  |
\-------------------------------------------------------------/</pre>




Revision as of 16:12, 29 April 2016

By IBM

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

About this Book

The device drivers described in the Display Device Driver Reference provide information and code to enable you to start developing your own OS/2 display device drivers.

Note: To verify that your driver signature is unique, contact the IBM Driver Development Support Center (DDSC) Bulletin Board System (the DUDE) on (407) 982-4239.

How This Book Is Organized

#16-Bit VGA Display Driver This chapter presents the 16-bit VGA driver, a dynamic link library that converts device-independent graphics calls into VGA-specific device instructions.

#8514/A Display Driver This chapter covers the differences between the 16- bit VGA display driver and the 8514.

32-Bit VGA Display Driver This chapter presents the 32-bit VGA driver, contained in two Dynamic Link Libraries: one hardware-independent, the other hardware-dependent.

Also described are the responsibilities of the driver to the Presentation Manager graphics engine, which loads the Dynamic Link Libraries for the display driver.

32-Bit Super VGA Display Driver This chapter discusses the differences between the VGA and the Super VGA device drivers.

SVGA Base Video Subsystem This chapter has been rewritten and now describes how the SVGA base video subsystem handles all non-graphical primitive video device functions. It also describes how to handle the mode set function.

Physical Video Device Drivers This chapter describes the Video Device handlers, and lists functions used to read and write to the EGA registers. The DPRINTF Print Formatting Package information has been moved from the end of SVGA Base Video Subsystem to the end of this chapter.

Virtual Video Device Drivers This chapter describes the design, implementation, and interfaces of virtual video device drivers, including the virtualization and windowing of DOS sessions on an OS/2 platform. A virtual video device driver is required when it is necessary for multiple DOS sessions to share one or more video devices. "Super VGA Virtual Video Device Driver Support" describes how to add support for an Super VGA capable chip set.

Seamless Windows Support This chapter provides information on how to execute Windows applications in one or more windows on the OS/2 desktop, and includes a Checklist for Palette Management Support in seamless display drivers. It also includes an overview of the Distributed Console Access Facility (DCAF), which provides remote console functions.

PM Palette Management Support This chapter describes Presentation Manager Palette Management, special code that enables applications to specify exact color values for a drawing or image on a particular device. The application's color requests are mapped as closely as possible to the actual colors available in the device's hardware color palette. When possible, the hardware palette is modified to exactly provide the requested RGB values.

Distributed Console Access Facility (DCAF) This chapter discusses the design and purpose of DCAF within the OS/2, DOS and WINDOWS environments.

DBCS Video Driver Support This chapter describes double-byte character set (DBCS) video driver support.

Installing and Configuring Display Device Drivers This chapter describes the OS/2 display driver installation utility program (DSPINSTL.EXE), which provides all the facilities for installing and configuring the IBM Operating System/2 and Presentation Manager display device drivers. This installation utility program also can install and configure WIN-OS/2 (both full-screen and windowed) display drivers, and can install base video service (VIO) and DOS virtual device drivers. A sample DSPINSTL Script is included to assist you in SVGA BBS installations.

Graphics Test Suites This chapter describes test suites that are designed for System Verification Test and Function Verification Test.

Display Test Tool This chapter describes the Display Test Tool, a Presentation Manager application that enables the user to select one or more display tests and execute them.

VIDEOCFG.DLL Exported Functions This chapter describes the VIDEOCFG syntax as working samples, adhering to the style of the "C" programming language. The VIDEOCFG.DLL exported functions, formerly in Chapter 5, are now in this revamped and revised chapter. Also covered is a section on a Generic Video Configuration Interface.

VIDEOPMI.DLL Exported Functions This chapter presents the VIDEOPMI syntax as working samples, adhering to the style of the "C" programming language.

VIDEO Protect-Mode Interface This chapter discusses the format and syntax used to define the necessary data for setting a video mode while in OS/2 protect mode, and to enable virtualization in multiple DOS sessions. The objective is to achieve a protect-mode interface to Super VGA hardware.

Appendixes

Appendix A. OS/2 Version Compatibility Considerations This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.

Appendix B. GRE Function Tests (by Function Name) This appendix consists of a table that lists the various GRE function tests, organized by function name.

Appendix C. GRE Function Tests (by Test-Case Name) This appendix consists of a table that lists the various GRE function tests, organized by test-case name.

Appendix D. Graphics Engine Functions This appendix consists of several tables, each of which lists a different type of graphics engine function.

Appendix E. DTT Script File Command Summary This appendix contains a summary of the commands used in a DTT script file.

Appendix F. DTT Command-Line Options Summary This appendix contains a summary of the command-line options.

Appendix G. Sample DTT Script File This appendix contains the code for a sample script file.

Appendix H. Glyph Codes This appendix contains a table that lists the reserved glyph codes and the relationship between glyph pattern and glyph code ID in code page 932.

Appendix I. S3 Display Driver This appendix contains a discussion on the architecture of the S3 Display Device Driver and covers the portions of the driver that require modification in order to support other graphics accelerator chip sets.

Appendix J. S3.DSP (Sample File for Installation and Configuration) This appendix consists of a sample S3 display (DSP) file that contains DSPINSTL installation and configuration commands.

Appendix K. Deciphering File Names in the S3 Driver This appendix consists of a list of S3 file names with an explanation of how the file names are derived.

Appendix L. Color Palette Default Values This appendix contains tables listing the default values for VGA (4bpp), XGA (8bpp) and XGA (16bpp) color palettes.
Miscellaneous

A glossary and index are included.

Notices

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 Graphics Adapter Device Driver Reference
�The MMPM/2 Device Driver Reference (Multimedia)
To order the DDK call: 

/----------------------------------------------------------------\
|U.S.A.:             |1-800-633-8266       |                     |
|--------------------+---------------------+---------------------|
|Canada:             |1-800-561-5293       |                     |
|--------------------+---------------------+---------------------|
|When calling from   |� English            |(+45) 48101500       |
|Europe, the Middle  |� French             |(+45) 48101200       |
|East, or Africa, the|� Italian            |(+45) 48101600       |
|number depends on   |� German             |(+45) 48101000       |
|the language you use|� Spanish            |(+45) 48101100       |
|to place the order: |� Dutch              |(+45) 48101400       |
|                    |� Danish             |(+45) 48101300       |
|                    |� Finish             |(+45) 48101650       |
|                    |� Swedish            |(+45) 48101150       |
|                    |� Norwegian          |(+45) 48101250       |
|                    |� FAX                |(+45) 48142207       |
|--------------------+---------------------+---------------------|
|When ordering from  |� Bolivia            |    02-35 1840       |
|Latin America or    |� Columbia           |   01-257-0111       |
|South America, the  |� Dominican Republic |      566-5161       |
|number depends on   |� El Salvador        |    02-98 5011       |
|the country from    |� Honduras           |       32-2319       |
|which you are       |� Paraguay           |   021-444 094       |
|calling:            |� Urugruay           |    02-923 617       |
|                    |� Chile              |   02-633-4400       |
|                    |� Costa Rica         |      223-6222       |
|                    |� Ecuador            |    02-56 5100       |
|                    |� Guatemala          |    02-31 5859       |
|                    |� Panama             |    02-639 977       |
|                    |� Peru               |   014-36 6345       |
|                    |� Venezuela          |   02-908-8901       |
|                    |� Argentina          |   01-313-0014       |
|--------------------+---------------------+---------------------|
|To order from Asia/ |� All except Japan   |(61) 2-354-7684      |
|Pacific:            |� Japan              |(81) 3-3495-2045(Fax)|
|                    |                     |Fax request to:      |
|                    |                     |DAP-J, IBM Japan     |
|--------------------+---------------------+---------------------|
|To order from SE    |(021) 800-6120(Voice)|                     |
|Brazil:             |(021) 800-6936(Fax)  |                     |
|--------------------+---------------------+---------------------|
|To order from       |� Mexico City        |627-2444             |
|Mexico:             |� Country            |91-800-00639         |
\----------------------------------------------------------------/

What's New

There were no major changes to this release of the Display Device driver Reference.

The table that appears in #OS/2 Version Compatibility Considerations identifies any compatibility issues associated with updates made to this book.

Try Our New Improved Model!

Are you tired of device-driving late into the night? You may want to consider using the new GRADD (short for GRaphics Adapter Device Driver) model to write your next video driver on OS/2 Warp, Beta Version 99.99.

The GRADD driver model, provided on this DDK CD, requires 10 times less lines of code than previously required to write an OS/2 video device driver. Some of the advantages incorporated in the GRADD model include the following:

  • Simplifies development effort
  • Reduces cycle time
  • Allows incremental development; requires fewer mandatory functions
  • Both This eliminates the need to write a seamless WinOS/2 driver.

If you are writing new video drivers for OS/2 Warp, Beta Version 99.99, you can take advantage of these development savings. Refer to the GRADD Device Driver Reference and code samples on this CD to get started today.

16-Bit VGA Display Driver

The 16-bit VGA display driver provides hardware independence to the application code that performs I/O to a display device. An application program need not be concerned with the hardware-specific requirements of the adapter card.

Overview

The 16-bit VGA display driver is a set of special-purpose I/O routines, operating at privilege level 2 (Ring 2). This driver, along with other presentation drivers, provides the link between the internal interface to display devices and the OS/2* interfaces to the kernel device drivers at Ring 0 (the highest privilege level) and the screen.

When an application needs to perform I/O to the screen, it calls a system DLL, which in turn calls the Presentation Manager* (PM) graphics engine, contained in PMGRE.DLL. The graphics engine then calls the display driver, contained in DISPLAY.DLL. The display driver can then access the adapter hardware directly through memory-mapped I/O, or can call the OS/2 kernel by way of the standard driver mechanism to perform the I/O.

When the display driver is loaded, the graphics engine allocates an internal dispatch table to process the functions. The dispatch table is an array of pointers to function-handling routines. The low-order byte of the function number identifies the member of the array that contains the pointer for the function. The first time that the display driver is called at its OS2_PM_DRV_ENABLE entry point, it replaces the graphics engine pointers in the dispatch table with pointers to the corresponding functions supported by the display driver. Some of the pointer replacements are mandatory; others are optional.

The graphics engine pointer to the dispatch table is passed to the display driver by way of a FillLogicalDeviceBlock call.

16-Bit VGA Architecture

The 16-bit VGA display driver consists of one component (DISPLAY.DLL). DISPLAY.DLL contains all entry points-both device-dependent and device-independent functions (including seamless support) - that the graphics engine calls.

All the fonts, cursors, and bit maps are included in a binary resource file (.RES) that is built and added to the driver by the resource compiler.

Functions

The following is a list of the functions in the graphics engine that are hooked by the 16-bit VGA display driver.

  • Graphics Engine Attribute Functions
  • Graphics Engine AVIO Functions
  • Graphics Engine Bit-Map Functions
  • Graphics Engine Color Table Functions
  • Graphics Engine Device Functions
  • Graphics Engine Escape Functions
  • Graphics Engine Line Functions
  • Graphics Engine Marker Functions
  • Graphics Engine Miscellaneous Device Functions
  • Graphics Engine Miscellaneous Screen Functions
  • Graphics Engine Query Functions
  • Graphics Engine String Functions

For more information about these functions and their descriptions, see #Graphics Engine Functions.

Debugging Support

Debugging support is provided through a macro, color_puts<>, contained in seamless.inc. This macro sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the OS/2 2.X Toolkit. The input for the macro is foreground color, background color <string>, as follows: 

ifdef FIREWALLS

        color_puts  BLUE,BLACK,< This message will be output to
                                        the debugging terminal >

endif ;FIREWALLS

Current debugging messages in the code are placed inside the conditional compilation ifdef FIREWALLS. This value is defined when compiling the debug version of the driver. Another example of this macro can be found in init.asm.

The BITBLT Function

One of the most important functions used in Presentation Manager is BITBLT (Bit Block Logical Transfer), which draws the rectangles that make up the PM Desktop, icons, and other bit maps. BITBLT is similar to a byte-block move operation except that blocks are moved on bit boundaries instead of byte boundaries. This could require that the bits of the source be aligned to the bits of the target (phase alignment). An example is moving all bits of a bit map left two pels. Once the bits are aligned, they are combined with an optional pattern and the target, as specified by the raster operation (ROP).

For arbitrary BLT processing, code is derived dynamically and written to a data segment. This segment is then aliased to a code segment, and executed. BITBLT functionality is the same for 16-bit VGA, 32-bit VGA, and 32-bit Super VGA.

For detailed information on BITBLT functionality, see VGA32\IBMDEV32\BITBLT .ASM and VGA32\IBMDEV32\CBLT.ASM.

The innermost functionality of BITBLT can be pictured as follows:

Bytes are fetched from a source. Color conversion is applied if the source and target are of different color formats. (See Color Conversionand XGA Support for Palette Management - Dithering and BITBLTingfor detailed information about color conversion.) The source bits then are aligned with the target. Bits from a previous phase alignment and the current phase alignment are combined to form one byte's worth of data. The unused bits from the phase alignment are saved for the next phase alignment.

The ROP is applied against the source bits, pattern, and target, as needed; the result replaces the target byte.

Overlapping BLTs

The following illustrations show possible overlaps that can occur when a BLT is performed. Since the source and target can overlap, the order in which bytes are processed must be chosen with care. If the order is wrong, a byte of the source might be overwritten (as a target) before the byte is used as a source. (You might remember propagating spaces through a field on the IBM* 360s and 370s).

In the following figures, S is the source, D is the target, and x is the corner from where the first byte will be fetched. The comments (on the right) tell in which directions (X and Y) the BLT must be performed to prevent the overwriting of a source byte before it is used as a source. The possible cases of overlap are as follows:

  1. Disjointed (not special cased)
  2. Identical (not special cased)
  3. Overlapping

The following four examples are degenerate cases (along with identical and disjoint) and the directions are as shown:

Phase Relationship Between Source and Target Bit Maps

Since BLTs are performed on bit boundaries instead of byte boundaries, rotations of the source bit map bytes might have to be performed. Source data is always rotated to align with the target. The following describes how the phase relationship is determined and how to start the BLT. (Some phase relationships require a different number of initial source bit map fetches to acquire enough bits to satisfy the first store.)

The number of bytes separating the source and target in the following examples is irrelevant; only the relationship of the bits within the bytes is important. Saved and used masks are applied after rotating the source byte.

Saved bits mask A mask that gives the bit that must be carried over to the next byte BLTed.

Used bits mask A mask that gives the bits that are to be used for the current byte BLTed.

Old unused bits Bits that were not used in the last byte BLTed and, therefore, bits that must be used for the current byte BLTed.

First byte mask A mask that is used to mask the bits (of the very first byte BLTed) that are to be altered. The complement of this mask gives the bits of the target byte that are to remain unaltered.

The BLT is started based on the cases of overlap as previously specified.

For box cases 3, 4, 5, 6, 8, disjoint, and same (as shown previously), BLTs start at the left, stepping right. Calculations are based on the left side of the source and target rectangles. The starting mask is based on the leftmost byte of the target; the ending mask is based on the rightmost byte of the target, as follows:

For box cases 1, 2, and 7, BLT starting at the right, stepping left. Calculations are performed on the right side of the source and target rectangles. The starting mask is based on the rightmost byte of the target , and the ending mask is based on the leftmost byte of the target.

Raster Operation Codes And Definitions

Each raster operation code represents a Boolean operation in which the source, currently selected brush, and target are combined.

The operands used in the operations are:

S Source bit map
P Currently selected brush (also called pattern)
D Target bit map

The Boolean operators used in these operations are:

o Bitwise OR
x Bitwise Exclusive OR
a Bitwise AND
n Bitwise NOT (inverse)

All Boolean operations are presented in reverse Polish notation. For example, the operation:

PSo

replaces the target with a combination of the source and brush.

The operation:

DPSoo

combines the source and brush with the target. Because there are alternate spellings of the same function, although a particular spelling might not be in the list, an equivalent form will be.

Each raster operation code is an 8-bit integer value that represents the result of the Boolean operation on predefined brush, source, and target values. For example, the operation indexes for the PSoand DPSoooperations are:

In this case, PSohas the operation index 00FC (read from the bottom up); DPSoohas the index 00FE.

Color Conversion

Color conversion applies when the source and target color formats are not the same. Color conversion takes place prior to any mix mode. For additional information, see XGA Support for Palette Management - Dithering and BITBLTing.

�Mono � Color Conversion

Applied when the source is monochrome and the target is color.

When going from monochrome to color, 1 bits are converted to the target image foreground color, and 0 bits are converted to the target image background color.

�Color � Mono Conversion

Applied when the source is color and the target is monochrome.

When going from color to monochrome, all pels that match the passed background IPC (obba_bgndIPC) are converted to the target image background color; all other pels are converted to the target image foreground color.

8514/A Display Driver

The IBM 8514/A display driver shares its basic functionality with the 16- bit VGA display driver. See 16-Bit VGA Display Driverfor details about privilege levels, graphics engine interface, graphics engine functions, dispatch tables, and debugging. For the most part, these topics, as covered in that chapter, apply also to the 8514/A display driver.

Overview

This chapter covers the differences between the 16-bit VGA display driver and the 8514/A display driver, followed by 8514/A device-specific programming information.

Operating Modes

The 8514/A graphics adapter operates in the following modes:

  • Video-graphics array (VGA)

This is the power-on mode; the functionality of the 16-bit VGA display driver is available.

  • Advanced-function

This mode provides a programming interface for the adapter. The primary advantage of the 8514/A display driver over the 16-bit VGA display driver is that the advanced-mode adapter interface handles much of the hardware programming for you. Instead of programming directly into the bit-plane memory, the adapter provides an interface supporting most of the required display functions.

Both modes of operation are selectable under program control.

Macros for Utilizing Available Hardware Capabilities

The 8514/A display driver includes a set of macros to access the adapter interface. When called by the driver, through the entry points, the interface provides a set of functions to utilize the hardware capabilities of the display adapter. Each of the macros is addressed in detail in the sections that follow. 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitIO                                                |
|                                                          |
\----------------------------------------------------------/

Tests an I/O port for a particular value, as follows:

Port The port number to be polled. If not present, it is assumed that the port number is already loaded into the DX register.

Sense The sense of jump needed to remain in the polling loop.

Mask If present, the value that will be ANDed with the polled contents of Port.

EquVal If present, the value that must match the Portcontents, after masking (if Maskis present).

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitIO macro Port,Sense,Mask,EquVal,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQIN                                               |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter output queue to contain available data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQIN macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQOUT                                              |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter input queue to be ready to accept data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQOUT macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    ChkERRSTATUS                                          |
|                                                          |
\----------------------------------------------------------/

Check for the underrun or overrun state after execution of a variable data command to the 8514/A graphics adapter.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

ChkERRSTATUS macro SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQ                                                 |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A adapter input queue to have a minimum number of words of free space. The queue may contain up to eight words. The number of words still to be dequeued can be ascertained at any time.

MinQSpaceIf at least this many words are available in the queue, fall out of wait loop. This parameter must be present.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQ macro MinQSpace,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    outwQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a word value to the 8514/A input queue.

Port The port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data The immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outwQ macro Port,Data,SaveRegs 

/--- MACRO ------------------------------------------------\
|                                                          |
|    outbQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a byte value to the 8514/A input queue. This macro differs from outwQin that it is assumed that only the low half of the AX register needs to be loaded. A slight saving in code size is achieved thereby.

Port A port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data An immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outbQ macro Port,Data,SaveRegs

Bit-Plane Model

The bit-plane memory in the adapter is arranged in planes of 1024 x 1024 bits. The displayed data is taken from the low 1024 x 768 or 640 x 480 bits . The undisplayed bit-plane memory is used by the adapter as auxiliary storage for functions, like area-fill working storage, as a cache for programmable character sets and marker drawing.

The number of planes available depends on the adapter mode and the amount of video RAM installed, up to a maximum of 32 planes. They are numbered from 0 to 31, with plane 0 associated with bit 0 of the color index. The 8514 display driver provides the following memory mapping for high- resolution mode: 

     /--------------------------------------------------------\
     |                                                        |
     |                                                        |
     |                   onscreen area                        |
     |                                                        |
     |                                                        |
     | (32x32)   64      128      196                         |
     | (40x40)   80      160      240                         |
     | (64x64)  128      256                                  |
 768 |--------------------------------------------------------|
     | ptr   | ptr   | ptr   | ptr   | work  |                |
     | and   | xor   | save  | color | area  | SaveScreenBits |
     | mask  | mask  | area  | bitmp |       | area           |
 848 |--------------------------------------------------------|
     |                      Pattern Cache                     |
 864 |--------------------------------------------------------|
     |                                                        |
     |                                                        |
     |     Font storage area and 3-op BLT temporary space     |
     |                                                        |
     |                                                        |
1023 \--------------------------------------------------------/



This chapter is based in part on the VESA SVPMI (Video Electronics Standards Association Super VGA Protect Mode Interface) proposal.

Display Device Driver Reference for OS/2:OS/2 Version Compatibility Considerations

Retrieved from "https://www.edm2.com/index.php?title=Display_Device_Driver_Reference_for_OS/2&oldid=26986"