Planar Dome Md2/PCI, Dome Md4/PCI, Dome Md5/PCI, Dome Md8/PCI Developer's Manual

Dome® Display Controller

Md2/PCI, Md4/PCI, Md5/PCI, Md8/PCI

PRODUCT DEVELOPER’S GUIDE

Windows 2000
Windows NT 4.0
Solaris 2.x

www.planar.com

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:
Internet address for sales information:
Internet address for technical support:
World Wide Web site:

www.dome.com

[e-mail]
[e-mail]
[e-mail]

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
systems

• DOME
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…

®

operating

®

MDlib Application Program Interface (API) for

Windows 2000 or
Windows NT

Solaris 2.x Chapter 3, “DOME MDlib API

®

Chapter 2, “Dynamic Link Library” on
page 9

Function Reference” on page 67

About This Guide vii

Conventions

This table explains the conventions used in the guide.

This
convention... Indicates...

Monospaced

type

Italic type

Bold type
File -> Open

<Key>

Computer code or directory; backslash (\)
indicates continuation of previous line of
UNIX code.

New or technical term; book title; or variable,
such as

Menu selection.
Select Open from the File menu.

Key name, such as
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.

x.

<Enter>.

viii PCI Products Developer’s Guide

What’s in this guide

This table describes the organization of the guide.

This chapter… Provides…

Chapter 1
Board Architecture

Chapter 2
Dynamic Link Library

Chapter 3
DOME MDlib API
Function Reference

Architecture drawings for the
Md2/PCI, Md4/PCI, Md5/PCI, and
Md8/PCI boards, and an explanation
of gamma correction and 10-bit DACs.

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

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

is followed by

DMdDev

DGetGCT

structure.

.

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

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.

Video Memory

4 MB VRAM

PCI

Local

Bus

32

Luminance
Calibr at o

in

Port

Md2/PCI board architecture

128

GUI & Copy

Accelerator

(I-128)

Masking

DRAM

64

VGA

Contr oller

10-bit DAC

Video

Video

10-bit DAC

VGA

DRAM

Board Architecture 3

Md4/PCI Board Architecture

This figure shows the Md4/PCI™ board architecture.

Video Memory

8 MB VRAM

128

128

128

10-bit DAC

Video

PCI

Local

Bus

GUI & Copy

32

Accelerator

(I-128)

Luminance
Calibr at o

in

Port*

* PS/2 or access bus supported

Md4/PCI board architecture

Masking

DRAM

10-bit DAC

VGA

Contr oller

VGA

DRAM

Video

Optional VGA Video

4 Chapter 1

Md5/PCI Board Architecture

This figure shows the Md5/PCI™ board architecture.

PCI

Local

Bus

GUI & Copy

32

Accelerator

Luminance
Calibr at o

in

Port*

* PS/2 or access

bus supported

(I-128)

Md5/PCI board architecture

Video

128 128

Memory

8 MB VRAM

VGA

DRAM

VGA

Contr oller

10-bit DAC

Video

Optional VGA Video

Board Architecture 5

Md8/PCI Board Architecture

This figure shows the Md8/PCI™ board architecture.

PCI

Local

Bus

GUI & Copy

32

Accelerator

Luminance
Calibration

Port*

* PS/2

(I-128)

Video

128 128

Memory

8 MB VRAM

32

VGA

DRAM

Md8/PCI board architecture

VGA

Controller

10-bit DAC

Video

Optional VGA Video

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

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.

. With this technique, the DAC’s lookup

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
Windows

®

and Solaris™ operating systems.

gamma correction tables

(GCTs) in both

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

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
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.

Size Signed Unsigned

1 byte

Dynamic Link Library (DLL) is a group

char, int

DOME Types

SBYTE UBYTE

, and

long

can mean

2 bytes
4 bytes

SWORD UWORD
SDWORD UDWORD

Windows types and structures

The DLL uses standard Windows types and structures, as
shown in this table.

Windows Types and Structures

Type or Structure Definition

DWORD
HDC
SIZE SIZE
POINT POINT

Unsigned 4 bytes
Handle to display-device context

structure as defined on page 33

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
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

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

is

mdpcint.dll

not

backward-compatible. It

• 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.

Dynamic Link Library 13

Full Windows NT 4.0-compatible mode

A system that is fully compatible with the Windows NT

4.0 operating system meets these criteria:

• All screens are driven by the same type of DOME

board, all at the same resolution.

• All screens combine to make a rectangle with no gaps.

• All screens are in nonnegative space.

Partial Windows NT 4.0-compatible mode

Partial Windows NT 4.0-compatible mode includes
these features:

• One system can include both DOME and other brands

of boards.

• One system can run different DOME board types

simultaneously.

• Screens do not have to combine to make a rectangle.

• All DOME screens are in nonnegative space.
When running in partial Windows NT 4.0-compatible

mode, these

Get

routines return an error, unless all

DOME displays have the same value:

DGetBoardType

•

•

DGetDriverVersion
DGetNumGCTBits

•

•

DGetRefreshRate

DGetNumScreens

returns the number of DOME screens

only (in all modes).

14 Chapter 2

Multi-monitor mode

Multi-monitor mode works with any Windows 2000
desktop. Multi-monitor mode includes these features:

• One system can include both DOME and other brands

of boards.

• One system can run different DOME board types

simultaneously.

• One board can support different palette types on

each monitor.

• Screens do not have to combine to make a rectangle.

• Screens can be unattached from the Windows

desktop.

Changing displays in the Windows 2000
virtual desktop

If you change any of the display properties in the
Windows 2000 virtual desktop (for example, if you
change resolution, placement, or detachment), you
must unload and then reload the DLL as follows:

• To unload the DLL, exit all programs that are using

the DLL, including the DOME tab.

• To reload the DLL, start any program that accesses

the DLL.

Dynamic Link Library 15

Using Functions in Multi-Monitor and
Windows NT 4.0-Compatible Modes

Multi-monitor and the Windows NT 4.0-compatible
modes treat functions differently depending on the
function’s parameters. This section describes how
functions work in these modes.

Using functions that require HDC and
screen-number parameters

For functions that require both an HDC (handle to
display-device context) and screen number, the modes
differ as follows:

• In Windows NT 4.0-compatible modes (full and partial),

the

HDC

number is the

• Multi-monitor mode is signaled by combining the high

bit in the screen-number parameter with the Windows
2000 display number. The application can create the

hdc

parameter to the functions. If the application wants
the DLL to create the
parameter. Otherwise, the DLL creates a DC using
the display number. For an example of each method,
see “DGetDriverVersionMM” on page 23.

• Always use the

is from any screen display, and the screen

Windows NT 4.0 virtual screen number.

for the particular display and supply it as the first

hdc

hdc

, it uses

for unattached displays.

NULL

as the first

The Windows NT 4.0 virtual screen number is the screen
number assigned by the DLL and is independent of the
operating system. The DLL counts only DOME screens.

16 Chapter 2

The Windows 2000 display number is the same as that
passed to the GDI (graphical device interface) function

EnumDisplayDevices

(the number shown via Identify

minus one).

The GDI call uses 32-bit numbers, while the DOME DLL
uses 16-bit numbers.

Example

WIN2K_DISPLAY_NUMBER

is defined in mdpcint.h as
0x8000. This code sample shows how to cast the display
number in the DLL:

nDisplay = (UWORD) Win2000DisplayNum |

WIN2K_DISPLAY_NUMBER;

Using functions that do not include HDC and
screen-number parameters

Functions that previously did not include a screen­number parameter are obsolete in multi-monitor mode.
Those that still provide useful information have been
rewritten with the MM suffix and

hdc and display-

number parameters.

Example For example, Windows NT 4.0-compatible applications

use the

DGetBoardType (HDC hdc, UWORD FAR * lpRetType)

DGetBoardType function like this:

Multi-monitor applications use DGetBoardType
like this:

DGetBoardTypeMM (HDC hdc, UWORD nDisplay,
UWORD FAR * lpRetType)

DGetMaxScreens and DGetNumBoards are obsolete in

both modes.

Dynamic Link Library 17

DDirectBlt

is only available in Windows NT 4.0­compatible mode. Currently this function is not fully
operational: although it splits the

blt between screens

correctly, GDI does not send the driver the correct clip,
and the driver overdraws overlapping windows.

18 Chapter 2

New Functions in the Windows 2000 DLL

These functions exist only in multi-monitor mode and
are new in the Windows 2000 DLL:

DGetPaletteTypeMM

•

• DGetSisterDisplayRegPathMM

• DGetSisterDisplayNumberMM

A sister display is one of two displays being driven by
the same DOME board.

This table lists each updated function and the obsolete
function it replaces.

Multi-Monitor Functions

That Replace Obsolete Functions

This new function… Replaces this function…

DGetBoardTypeMM DGetBoardType
DGetDriverVersionMM DGetDriverVersion
DGetNumGCTBitsMM DGetNumGCTBits
DGetNumGDIBitsMM DGetNumGDIBits
DGetRefreshRateMM DGetRefreshRate

All functions with the MM suffix are available only in
Windows 2000 and work only in multi-monitor mode.
The previous versions (without the MM suffix) work in
Windows NT 4.0-compatible mode.

Dynamic Link Library 19

DLL Functions

Use the DLL functions described in this section to write
applications. The functions are listed logically; for example,

DSetGCT

For a description of this function… See page…

DGetDriverVersion 21
DGetDriverVersionMM 23
DGetLibraryVersion 25
DGetBoardType 26
DGetBoardTypeMM 28
DGetNumBoards 30
DGetNumScreens 31
DGetMaxScreens 32
DGetScreenDimensions 33

is followed by DGetGCT.

Description of DLL Functions

DGetScreenPlacement 35
DGetNumGCTBits 37
DGetNumGCTBitsMM 38
DGetNumGDIBits 39
DGetNumGDIBitsMM 40
DGetSisterDisplayRegPathMM 42
DGetSisterDisplayNumberMM 44
DDirectBlt 45
DGetPaletteTypeMM 47
DSetGCT 48
DGetGCT 50
DSetStartupGCT 52

20 Chapter 2

Description of DLL Functions (Cont.)

For a description of this function… See page…

DCancelStartupGCT 54
DGetRefreshRate 55
DGetRefreshRateMM 56
DCalibratorInit 57
DCalibratorMeasure 60
DGetFtLamScale 62
DSerialCmd 64

DGetDriverVersion 21

DGetDriverVersion

Purpose Use DGetDriverVersion to return the version number of

the DOME Windows driver.

Syntax

DWORD DGetDriverVersion (hdc, lpwDriverVersion)

DGetDriverVersion Parameters

Parameter
Type Name Description

HDC hdc Handle to the display-

device context.

UWORD FAR * wDriverVersion Pointer to UWORD.

It is filled in with a
hexadecimal value. The
high byte is the version
number , and the low b yte
is the revision number.
For example, 0x108 is
returned when you’re
using the version 1.8
driver.

Return value DWORD – zero (0) if function completed successfully;

otherwise, operating system error code.

22 DGetDriverVersion

Example This example returns the driver version in

wDriverVersion.
#include <mdpcint.h>
{

HDC hdc;
UWORD wDriverVersion;
DWORD dwRetCode;

dwRetCode + DGetDriverVersion (hdc,

&wDriverVersion);
return dwRetCode;
}

See also DGetLibraryVersion