Planar DX/PCI, Dome M2/PCI, RX/PCI, Dome DX/PCI, Dome RX/PCI User Manual

Dome® Display Controllers

DX/PCI, M2/PCI, RX/PCI

PRODUCT DEVELOPER’S GUIDE

Windows XP Windows 2000 Windows NT 4.0 Solaris 2.x

www.planar.com

systems, inc. It is the exclusive property of DOME. 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 limited to the implied warranties of merchantability or fitness for a particular 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 (781) 895-1155 phone (781) 895-1133 fax Internet address for product information: Internet address for sales information: Internet address for technical support: World Wide Web site:

www.dome.com

info@dome.com sales@dome.com support@dome.com

Part No. 41-DEVM-01 Product No. 55-M2PCI2, 55-RXPCI2, 55-DXPCI2 June 2002

DOME is a registered trademark and Calibration TQA, DIMPL, DimplX, M2/PCI, RX/PCI, and DX/PCI are trademarks of DOME imaging systems, inc. Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or in other countries. PS/2 is a trademark of International Business Machines Corporation. Sun and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. X Window System is a trademark of The Open Group.

Contents

iii

About This Guide

Board Architecture

DX/PCI Board Architecture 2 M2/PCI Board Architecture 3 RX/PCI Board Architecture 4 Gamma Correction and the 10-Bit DAC 5

Gamma correction 5 Accessing the gamma correction tables 6

Dynamic-Link Library

DLL Data Types 8

DOME types 8

Windows types and structures 8 Windows NT DLL 9 Windows 2000 DLL 10

Windows 2000 DLL modes 10

Changing displays in the Windows 2000 virtual desktop 12

vii

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

Using functions that require HDC and

screen-number parameters 13

Using functions that do not include HDC and

screen-number parameters 14

Specific Functions for Windows 2000 in the DLL 15

| Contents

DLL Functions 16

DGetDriverVersion 18

DGetDriverVersionMM 19

DGetLibraryVersion 21

DGetBoardType 22

DGetBoardTypeMM 24

DGetNumBoards 26

DGetNumScreens 27

DGetMaxScreens 28

DGetScreenDimensions 29

DGetScreenPlacement 31

DSetBrightness 33

DGetBrightness 34

DSetContrast 35

DGetContrast 36

DGetNumGCTBits 37

DGetNumGCTBitsMM 38

DGetNumGDIBits 39

DGetNumGDIBitsMM 40

DGetSisterDisplayRegPathMM 42

DGetSisterDisplayNumberMM 43

DDirectBlt 44

DGetPaletteTypeMM 46

DSetGCT 47

DGetGCT 49

DSetStartupGCT 51

DCancelStartupGCT 53

DGetRefreshRate 54

DGetRefreshRateMM 55

DCalibratorInit 56

DCalibratorMeasure 59

DGetFtLamScale 61

DSerialCmd 62

Contents |

DOME MDlib API Function Reference

MDlib API Types 66 MDlib API Structures 67

DMdVersion Structure 67

DMdCopyRect Structure 69

DMdFillRect Structure 70

DMdDev Structure 71 MDlib API Functions 73

DMdOpen 74

DMdFdOpen 75

Close 76

RefreshRate 77

FbVideo 78

MapFb 79

UnmapFb 81

FbSize 82

FbWidth 83

FbHeight 84

FbPitch 85

FbType 86

BitsPerPixel 87

CopyRects 88

FillRects 90

InitCmap 92

WriteCmap 93

UpdateCmap 95

ReadCmap 96

InitGCT 98

WriteGCT 99

UpdateGCT 101

ReadGCT 102

Index 103

About This Guide

The

Product Developer’s Guide

the DOME DX/PCI™, M2/PCI™, and RX/PCI™ display controllers (boards), as well as the data types and functions specific to DOME and Windows types and structures used in the dynamic-link library and to the MDlib API types and structures for Solaris.

Purpose

This guide explains how to develop applications with these libraries:

vii

describes the architecture of

• DOME

operating systems

• DOME® MDlib application programming interface for

Solaris™ operating systems

Audience

This guide serves developers who are writing software applications for the DOME boards. You should have programming experience with either Windows or Solaris operating systems.

Use this table to find the section related to your operating system.

For this operating system… Go to this section…

• Windows XP

• Windows 2000

• Windows NT® 4.0

mdpcint

dynamic-link library for Windows

Chapter 2, “Dynamic-Link Library” on page 7

Solaris 2.x Chapter 3, “DOME MDlib API

Function Reference” on page 65

viii

| About This Guide

Conventions

This documentation uses the conventions shown in this table.

This convention... Indicates...

Monospaced type

Italic type

Bold type File -> Open

<Key>

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

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

Menu selection: Select the

Key name such as A note of important information regarding a

particular topic or procedure. A caution that can prevent potential

damage to hardware or software.

A helpful tip or an alternative method of performing a procedure.

File

menu, then

<Enter>.

Open

What’s Inside

This table summarizes the organization of this guide.

This chapter… Provides…

About This Guide |

Chapter 1 Board Architecture

Chapter 2 Dynamic-Link Library (Windows)

Chapter 3 DOME MDlib API Function Reference

(Solaris)

• Architecture drawings for the DX/PCI, M2/PCI, and RX/PCI boards

• 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

• An explanation of the DOME data types and detailed descriptions of each DLL function

• Logical organization of the functions; for example,

DSetGCT

is followed by

DGetGCT

• Detailed descriptions of the types, structures, and functions of the DOME MDlib API (Use these functions with Solaris operating systems only.)

• Logical organization of the functions, in the order of their appearance as members of the

DMdDev

structure

| About This Guide

Related Documentation

For more information about your board or related DOME products, refer to these books:

• DX/PCI Display Controller Installation Guide

• M2/PCI Display Controller Installation Guide

• RX/PCI Display Controller Installation Guide

• Calibration TQA User’s Guide

• DIMPL Library Reference

Board Architecture

In This Chapter

• DX/PCI Board Architecture 2

• M2/PCI Board Architecture 3

• RX/PCI Board Architecture 4

• Gamma Correction and the 10-Bit DAC 5

| Board Architecture

DX/PCI Board Architecture

The DX/PCI™ display controller (board) is a single- or dual-headed, 8-bit framebuffer with an 8-bit digital interface.

The figure below shows these significant features of the board architecture:

• A highly optimized PCI local bus that provides 32-bit or 64-bit, 66 MHz transfers at speeds exceeding 500 MB per second

• 32 MB of DDR SDRAM (double data rate synchronous dynamic random access memory) that supports a 3-megapixel grayscale or pseudocolor display and a 5-megapixel grayscale display

• Can drive two digital displays in portrait or landscape mode on the C3 flat-panel system and two digital displays in portrait mode on the C5 flat-panel system

Digital Video

DVI

Digital Video

PCI Interface

64-bit 66 MHz

ROM

DX board architecture

DVI Driver

Mesquite V

DVI Driver

128

32 MB

DDR SDRAM

M2/PCI Board Architecture

The M2/PCI™ display controller (board) is a singleor dual-headed, 8-bit framebuffer with a 10-bit DAC (digital-to-analog converter).

The figure below shows these significant features of the board architecture:

• A highly optimized PCI local bus that provides 64-bit, 66 MHz transfers at speeds exceeding 500 MB per second

• 32 MB of DDR SDRAM that supports an 8 bits per pixel grayscale or pseudocolor display and a 32 bit per pixel truecolor display

• Supports double buffering, overlay, and stereo configurations

M2/PCI Board Architecture |

• Can drive two analog displays in portrait or landscape mode.

RGB DAC

PCI Interface

64-bit 66 MHz

ROM

M2 board architecture

Mesquite V

RGB DAC

128

32 MB

DDR SDRAM

Analog Video

DVI

Analog Video

DVI

| Board Architecture

RX/PCI Board Architecture

The RX display controller is a dual-headed, 8-bit framebuffer with a 10-bit DAC.

The figure below shows these significant features of the board architecture:

• A highly optimized PCI local bus that provides 64-bit, 66 MHz transfers at speeds exceeding 500 MB per second

• 32 MB of DDR SDRAM supports a 4- or 5-megapixel grayscale display (as well as double-buffered and/or stereo display)

• Can drive two analog displays in portrait or landscape mode

RX board architecture

PCI Interface

64-bit 66 MHz

ROM

Video

DAC

Mesquite V

Video

DAC

128

32 MB

DDR SDRAM

Gamma Correction and the 10-Bit DAC |

Gamma Correction and the 10-Bit DAC

All DOME display controllers use a 10-bit DAC in their video output circuitry. Nearly all competitive 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 display. An 8-bit DAC can send no more than 256 different analog values to the display, 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 available to display an image. With such a reduction, critical image details can be lost.

Displays do not produce a linear response across the full range of pixel values. If there are 256 possible analog values, the change in luminance from value 0 (zero) to value 1 (one) differs from the change of value 127 to 128. Likewise, doubling the pixel value sent to the display does not precisely double the brightness emitted.

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

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

. With this technique, the DAC’s lookup

| Board Architecture

Accessing the gamma correction tables

The 10-bit DAC on the DOME boards can produce up to 1024 distinct analog values. Thus, the board can perform gamma correction and send 256 distinct pixel values to the display, to produce a truer, more accurate grayscale image.

The flat-panel method is somewhat different but still allows more than 256 display value. The interface to the flat-panel driver is the same as that for the traditional display boards.

You can access the

gamma correction tables

(GCTs) in both

Windows® and Solaris™ operating systems.

GCTs in Windows

If you are running a Windows operating system, use the dynamic link library (DLL) provided with the DOME Windows driver to set the GCT. For more information, see “DSetGCT” on page 47.

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 running a Solaris operating system, initialize the GCT to a linear ramp and load it into the hardware with the

InitGCT

function (page 98) of the MDlib API (application

programming interface).

Dynamic-Link Library

In This Chapter

• DLL Data Types 8

• Windows NT DLL 9

• Windows 2000 DLL 10

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

• Specific Functions for Windows 2000 in the DLL 15

• DLL Functions 16

| Dynamic-Link Library

DLL Data Types

The

mdpcint

functions that provide an application interface to specific driver functionality. This section describes the data types specific to DOME and the Windows types and structures used in the DLL.

DOME types

dynamic link library (DLL) is a group of

The standard C types of

char, int

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 2 bytes 4 bytes

SBYTE UBYTE

SWORD UWORD

SDWORD UDWORD

Windows types and structures

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

, and

long

can mean

Type or Structure Deﬁnition

DWORD

HDC

SIZE

POINT

Unsigned 4 bytes Handle to display-device context

SIZE

structure as defined on page 29

POINT

structure as defined on page 31

Windows NT DLL

Windows NT DLL |

All DOME Windows drivers include the

mdpcint.dll

library. This DLL provides an application interface to the driver.

When you work in Windows NT® 4.0-compatible mode, use only those functions without the MM sufﬁx.

Other functions listed in this chapter are not available for the Windows NT operating system; these functions all have the MM sufﬁx.

| Dynamic-Link Library

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 signiﬁcant 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 conﬁguration, programs written for Windows NT 4.0 will work unchanged under Windows 2000 with the new DLL.

The Windows 2000 DLL also applies to the Windows XP operating system. For an XP system, follow the instructions for the Windows 2000 DLL using your operating system.

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

Each function’s parameters determine the mode. Where possible, function names and parameters in the Windows 2000 DLL use the same names and parameters that they used in previous versions. The main difference among the modes is in the way applications use the parameters.

Windows 2000 DLL | 11

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

12 | Dynamic-Link Library

Multi-monitor mode

Multi-monitor mode works with any Windows 2000 or Windows XP 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 display.

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

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

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 displaydevice context) and screen number, the modes differ as follows:

• In Windows NT 4.0-compatible modes (full and partial), the HDC is from any screen display, and the screen number is the Windows NT 4.0 virtual screen number.

• 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 for the particular display and supply it as the first parameter to the functions. If the application wants the DLL to create the hdc, it uses NULL as the first parameter. Otherwise, the DLL creates an hdc using the display number. For an example of each method, see “DGetDriverVersionMM” on page 19.

• The hdc is always used for unattached displays.

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

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

Devices

(the number shown via Identify minus one).

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

14 | Dynamic-Link Library

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 |

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

Functions that did not previously include a screen-number parameter are obsolete in multi-monitor mode. Those that still provide useful information have been rewritten with the MM sufﬁx and hdc and display-number parameters.

Example For example, Windows NT 4.0-compatible applications use

the DGetBoardType function like this:

WIN2K_DISPLAY_NUMBER;

DGetBoardType (HDC hdc, UWORD FAR * lpRetType)

Multi-monitor applications use DGetBoardType like this:

DGetBoardTypeMM (HDC hdc, UWORD nDisplay,

UWORD FAR * lpRetType)

DGetMaxScreens and DGetNumBoards are obsolete in

both modes.

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.

Specific Functions for Windows 2000 in the DLL | 15

Speciﬁc Functions for Windows 2000 in the DLL

These functions exist only in multi-monitor mode and are only available 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.

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.

16 | Dynamic-Link Library

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… Go to page…

is followed by DGetGCT.

DGetDriverVersion

DGetDriverVersionMM

DGetLibraryVersion

DGetBoardType

DGetBoardTypeMM

DGetNumBoards

DGetNumScreens

DGetMaxScreens

DGetScreenDimensions

DGetScreenPlacement

DSetBrightness

18 19 21 22 24 26 27 28 29 31 33

DGetBrightness

DSetContrast

DGetContrast

34 35 36

(Cont.)

DLL Functions | 17

For a description of this function… Go to page…

DGetNumGCTBits

DGetNumGCTBitsMM

DGetNumGDIBits

DGetNumGDIBitsMM

DGetSisterDisplayRegPathMM

DGetSisterDisplayNumberMM

DDirectBlt

DGetPaletteTypeMM

DSetGCT

DGetGCT

DSetStartupGCT

37 38 39 40 42 43 44 46 47 49 51

DCancelStartupGCT

DGetRefreshRate

DGetRefreshRateMM

DCalibratorInit

DCalibratorMeasure

DGetFtLamScale

DSerialCmd

53 54 55 56 59 61 62

18 | DGetDriverVersion

DGetDriverVersion

(Windows NT, Windows 2000 full Windows NT 4.0 compatible mode)

Purpose Use DGetDriverVersion to return the version number of

the DOME Windows driver.

Syntax

DWORD DGetDriverVersion (hdc, lpwDriverVersion)

Parameter T ype Name Description

HDC hdc

UWORD FAR * wDriverVer-

sion

Handle to the displaydevice context.

Pointer to UWORD. It is filled in with a hexadecimal value. The high byte is the version number, and the low byte 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.

Example This example returns the driver version in wDriverVersion.

#include <mdpcint.h> { HDC hdc; UWORD wDriverVersion; DWORD dwRetCode; dwRetCode = DGetDriverVersion (hdc,

&wDriverVersion); return dwRetCode; }

Planar DX/PCI, Dome M2/PCI, RX/PCI, Dome DX/PCI, Dome RX/PCI User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual