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

Download

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

See also DSetStartupGCT

54 | DGetRefreshRate

DGetRefreshRate

(Obsolete in multi-monitor mode)

Purpose Use DGetRefreshRate to return the screen’s refresh rate.

Syntax DWORD DGetRefreshRate (hdc, lpwRefreshRate)

Parameter T ype Name Description

HDC hdc

UWORD FAR * wRefreshRate

Handle to the displaydevice context.

Pointer to UWORD. It is filled in with the refresh rate in Hertz * 100.

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

otherwise, operating system error code.

Example This example returns the refresh rate of the screen.

#include <mdpcint.h> { HDC hdc; UWORD wRefreshRate; DWORD dwRetCode; dwRetCode = DGetRefreshRate (hdc, &wRefreshRate); return dwRetCode; }

See also DGetNumScreens, DGetScreenDimensions,

DGetScreenPlacement

DGetRefreshRateMM

(Windows 2000, multi-monitor mode only)

Purpose Use DGetRefreshRateMM to return the screen’s

refresh rate.

DGetRefreshRateMM | 55

Syntax

DWORD DGetRefreshRateMM (hdc, nDisplay,

lpRefreshRate)

Parameter T ype Name Description

HDC hdc

UWORD nDisplay

UWORD FAR * lpRefreshRate

Handle to the displaydevice context.

Target display. Pointer to UWORD FAR.

It is filled in with the refresh rate in Hertz * 100.

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

otherwise, operating system error code.

Example This example returns the refresh rate of the screen.

#include <mdpcint.h> { HDC hdc UWORD nDisplay = (UWORD) Win2000DisplayNum |

WIN2K_DISPLAY_NUMBER; DWORD dwRetCode; UWORD RefreshRate; dwRetCode = DGetRefreshRateMM (NULL,

nDisplay, &lpRefreshRate); return dwRetCode; }

See also DGetScreenDimensions, DGetScreenPlacement

56 | DCalibratorInit

DCalibratorInit

Purpose Use DCalibratorInit to initialize the Calibration TQA™

system from DOME and prepare it to take measurements.

Syntax DWORD DCalibratorInit (hdc, wScreenNumber,

lpInitStruct)

Parameter T ype Name Description

HDC hdc

UWORD wScreenNumber

INIT_ CALIBRATOR_ STRUCT FAR *

InitStruct

Handle to the displaydevice context

Target screen number (zero-based)

Pointer to INIT_

CALIBRATOR_ STRUCT

structure

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

otherwise, operating system error code.

Structure This code fragment defines the INIT_CALIBRATOR_STRUCT

structure.

typedef struct

{

UWORD Version;

SDWORD MeasurementTime;

DWORD ReadTimeout;

UDWORD Reserved;

} INIT_CALIBRATOR_STRUCT;

You must set Version to 2.

DCalibratorInit | 57

MeasurementTime is the number of microseconds over which

the sample is taken in DCalibratorMeasure (page 59). This parameter must be greater than 17 and less than 1,179,630.

When measuring a periodic source such as a display, sample at an integer number of periods. Setting the proper integration time for a display at a specific frequency is essential to obtaining accurate, repeatable measurements. Each value set in MeasurementTime is equal to one (1) microsecond. Use this equation to find the integration time:

period of

one cycle

-------------------- =

integration time for one cycle

00010600

Multiply the integration time by the number of cycles you want to measure (31 cycles are recommended). For example, with a 75 Hz display, use this calculation:

----- -

× 31× 413333=

Thus, the integration time is: 413,333 microseconds = .413 seconds

ReadTimeout is the number of milliseconds to wait for data

when reading from the calibrator port. You can still use Version 1 (one) of the structure, which does

not include ReadTimeout. If you do use Version 1 (one), the

ReadTimeout

value defaults to 2000 (2 seconds), and you

must set Version to 1 (one).

58 | DCalibratorInit

Example This example initializes the DOME Calibration TQA system

and prepares it to take measurements on screen one (1).

#include <mdpcint.h> /* includes

INIT_ CALIBRATOR_STRUCT

definition */ { HDC hdc; INIT_CALIBRATOR_STRUCTInitStruct; DWORD dwRetCode; InitStruct.Version = 2; InitStruct.ReadTimeout = 2000; /* Set InitStruct.MeasurementTime using the

calculation on page 57 */

. . .

dwRetCode = DCalibratorInit (hdc, 1,

&InitStruct); return dwRetCode; }

See also DCalibratorMeasure, DGetFtLamScale

DCalibratorMeasure

Purpose Use DCalibratorMeasure to take a measurement from the

DOME Calibration TQA system and return the result.

Syntax DWORD DCalibratorMeasure (hdc, wScreenNumber,

lpdwMeasure)

Parameter T ype Name Description

DCalibratorMeasure | 59

HDC hdc

UWORD wScreenNumber

DWORD FAR * dwMeasure

Handle to the displaydevice context.

Target screen number (zero-based).

Pointer to DWORD. It is filled in with the measurement result, in the range from 0 (zero) to 65534. The number 65535 indicates a saturation error. Higher numbers indicate greater light striking the pod.

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

otherwise, operating system error code.

60 | DCalibratorMeasure

Example This example returns the screen luminance on screen one (1),

as measured by the calibration system.

#include <mdpcint.h> { HDC hdc; DWORD dwMeasure; DWORD dwRetCode; dwRetCode = DCalibratorMeasure (hdc, 1,

&dwMeasure); return dwRetCode; }

See also DCalibratorInit, DGetFtLamScale

DGetFtLamScale

Purpose Use DGetFtLamScale to get the scale factor used to convert

calibration measurement units to foot Lamberts.

Syntax DWORD DGetFtLamScale (hdc, wScreenNumber, lpdScale)

Parameter T ype Name Description

DGetFtLamScale | 61

HDC hdc

UWORD wScreenNumber

double * dScale

Handle to the displaydevice context.

Target screen number (zero-based).

Pointer to scale factor. It is filled in with the value used to convert calibrator measurement units to foot Lamberts.

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

otherwise, operating system error code.

Example This example returns the scale factor to convert the

calibration measurement units to foot Lamberts.

#include <mdpcint.h> { HDC hdc; UWORD wScreenNumber; DWORD dwRetCode; double dScale; dwRetCode = DGetFtLamScale (hdc,

wScreenNumber, &dScale); return dwRetCode; }

See also DCalibratorInit, DCalibratorMeasure

62 | DSerialCmd

DSerialCmd

Purpose Use DSerialCmd to write command bytes to the PS/2® serial

port and then read back the specified number of response bytes from the port.

Syntax

DWORD DSerialCmd (hdc, wScreenNumber, wnumCmdBytes,

lpCmdBuffer, wnumResponseBytes, lpResponseBuffer,

dwTimeout)

Parameter T ype Name Description

HDC hdc

UWORD wScreenNumber

UWORD wnumCmdBytes

Handle to the displaydevice context.

Target screen number (zero-based). This determines which board’s serial port to write to.

Number of bytes to write to the command buffer. If this is zero (0), the function reads the response bytes without writing any command bytes.

UBYTE FAR * CmdBuffer

Buffer that contains the command bytes that are written to the port. This parameter can be

NULL if

wnumCmdBytes

is zero (0).

(Cont.)

DSerialCmd | 63

Parameter T ype Name Description

UWORD wnumResponseBytes

UBYTE FAR * ResponseBuffer

DWORD dwTimeout

Number of bytes to be read from the port after the If this value is zero (0), the function returns zero (0) without waiting for a response.

Buffer to receive the response bytes. If

Cmd is sent.

wnumResponseByte

is zero (0), this

can be Number of

milliseconds to wait for the response data. If this value is zero (0), the

Timeout

NULL.

Read-

value from

InitCalibrator

is used.

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

otherwise, operating system error code.

All structures are packed on 1-byte boundaries.

64 | DSerialCmd

Example This example writes a command byte to the PS/2 serial port

and then reads back the specified number of response bytes from the port.

#include <mdpcint.h> { HDC hdc; UWORD wnumCmdBytes, wnumResponseBytes; DWORD dwTimeout; UBYTE CmdBuffer, ResponseBuffer; DWORD dwRetCode; /* Put command bytes in CmdBuffer, and set number of

command bytes and response bytes */ . . .

dwRetCode = DSerialCmd (hdc, 0, wnumCmdBytes,

&CmdBuffer, wnumResponseBytes, &ResponseBuffer,

dwTimeout); return dwRetCode; }

DOME MDlib API Function Reference

In This Chapter

• MDlib API Types 66

• MDlib API Structures 67

• MDlib API Functions 73

66 | DOME MDlib API Function Reference

MDlib API Types

The standard C types of char, int, and long can mean different things to different compilers and machine types. The MDlib API types, however, are strictly defined as signed or unsigned and by byte size, as shown below.

Size Signed Unsigned

1 byte DChar DByte

2 bytes DShort DUShort

4 bytes DLong DULong

4 bytes DBool

4 bytes DFloat

8 bytes DDouble

A DBool value can have one of two values: either zero (FALSE) or nonzero (TRUE).

A DVoid value is equivalent to the C type void. When DVoid is a return value, it returns nothing.

DError values, shown below, are the return values of

functions that might fail.

#define D_OK 0

#define DMD_ERROR_BAD_VALUE 1

#define DMD_ERROR_BAD_DEVICE 2

#define DMD_ERROR_NO_MEMORY 3

#define DMD_ERROR_BAD_GCT 4

#define DMD_ERROR_BAD_IO 5

MDlib API Structures

Use this table to quickly locate the MDlib API structures described in this section.

For this structure Go to page

MDlib API Structures | 67

DMdVersion

DMdCopyRect

DMdFillRect

DMdDev

DMdVersion Structure

Purpose The DMdVersion structure returns the version of the DOME

MDlib API.

DMdVersion is a member of the DMdDev structure returned by

the DMdOpen or DMdFdOpen call. When the program runs, it checks to see if the version of the domeMd.h header file it has used to compile matches that of the MDlib API.

67 69 70 71

Full compatibility with the API exists only if both the major and minor version numbers match. The subversion number, however, does not need to match for full compatibility.

If the major version number does not match, the program is unable to operate. When the major version number changes, backward compatibility is not provided.

68 | DMdVersion Structure

If the major version number matches, but the minor version number does not, the API retains backward compatibility; a program compiled with an older version of domeMd.h runs correctly with a newer MDlib API.

Structure This table defines the DMdVersion structure.

DMdVersion Member Description

struct {

DShort major

DByte minor

DByte sub

Major version number Minor version number Subversion number

} DMdVersion

#define DMD_MAJOR_VERSION 1

#define DMD_MINOR_VERSION 0

#define DMD_SUB_VERSION 1

DMdCopyRect Structure

Purpose The DMdCopyRect structure accelerates screen-to-

screen copying.

Structure This table defines the DMdCopyRect structure.

DMdCopyRec t Member Description

struct {

DMdCopyRect Structure | 69

DULong srcx

DULong srcy

DULong dstx

DULong dsty

The x screen coordinate of the upper-left corner pixel of the source rectangle. The upper-left corner pixel of the screen has screen coordinates (0,0). The x screen coordinate increases to the right.

The y screen coordinate of the upper-left corner pixel of the source rectangle. The upper-left corner pixel of the screen has screen coordinates (0,0). The y screen coordinate increases downward.

The x screen coordinate of the upper-left corner pixel of the destination rectangle.

The y screen coordinate of the upper-left corner pixel of the destination rectangle.

DULong width

DULong height

} DMdCopyRect

Width in pixels of the rectangle to copy.

Height in pixels of the rectangle to copy.

70 | DMdFillRect Structure

DMdFillRect Structure

Purpose The DMdFillRect structure accelerates screen filling.

Structure This table defines the DMdFillRect structure.

DMdFillRect Member Description

struct {

DULong dstx

DULong dsty

DULong width

DULong height

} DMdFillRect

The x screen coordinate of the upper-left corner pixel of the destination rectangle

The y screen coordinate of the upper-left corner pixel of the destination rectangle

Width in pixels of the rectangle to fill

Height in pixels of the rectangle to fill

DMdDev Structure

Purpose The DMdDev structure provides a pointer to the structure

that accesses to the DOME MDlib device returned by DMdOpen or DMdFdOpen. DMdDev is also called the device handle.

Structure This table defines the DMdDev structure.

DMdDev Member Description

struct {

DMdDev Structure | 71

DMdVersion version

DLong fd

DVoid (*Close) ()

DLong (*RefreshRate) ()

DBool (*FbVideo) ()

DVoid (*MapFb) ()

DVoid (*UnmapFb) ()

DLong (*FbSize) ()

DLong (*FbWidth) ()

DOME MDlib API version

File descriptor of the opened DOME MDlib device

See page 76 See page 77 See page 78 See page 79 See page 81 See page 82 See page 83

DLong (*FbHeight) ()

DLong (*FbPitch) ()

struct fbtype *(*FbType) ()

DLong (*BitsPerPixel) ()

DError (*CopyRects) ()

See page 84 See page 85 See page 86 See page 87 See page 88

(Cont.)

72 | DMdDev Structure

DMdDev Member Description

DError (*FillRects) ()

DError (*InitCmap) ()

DError (*WriteCmap) ()

DError (*UpdateCmap) ()

DError (*ReadCmap) ()

DError (*InitGCT) ()

DError (*WriteGCT) ()

DError (*UpdateGCT) ()

DError (*ReadGCT) ()

DVoid (*reserve1)

DVoid (*reserve2)

See page 90 See page 92 See page 93 See page 95 See page 96 See page 98 See page 99 See page 101 See page 102 For future use For future use

DVoid (*reserve3)

DVoid (*reserve4)

DVoid (*reserve5)

DVoid (*reserve6)

DVoid (*reserve7)

DVoid (*reserve8)

DVoid (*reserve9)

For future use For future use For future use For future use For future use For future use For future use

} DMdDev

All structure members, except both version and fd, are pointers to functions that provide the remaining functionality of the DOME MDlib API. Those functions are described in the next section, “MDlib API Functions.”

MDlib API Functions

Use this reference to the DOME MDlib API functions to write applications. The two Open functions appear first, followed by the other functions in the order of their appearance as members of the DMdDev structure.

For a description of this function… Go to page…

MDlib API Functions | 73

DMdOpen DMdFdOpen Close RefreshRate FbVideo MapFb UnmapFb FbSize FbWidth FbHeight FbPitch FbType BitsPerPixel

74 75 76 77 78 79 81 82 83 84 85 86 87

CopyRects FillRects InitCmap WriteCmap UpdateCmap ReadCmap InitGCT WriteGCT UpdateGCT ReadGCT

88 90 92 93 95 96 98

99 101 102

74 | DMdOpen

DMdOpen

Purpose Use DMdOpen to gain access to a DOME device.

Syntax DMdDev DMdOpen (name)

Parameter T ype Name Description

DChar *name

Device file of the DOME device, for example,

"/dev/m2pci0.0"

Return value Device handle if successful; otherwise, NULL.

Description DMdOpen() opens the DOME device specified by name

and returns the device handle, which provides access to the device. To close the DOME device, use the Close() member function (page 76) of the returned device handle.

Errors If DMdOpen() returns NULL, an error message prints to

stderr

Example This example opens the DOME device /dev/m2pci0.0.

#include "domeMd.h" DMdDev dev; dev = DMdOpen ("/dev/m2pci0.0");

. . .

(*dev->Close) (dev);

See also DMdFdOpen, Close, DMdDev Structure

DMdFdOpen

Purpose Use DMdFdOpen to access a DOME device if the device file

is already open.

Syntax DMdDev DMdFdOpen (fd)

Parameter T ype Name Description

DMdFdOpen | 75

DLong fd

File descriptor of the opened device file

Return value Device handle if successful; otherwise, NULL.

Description DMdFdOpen() opens the DOME device specified by the

open file descriptor fd and returns the device handle that provides access to the device. To close the DOME device, use the Close() member function (page 76) of the returned device handle.

Errors If DMdFdOpen() returns NULL, an error message prints

to stderr.

Example This example opens the DOME device /dev/m2pci0.0.

#include "domeMd.h" DMdDev dev; DLong fd; fd = open ("/dev/m2pci0.0", O_RDWR); if (fd == -1)

exit (-1);

dev = DMdFdOpen (fd);

. . .

(*dev->Close) (dev);

See also DMdOpen, Close, DMdDev Structure

76 | Close

Purpose Use Close to end access to a DOME device.

Syntax DVoid (*Close) (dev)

Parameter T ype Name Description

DMdDev dev

Device handle of the DOME device

Return value None.

Description Close() closes the DOME device previously opened with

either DMdOpen() or DMdFdOpen() . After you call Close() , you cannot access the DOME device using the old device handle.

Errors None.

Example This example closes the device handle dev.

#include "domeMd.h" DMdDev dev; dev = DMdOpen ("/dev/m2pci0.0");

. . .

(*dev->Close) (dev);

See also DMdOpen, DMdFdOpen, DMdDev Structure

RefreshRate

Purpose Use RefreshRate to get the refresh rate for a display

mode setting.

Syntax DLong (*RefreshRate) (dev)

RefreshRate | 77

Parameter T ype Name Description

DMdDev dev

Device handle for the DOME device

Return value An integer equal to 100 times the refresh rate in Hz, if

successful. If the display mode is not set to a supported mode, RefreshRate() returns zero.

Description RefreshRate() returns a long integer equal to 100 times

the refresh rate of the display mode setting.

Errors None.

Example This example returns the refresh rate of the display mode.

#include "domeMd.h" DMdDev dev; float refreshRate;

. . .

refreshRate = (*dev->RefreshRate) (dev) / 100.0;

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