Planar Dome Md2/PCI Instruction Manual

Dome
®
Display Controller
Md2/PCI, Md4/PCI, Md5/PCI, Md8/PCI
PRODUCT DEVELOPER’S GUIDE
www.planar.com
Windows 2000
Windows NT 4.0
Solaris 2.x

Copyright © DOME®imaging systems, inc., 2000. All rights reserved.
This document contains proprietary information of DOME imaging
systems, inc. It is DOME’s exclusive property. It may not be reproduced
or transmitted, in whole or in part, without a written agreement from
DOME. No patent or other license is granted to this information.
The software, if any, described in this document is furnished under a
license agreement. The software may not be used or copied except as
provided in the license agreement.
DOME imaging systems, inc. provides this publication as is without
warranty of any kind, either express or implied, including but not lim-
ited to the implied warranties of merchantability or fitness for a particu-
lar purpose. DOME may revise this document from time to time without
notice. Some states or jurisdictions do not allow disclaimer of express or
implied warranties in certain transactions; therefore, this statement may
not apply to you.
Information in this document about products not manufactured by
DOME is provided without warranty or representation of any kind, and
DOME will not be liable for any damages resulting from the use of such
information.
DOME imaging systems, inc.
400 Fifth Avenue
Waltham, MA 02451-8738
[phone] phone
[phone] fax
Internet address for product information: [email protected]
Internet address for sales information: [email protected]
Internet address for technical support: [email protected]
World Wide Web site: www.dome.com
Part No. 41-DEVPCI-03
Product Nos. 55-MD2PCI2, 55-MD4PCI2, 55-MD5PCIB, 55-MD8PCI
October 2000
DOME is a registered trademark and DIMPL, DimplX, Calibration TQA,
Md2/PCI, Md4/PCI, Md5/PCI, and Md8/PCI are trademarks of DOME
imaging systems, inc. Microsoft, Windows, and Windows NT are trade-
marks of Microsoft Corporation. PS/2 is a trademark of International
Business Machines Corporation. Sun and Solaris are trademarks of
Sun Micro-systems, Inc. X Window System is a trademark of the
Massachusetts Institute of Technology.

Contents iii
Contents
About This Guide vi
Purpose vi
Audience vi
Conventions vii
What’s in this guide viii
Related documentation viii
Chapter 1: Board Architecture 1
Md2/PCI Board Architecture 2
Md4/PCI Board Architecture 3
Md5/PCI Board Architecture 4
Md8/PCI Board Architecture 5
Gamma Correction and the 10-Bit DAC 6
Gamma correction 6
Accessing the gamma correction tables 7
Chapter 2: Dynamic Link Library 9
DLL Data Types 10
DOME types 10
Windows types and structures 10
Windows NT DLL 11
Windows 2000 DLL 12
Windows 2000 DLL modes 12
Changing displays in the Windows 2000
virtual desktop 14
Using Functions in Multi-Monitor and
Windows NT 4.0-Compatible Modes 15
Using functions that require HDC and
screen-number parameters 15
Using functions that do not include HDC and
screen-number parameters 16

iv PCI Products Developer’s Guide
New Functions in the Windows 2000 DLL 18
DLL Functions 19
DGetDriverVersion 21
DGetDriverVersionMM 23
DGetLibraryVersion 25
DGetBoardType 26
DGetBoardTypeMM 28
DGetNumBoards 30
DGetNumScreens 31
DGetMaxScreens 32
DGetScreenDimensions 33
DGetScreenPlacement 35
DGetNumGCTBits 37
DGetNumGCTBitsMM 38
DGetNumGDIBits 39
DGetNumGDIBitsMM 40
DGetSisterDisplayRegPathMM 42
DGetSisterDisplayNumberMM 44
DDirectBlt 45
DGetPaletteTypeMM 47
DSetGCT 48
DGetGCT 50
DSetStartupGCT 52
DCancelStartupGCT 54
DGetRefreshRate 55
DGetRefreshRateMM 56
DCalibratorInit 57
DCalibratorMeasure 60
DGetFtLamScale 62
DSerialCmd 64

Contents v
Chapter 3: DOME MDlib API Function Reference 67
MDlib API Types 68
MDlib API Structures 69
DMdVersion Structure 69
DMdCopyRect Structure 71
DMdFillRect Structure 72
DMdDev Structure 73
MDlib API Functions 75
DMdOpen 76
DMdFdOpen 77
Close 78
RefreshRate 79
FbVideo 80
MapFb 81
UnmapFb 83
FbSize 84
FbWidth 85
FbHeight 86
FbPitch 87
FbType 88
BitsPerPixel 89
CopyRects 90
FillRects 92
InitCmap 94
WriteCmap 95
UpdateCmap 97
ReadCmap 98
InitGCT 100
WriteGCT 101
UpdateGCT 103
ReadGCT 104
Index 107

vi PCI Products Developer’s Guide
About This Guide
Read this section for an overview of how to use this guide.
Purpose
This guide describes the architecture of the Md2/PCI,™
Md4/PCI,™Md5/PCI,™and Md8/PCI™ display control-
lers (boards). It explains how to develop applications with
these libraries:
• Dynamic Link Library (DLL) for Windows
®
operating
systems
• DOME
®
MDlib Application Program Interface (API) for
Solaris™ operating systems
Audience
This guide serves developers who are writing software
applications for the Md2/PCI, Md4/PCI, Md5/PCI, or
Md8/PCI board. You should have programming experi-
ence with either Windows or Solaris operating systems.
Use this table to find the section for your operating system.
For this operating
system… See this section…
Windows 2000 or
Windows NT
®
Chapter 2, “Dynamic Link Library”on
page 9
Solaris 2.x Chapter 3, “DOME MDlib API
Function Reference” on page 67

About This Guide vii
Conventions
This table explains the conventions used in the guide.
This
convention... Indicates...
Monospaced
type
Computer code or directory; backslash (\)
indicates continuation of previous line of
UNIX code.
Italic type New or technical term; book title; or variable,
such as x.
Bold type
File -> Open
Menu selection.
Select Open from the File menu.
<Key> Key name, such as <Enter>.
Information you should know regarding a
particular topic or procedure.
Information that can prevent potential
damage to hardware or software.
A helpful tip or an alternative method of
performing a procedure.

viii PCI Products Developer’s Guide
What’s in this guide
This table describes the organization of the guide.
Related documentation
For more information about your board or related
DOME products, refer to these books:
• Md2/PCI Display Controller Installation Guide
• Md4/PCI Display Controller Installation Guide
• Md5/PCI Display Controller Installation Guide
• Md8/PCI Display Controller Installation Guide
• Calibration TQA User’s Guide
• DIMPL Library Reference
This chapter… Provides…
Chapter 1
Board Architecture Architecture drawings for the Md2/PCI, Md4/PCI, Md5/PCI, and
Md8/PCI boards, and an explanation
of gamma correction and 10-bit DACs.
Chapter 2
Dynamic Link Library Detailed descriptions of the data types and functions of the DOME DLL for
Windows operating systems. It
explains the DOME data types and
gives detailed descriptions of each
DLL function.The functions are
organized logically. For example,
DSetGCT is followed by DGetGCT .
Chapter 3
DOME MDlib API
Function Reference
Detailed descriptions of the types,
structures, and functions of the DOME
MDlib API. Use these functions with
Solaris operating systems only.
Functions are organized logically, in
the order in which they appear as
members of the DMdDev structure.

Board Architecture 1
Chapter 1
Board Architecture
In This Chapter
• Md2/PCI Board Architecture 2
• Md4/PCI Board Architecture 3
• Md5/PCI Board Architecture 4
• Md8/PCI Board Architecture 5
• Gamma Correction and the 10-Bit DAC 6

2 Chapter 1
Md2/PCI Board Architecture
This figure shows the Md2/PCI™ board architecture.
Md2/PCI board architecture
PCI
Local
Bus
Luminance
Port Masking
DRAM VGA
Controller VGA
DRAM
GUI & Copy
Accelerator
(I-128)
Video Memory
4 MB VRAM
10-bit DAC
10-bit DAC
Video
Video
32
128 64
Calibrat o
in

Board Architecture 3
Md4/PCI Board Architecture
This figure shows the Md4/PCI™ board architecture.
Md4/PCI board architecture
Video Memory
8 MB VRAM
128
PCI
Local
Bus
Luminance
Port* Masking
DRAM VGA
Controller
VGA
DRAM
GUI & Copy
Accelerator
(I-128)
10-bit DAC
10-bit DAC
Video
Video
Optional VGA Video
* PS/2 or access bus supported
32
128 128
Calibrat o
in

4 Chapter 1
Md5/PCI Board Architecture
This figure shows the Md5/PCI™ board architecture.
Md5/PCI board architecture
Video
Memory
8 MB VRAM
PCI
Local
Bus
Luminance
Port* VGA
Controller
VGA
DRAM
GUI & Copy
Accelerator
(I-128) 10-bit DAC Video
Optional VGA Video
* PS/2 or access
bus supported
32 128 128
Calibrat o
in

Board Architecture 5
Md8/PCI Board Architecture
This figure shows the Md8/PCI™ board architecture.
Md8/PCI board architecture
Video
Memory
8 MB VRAM
PCI
Local
Bus
GUI & Copy
Accelerator
(I-128) 10-bit DAC
VGA
Controller
Luminance
Calibration
Port* VGA
DRAM
Video
Optional VGA Video
* PS/2
32
32 128 128

6 Chapter 1
Gamma Correction and the 10-Bit DAC
The Md2/PCI, Md4/PCI, Md5/PCI, and Md8/PCI display
controllers (boards) use a 10-bit digital-to-analog converter
(DAC) in their video output circuitry. Nearly all competi-
tive display boards use 8-bit DACs.
The DAC converts the digital image data stored in the
board’s video memory to an analog signal that drives the
monitor. An 8-bit DAC can send no more than 256 different
analog values to the monitor, while a 10-bit DAC can
provide up to 1024 values. An 8-bit DAC can therefore
result in as much as a 30% reduction in gray shades avail-
able to display an image. With such a reduction, critical
image details can be lost.
Display monitors do not produce a linear response across
the full range of pixel values. If there are 256 possible ana-
log values, the change in luminance from value 0 (zero) to
value 1 (one) is different than the change from value 127 to
128. Likewise, doubling the pixel value sent to the monitor
does not precisely double the displayed brightness.
Gamma correction
This nonlinearity can be corrected using a method known
as
gamma correction . With this technique, the DAC’s lookup
table compensates for the nonlinearity by adjusting the
values sent to the monitor.
An 8-bit DAC can produce only 256 such values, and
a nonlinear translation must sacrifice some of these values.
For this reason, gamma correction performed with an 8-bit
DAC sends substantially fewer than 256 distinct values to
the monitor.

Board Architecture 7
The 10-bit DAC on the Md2/PCI, Md4/PCI, Md5/PCI, and
Md8/PCI boards can produce up to 1024 distinct analog
values. Thus, the boards can perform gamma correction
and send 256 distinct pixel values to the monitor, to pro-
duce a truer, more accurate grayscale image.
Accessing the gamma correction tables
You can access the gamma correction tables (GCTs) in both
Windows
®
and Solaris™ operating systems.
GCTs in Windows
If you are using a Windows operating system, apply the
Dynamic Link Library (DLL) provided with the DOME
®
Windows driver to set the GCT. For more information,
see “DSetGCT” on page 48.
The Windows operating system uses 8-bit color. Once
you set the GCT, the DOME Windows driver translates
all palette changes to the 10-bit value.
GCTs in Solaris
If you are using a Solaris operating system, initialize
the GCT to a linear ramp and load it into the hardware
with the
InitGCT
function (page 100) of the MDlib API.

Dynamic Link Library 9
Chapter 2
Dynamic Link Library
In This Chapter
• DLL Data Types 10
• Windows NT DLL 11
• Windows 2000 DLL 12
• Using Functions in Multi-Monitor and
Windows NT 4.0-Compatible Modes 15
• New Functions in the Windows 2000 DLL 18
• DLL Functions 19

10 Chapter 2
DLL Data Types
The
mdpcint
Dynamic Link Library (DLL) is a group
of functions that links Windows operating systems and
DOME software applications. This section describes the
data types specific to DOME as well as the Windows
types and structures used in the DLL.
DOME types
The standard C types of
char
,
int
, and
long
can mean
different things to different compilers. The DOME types,
however, are strictly defined as signed or unsigned and
by byte size, as shown in this table.
Windows types and structures
The DLL uses standard Windows types and structures, as
shown in this table.
DOME Types
Size Signed Unsigned
1 byte SBYTE UBYTE
2 bytes SWORD UWORD
4 bytes SDWORD UDWORD
Windows Types and Structures
Type or Structure Definition
DWORD Unsigned 4 bytes
HDC Handle to display-device context
SIZE SIZE structure as defined on page 33
POINT POINT structure as defined on page 35

Dynamic Link Library 11
Windows NT DLL
All DOME Windows drivers include the
mdpcint.dll
library. This DLL provides an application interface to
the driver.
When working in Windows NT
®
4.0-compatible mode,
use only functions without the MM suffix.
Other functions listed in this chapter are not available
for the Windows NT operating system; these include
all functions with the MM suffix.

12 Chapter 2
Windows 2000 DLL
All DOME Windows drivers include the
mdpcint.dll
library. This DLL provides an application interface to
the driver.
The Windows
®
2000 DLL has some significant differences
from previous versions of the DLL. For example, the new
version of
mdpcint.dll
is not backward-compatible. It
does not run on the Windows NT 4.0 operating system.
But, given a Windows NT 4.0-compatible screen configura-
tion, programs written for Windows NT 4.0 will work
unchanged under Windows 2000 with the new DLL.
Windows 2000 DLL modes
Most functions in the Windows 2000 DLL have these
three modes:
• Full Windows NT 4.0-compatible mode
• Partial Windows NT 4.0-compatible mode
• Multi-monitor mode
The parameters to each function determine the mode.
Where possible, function names and parameters in the
Windows 2000 DLL use the same names and parameters
as they did in previous versions. The main difference
among the modes is in the way applications use the
parameters.