opengl-icd - Read

erectboboΛογισμικό & κατασκευή λογ/κού

14 Δεκ 2013 (πριν από 3 χρόνια και 8 μήνες)

114 εμφανίσεις



OpenGL Installable Client Driver

Version 1.101

For Microsoft’s Windows NT 4.0, Windows NT 5.0, Windows 95, and
Windows 98

Reference Guide

2

OpenGL Installable Client Driver







Information in this document is subject to change without notice. Companies,
names, and dat
a used in examples herein are fictitious unless otherwise noted. No
part of this document may be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without the express written
permission of Microsoft Corporati
on.


©
1995, 1996, 1998 Microsoft Corporation. All rights reserved.

Portions
©
1998 Silicon Graphics Inc., All rights reserved.

Microsoft Corporation


OpenGL Installable Client Driver

3




OVERVIEW

................................
................................
................................
.................

5

FEATURES ADDED TO TH
E OPENGL SYSTEM

................................
................

7

CL
IENT DRIVER INTERFAC
E

................................
................................
...............

9

D
RV
C
OPY
C
ONTEXT

................................
................................
................................
......

10

D
RV
C
REATE
C
ONTEXT

................................
................................
................................
..

11

D
RV
C
REATE
L
AYER
C
ONTEXT

................................
................................
.......................

12

D
RV
D
ELETE
C
ONTEXT

................................
................................
................................
..

13

D
RV
D
ESCRIBE
L
AYER
P
LANE

................................
................................
........................

14

D
RV
D
ESCRIBE
P
IXEL
F
ORMAT

................................
................................
.......................

15

D
RV
G
ET
L
AYER
P
ALETTE
E
NTRIES

................................
................................
.................

16

D
RV
G
ET
P
ROC
A
DDRESS

................................
................................
...............................

17

D
RV
R
EALIZE
L
AYER
P
ALETTE

................................
................................
.......................

18

D
RV
R
ELEASE
C
ONTEXT

................................
................................
................................

19

D
RV
S
ET
C
ALLBACK
P
ROCS

................................
................................
............................

20

D
RV
S
ET
C
ONTEXT
................................
................................
................................
.........

21

D
RV
S
ET
L
AYER
P
ALETTE
E
NTRIES

................................
................................
.................

22

D
RV
S
ET
P
IXEL
F
ORMAT

................................
................................
................................
.

23

D
RV
S
HARE
L
ISTS

................................
................................
................................
..........

24

D
RV
S
WAP
B
UFFERS

................................
................................
................................
......

25

D
RV
S
WAP
L
AYER
B
UFFERS

................................
................................
...........................

26

D
RV
V
ALIDATE
V
ERSION

................................
................................
...............................

28

LAYERPLANEDESCRIPTOR

................................
................................
...................

29

DISPLAY DRIVER INTER
FACE

................................
................................
...........

33

D
RV
D
ESCRIBE
P
IXEL
F
ORMAT

................................
................................
.......................

34

D
RV
S
ET
P
IXEL
F
ORMAT

................................
................................
................................
.

35

D
RV
S
WAP
B
UFFERS

................................
................................
................................
......

36

OPENGL ESCAPE INTE
RFACE

................................
................................
............

37

OPENGL_GETINFO

................................
................................
................................
..

38

OPENGL_CMD

................................
................................
................................
..........

39

SERVICE FUNCTIONS

................................
................................
...........................

40

D
RIVER
O
BJECT
S
ERVICES
................................
................................
............................

41

E
NG
C
REATE
D
RIVER
O
BJ

................................
................................
...............................

42

E
NG
D
ELETE
D
RIVER
O
BJ

................................
................................
...............................

43

DRIVEROBJ

................................
................................
................................
...............

44

W
INDOW
O
BJECT
S
ERVICES

................................
................................
.........................

45

E
NG
C
REATE
W
ND

................................
................................
................................
.........

46

WNDOBJ_
B
E
NUM
................................
................................
................................
.......

49

WNDOBJ_
C
E
NUM
S
TART

................................
................................
............................

50

4

OpenGL Installable Client Driver



WNDOBJ_
V
S
ET
C
ONSUMER

................................
................................
........................

52

WNDOBJ

................................
................................
................................
.....................

53

CLIENT DRIVER SETUP
AND INSTALLATION

................................
...............

54

R
EGISTRY

................................
................................
................................
......................

54

S
ETUP

................................
................................
................................
...........................

55

SAMPLE INSTALLABLE C
LIENT DRIVER

................................
.......................

56

D
IRECTORY
S
TRUCTURE

................................
................................
...............................

57

B
UILDING A
D
ISPLAY
D
RIVER WITH
O
PEN
GL

S
UPPORT

................................
................

58

Windows 9x

................................
................................
................................
..............

58

Windows NT

................................
................................
................................
.............

58

ICD

L
IBRARY
O
RGANIZATION

................................
................................
......................

59

Interacting Objects

................................
................................
................................
..

59

Nomenclature

................................
................................
................................
...........

60

Where to
add your code

................................
................................
...........................

60

State validation and function picking

................................
................................
......

61

Miscellaneous concerns

................................
................................
...........................

62

I
NTERACTIONS

................................
................................
................................
..............

63

Normal Interactions

................................
................................
................................
.

63

Exceptional Conditions

................................
................................
............................

65

H
ARDWARE
A
CCELERATION

................................
................................
.........................

67

T
HE ROLE OF
D
IRECT
D
RAW

................................
................................
..........................

71

T
EXTURE
M
ANAGEMENT

................................
................................
..............................

72

Surface Management

................................
................................
...............................

73

Texture format mapping

................................
................................
...........................

74

K
ERNEL
M
ODE
I
SSUES IN
W
INDOWS
NT

4.0

AND
5.0

................................
...................

75


OpenGL Installable Client Driver

5



Overview

The OpenGL installable client driver (ICD) allows independent hardware vendors
(IHV’s) to provide accelerated OpenGL rendering by intercepting OpenGL
functions in a client library (DLL). Acceleration is provided via the combination
of the ICD and extensions to the video display driver. To further illustrate this
arrangement, the basi
c architecture of the OpenGL system is shown in the
following illustration.



When OpenGL renders to a device, it needs to know certain attributes of the
device it is drawing to, such as color depth/format, auxiliary buffers supported,
and so on. This inf
ormation is referred to as the pixel format. There are two
classes of OpenGL pixel formats: generic and device specific.

6

OpenGL Installable Client Driver



Generic pixel formats are supported by a software implementation of OpenGL in
the OpenGL DLL (
opengl32.dll
). This DLL processes the Ope
nGL calls into
Win32 calls, rendering/CAD extension calls, or draws directly into the frame
buffer.

Support for device specific pixel formats is divided between the video display
driver and an ICD. The physical OpenGL API entry points are still provided by

the OpenGL DLL, but are redirected via the ICD interface to the Client Driver.
The ICD communicates with the Video Display Driver via the OpenGL Escape
Module in the Win32 Kernel Component. The level of batching and the nature of
the commands passed betwe
en the client driver and the display driver via the
escapes is determined by the IHV and varies with the device capabilities. An IHV
with hardware that supports high level graphics primitives might choose to do
some of the OpenGL processing up front in the

ICD and send graphics primitive
drawing commands to the display driver. On the other hand, an IHV with
hardware capable of directly supporting OpenGL might choose to send the
OpenGL API calls directly from the client driver to the display driver. The
Open
GL escape support in the Win32 Kernel Component merely provides the
communications framework; the content of the drivers and the structures passed in
to the Escapes are determined by the IHV.

In addition to providing the communications channel, the Win32 K
ernel
Component also provides the display driver with an array of engine services to
help track window information and manage resources.


OpenGL Installable Client Driver

7



Features Added to the OpenGL System

The following features have been added to the OpenGL system in support of the
inst
allable client driver.



Installable Client Driver Library Entry Points:

DrvCreateContext:

Creates a client rendering context for a specified device
context.

DrvDeleteContext:

Deletes a client rendering context for a specified device
context.

DrvSetContext:

Makes the rendering context current for the calling thread.

DrvReleaseContext:

Releases the rendering context from being current for
the calling thread

DrvCopyContext:
Copies selected groups of rendering state from one
OpenGL rendering context to another.

DrvShareLists:

Allows rendering contexts to share a single display
-
list space.

DrvValidateVersion:

Allows the client driver to verify that it is
communicating with the correct version of the display driver.

DrvGetProcAddress:

Returns the client address of
an extension function to
use with the current rendering context.

DrvSetCallbackProcs:

Initializes the OpenGL DLL callback function
addresses in the ICD.

DrvCreateLayerContext:
Creates a new OpenGL rendering context for
drawing to a specified layer plane on

a given device context.

DrvDescribeLayerPlane:
Obtains information about the layer planes of a
given pixel format.

DrvSetLayerPaletteEntries:

Sets the palette entries in a given color
-
index
layer plane for a device context.

DrvGetLayerPaletteEntries:

Retr
ieves the palette entries from a given color
-
index layer plane for a specified device context.

DrvRealizeLayerPalette:

Maps palette entries from a given color
-
index layer
plane into the physical palette or initializes the palette of an RGBA layer
plane.

Dr
vSwapLayerBuffers:
Swaps the front and back buffers in the overlay,
underlay, and main planes of a device context’s window.

DrvDescribePixelFormat:

This entry point allows the client driver to identify
pixel formats that it is capable of accelerating.

DrvS
etPixelFormat:
This entry point informs the client driver that an
accelerated pixel formats is being used for a particular window.

8

OpenGL Installable Client Driver



DrvSwapBuffers:

This entry point instructs the client driver to copy the
contents of the back buffer to the display.




Video D
isplay Driver Entry Points:

DrvDescribePixelFormat:

This entry point allows the video display driver to
identify pixel formats that it is capable of accelerating.

DrvSetPixelFormat:
This entry point informs the video display driver that an
accelerated pixe
l formats is being used for a particular window.

DrvSwapBuffers:

This entry point instructs the video display driver to copy
the contents of the back buffer to the display.




Dedicated OpenGL Escape Function:

The OpenGL Escape function passes
additional inf
ormation to the video display driver, such as the foreground
translation object and the window object.




Window Object Services:

These services allow the video display driver to be
notified of visible region changes for displayed windows.




Driver Object Ser
vices:

These services allow the video display driver to
register objects to be deleted upon thread detachment.


OpenGL Installable Client Driver

9



Client Driver Interface

The OpenGL DLL calls the following entry points of the ICD interface if the
device supports the pixel format requested
by the application. All prototypes and
structure definitions for the client driver interface are located in the header file
include/gldrv.h
. The functions are listed in alphabetic order, and the structure
definition of LAYERPLANEDESCRIPTOR can be found at
the end of this
section.

DrvCopyContext

DrvCreateContext

DrvCreateLayerContext

DrvDeleteContext

DrvDescribeLayerPlane

DrvDescribePixelFormat

DrvGetProcAddress

DrvGetLayerPaletteEntries

DrvRealizeLayerPalette

DrvReleaseContext

DrvSetCallbackProcs

DrvSetCont
ext

DrvSetLayerPaletteEntries

DrvSetPixelFormat

DrvShareLists

DrvSwapBuffers

DrvSwapLayerBuffers

DrvValidateVersion

LAYERPLANEDESCRIPTOR


10

OpenGL Installable Client Driver



DrvCopyContext

BOOL DrvCopyContext(
dhrcSource, dhrcDest, fuMask
)

DHGLRC

dhrcSource;

DHGLRC
dhrcDest;

UINT

fuMask;

DrvCopyContext

copies selected groups of rendering state from one OpenGL
driver’s rendering context to another.

dhrcSource

Specifies the source OpenGL driver rendering context whose state information
is to be copied.

dhrcDest

Specifies the destination Open
GL driver rendering context to which the
information is to be copied.

fuMask

Specifies which groups of
dhrcSource
’s rendering state are to be copied. It
contains a bitwise
-
OR of the same symbolic names that are passed to
glPushAttrib
. You can use GL_ALL_AT
TRIB_BITS to copy the entire
rendering state.

DrvCopyContext

enables the synchronization of rendering state between two
driver rendering contexts. The rendering state between two contexts can only be
copied within the same process, and the rendering contex
ts must be from the same
OpenGL implementation. For example, you can always copy a rendering state
between two rendering contexts of a given pixel format in the same process.

You can copy only the same state information available through
glPushAttrib
.
You
cannot copy some state information, such as pixel pack/unpack state, render
mode state, select state, and feedback state. Opengl32 ensures that
dhrcDest

is not
current to any thread.


OpenGL Installable Client Driver

11



DrvCreateContext

DHGLRC

DrvCreateContext
(
hdc
)

HDC

hdc
;

DrvCreateContext

creates a client rendering context for the device context
specified by
hdc
. The unique identifier returned by
DrvCreateContext

will be
used to identify the created context in subsequent calls to the client driver.

hdc

A valid handle to a device context.

D
rvCreateContext

returns a non
-
zero unique identifier for the rendering context.
If an error occurs,
DrvCreateContext

returns NULL.

12

OpenGL Installable Client Driver



DrvCreateLayerContext

DHGLRC DrvCreateLayerContext
(
hdc, iLayerPlane
)

HDC

hdc
;

INT

iLayerPlane
;

DrvCreateLayerContext

creat
es an OpenGL driver rendering context for
drawing to a layer plane on the given device context.

hdc

Specifies the device context for which the new driver rendering context will be
created.

iLayerPlane

Specifies the layer plane to which the new rendering co
ntext will be bound.
Positive values of
iLayerPlane

identify overlay planes, where 1 is the first
overlay plane over the main plane, 2 is the second overlay plane over the first
overlay plane, and so on. Negative values identify underlay planes, where
-
1 i
s
the first underlay plane under the main plane,
-
2 is the second underlay plane
under the first underlay plane, and so on. The number of overlay and underlay
planes is given in the
bReserved

field of the PIXELFORMATDESCRIPTOR
structure.

DrvCreateLayerCont
ext
returns the handle to an OpenGL driver rendering
context upon success; it returns NULL if it fails.

DrvCreateLayerContext

creates a client rendering context for the device context
specified by
hdc
. The unique identifier returned by
DrvCreateLayerContex
t

will
be used to identify the created context in subsequent calls to the client driver.


OpenGL Installable Client Driver

13



DrvDeleteContext

BOOL

DrvDeleteContext
(
dhglrc
)

DHGLRC

dhglrc
;

DrvDeleteContext

deletes the client rendering context specified by
dhglrc
.

dhglrc


A valid handle to a
client rendering context.

DrvDeleteContext

returns TRUE if the rendering context was deleted, FALSE
otherwise.

14

OpenGL Installable Client Driver



DrvDescribeLayerPlane

BOOL DrvDescribeLayerPlane
(
hdc, iPixelFormat, iLayerPlane, nBytes, plpd
)

HDC

hdc
;

INT

iPixelFormat
;

INT

iLayerPlane
;

UI
NT

nBytes
;

LPLAYERPLANEDESCRIPTOR

plpd
;

DrvDescribeLayerPlane

obtains information about the layer planes of a given
pixel format.

hdc

Specifies the device context of a window whose layer planes are to be
described.

iPixelFormat

Specifies the pixel format
of
iLayerPlane
.

iLayerPlane

Specifies the overlay or underlay plane for which information is to be obtained.
Positive values of
iLayerPlane

identify overlay planes, where 1 is the first
overlay plane over the main plane, 2 is the second overlay plane over
the first
overlay plane, and so on. Negative values identify underlay planes, where
-
1 is
the first underlay plane under the main plane,
-
2 is the second underlay plane
under the first underlay plane, and so on. The number of overlay and underlay
planes is

given in the
bReserved

field of the PIXELFORMATDESCRIPTOR
structure.

nBytes

Specifies the size, in bytes, of the structure pointed to by
plpd
.
DrvDescribeLayerPlane

stores layer
-
plane data in a
LAYERPLANEDESCRIPTOR

structure, and it stores no more than
nB
ytes

of
data. This parameter should be the
sizeof
(LAYERPLANEDESCRIPTOR
).

plpd

Points to a LAYERPLANEDESCRIPTOR structure in which
DrvDescribeLayerPlane

returns the layer plane information. The number of
bytes of data copied to the structure will be stored
in the
nSize

field of this
structure.

DrvDescribeLayerPlane
returns TRUE if it succeeds, and the members of the
structure pointed to by
plpd

are set accordingly. This function returns FALSE if it
fails.

Higher
-
numbered planes overlay lower
-
numbered planes.


OpenGL Installable Client Driver

15



DrvDescribePixelFormat

LONG DrvDescribePixelFormat(
hdc
,
iPixelFormat
,
cjpfd
,
ppfd
)

HDC
hdc
,

LONG


iPixelFormat
;

ULONG

cjpfd
;

PIXELFORMATDESCRIPTOR

*
ppfd
;

DrvDescribePixelFormat

describes the pixel format for a
dhpdev

device by
writing the pixel descrip
tion information to a structure specified by
ppfd
.

hdc

Specifies the device context for which the pixel format is requested.

iPixelFormat

Specifies the index number of the requested pixel format.

cjpfd

Specifies the maximum number of bytes that may be writ
ten into the structure
pointed to by
ppfd
.

ppfd

Points to the PIXELFORMATDESCRIPTOR structure that is to receive the
information describing the pixel format. This function stores the number of
bytes copied to the structure in the structure’s
nSize

member.

If the function succeeds, it returns the maximum pixel format index. It returns zero
if an error occurs, and an error code is logged.

A pixel format corresponds to a pixel configuration supported by the graphics
hardware. The PIXELFORMATDESCRIPTOR structur
e contains information
about a pixel format. PIXELFORMATDESCRIPTOR is defined in
wingdi.h
.

DrvDescribePixelFormat

also fills in the structure pointed to by
ppfd

if it is
successful. If
ppfd

is NULL, this function simply returns the maximum pixel
format in
dex and writes no data to the structure. This may be used by GDI to
obtain a device context’s maximum pixel format index. The pixel formats that a
device supports are identified by positive one
-
based integer indices starting at 1.



This client driver

entry point is supported only for client drivers on Windows 95,
Windows 98 and (in some cases) Windows NT 5.0. The format of the registry
entries on Windows NT 5.0 determines if this entry point is going to be used or
not (see Client Driver Setup and Ins
tallation for details.) When this entry point is
not supported in the client driver, it exists in the display driver.


Note

16

OpenGL Installable Client Driver



DrvGetLayerPaletteEntries

int DrvGetLayerPaletteEntries
(
hdc, iLayerPlane, iStart, cEntries, pcr
)

HDC

hdc
;

INT

iLayerPlane
;

INT

iStar
t
;

INT

cEntries
;

COLORREF

*pcr
;

DrvGetLayerPaletteEntries

retrieves the palette entries from a given color
-
index
layer plane for the given device context.

hdc

Handle to the device context of a window whose layer plane’s palette entries
are to be describe
d.

iLayerPlane

Specifies the overlay or underlay plane for which information is to be obtained.
Positive values of
iLayerPlane

identify overlay planes, where 1 is the first
overlay plane over the main plane, 2 is the second overlay plane over the first
ove
rlay plane, and so on. Negative values identify underlay planes, where
-
1 is
the first underlay plane under the main plane,
-
2 is the second underlay plane
under the first underlay plane, and so on. The number of overlay and underlay
planes is given in the

bReserved

field of the PIXELFORMATDESCRIPTOR
structure.

iStart

Specifies the first palette entry to be retrieved.

cEntries

Specifies the number of palette entries to be retrieved.

pcr

Pointer to an array of COLORREF structures in which RGB color informati
on
will be returned. The array size is
cEntries
.

DrvGetLayerPaletteEntries

returns the number of palette entries that were
retrieved for the specified layer plane of the window upon successful completion.
If the function fails or no pixel format is selecte
d, the return value is 0.

Each color
-
index plane in a window has a palette of size 2
n
, where
n

is the number
of bit planes in the layer plane.


OpenGL Installable Client Driver

17



DrvGetProcAddress

PROC

DrvGetProcAddress

(
lpszProc
)

LPCSTR

lpszProc
;

DrvGetProcAddress

returns the client addre
ss of an extension function to use
with the current rendering context. The extension function addresses are unique
for each pixel format. All rendering contexts of a given pixel format share the
same extension function addresses.

lpszProc

Points to a null
-
terminated string containing the extension function name.

DrvGetProcAddress
returns the client address of the extension function if the
extension is supported by the current rendering context. Otherwise, it returns
NULL
.

OpenGL applications do not have a d
irect link to the ICD.
DrvGetProcAddress

allows applications to call extension functions provided by the driver indirectly
through the returned function addresses. The returned function addresses must be
callable in the client space.

Since extension functi
ons are callable by applications, they must validate the
current rendering context. The list of supported extensions for the current
rendering context must be given in
glGetString
.

18

OpenGL Installable Client Driver



DrvRealizeLayerPalette

int DrvRealizeLayerPalette
(
hdc, iLayerPlane,bRealiz
e
)

HDC

hdc
;

INT

iLayerPlane
;

BOOL

bRealize
;

DrvRealizeLayerPalette

maps palette entries from a given color
-
index layer
plane into the physical palette, or initializes the palette of an RGBA layer plane.

hdc

Handle to the device context of a window whose

layer plane’s palette is to be
realized into the physical palette.

iLayerPlane

Specifies the overlay or underlay plane whose palette information is to be
realized. Positive values of
iLayerPlane

identify overlay planes, where 1 is the
first overlay plane
over the main plane, 2 is the second overlay plane over the
first overlay plane, and so on. Negative values identify underlay planes, where
-
1 is the first underlay plane under the main plane,
-
2 is the second underlay
plane under the first underlay plane,

and so on. The number of overlay and
underlay planes is given in the
bReserved

field of the
PIXELFORMATDESCRIPTOR structure.

bRealize

Indicates whether the palette is to be realized into the physical palette. When
bRealize

is TRUE, the palette entries are

mapped into the physical palette where
available. When
bRealize

is FALSE, the palette entries for the layer plane of the
window are no longer needed and might be realized for use by another foreground
window.

DrvRealizeLayerPalette

returns TRUE upon succe
ss, even if
bRealize

is TRUE
and the physical palette is not available. If the function fails or no pixel format is
selected, the return value is FALSE.

The physical palette for a layer plane is a shared resource among windows with
layer planes. When more
than one window realizes a palette for a given physical
layer plane, only one palette at a time is realized. When you call
DrvRealizeLayerPalette
, the layer palette of a foreground window is always
realized.

When a window’s layer palette is realized, its p
alette entries are always mapped
one
-
to
-
one into the physical palette. Unlike GDI’s logical palettes, there is no
mapping of other windows’ layer palettes to the current physical palette in
DrvRealizeLayerPalette.

DrvRealizeLayerPalette

cannot be used to r
ealize the palette of the main plane
palette.


OpenGL Installable Client Driver

19



DrvReleaseContext

BOOL

DrvReleaseContext
(
dhglrc
)

DHGLRC

dhglrc
;

DrvReleaseContext

releases the rendering context specified by
dhglrc

from being
current for the calling thread. This function returns TRUE upon s
uccess,
otherwise it returns FALSE.

20

OpenGL Installable Client Driver



DrvSetCallbackProcs

void

DrvSetCallbackProcs

(
nProcs, pProcs
)

INT

nProcs
;

PROC

*
pProcs
;

DrvSetCallbackProcs

initializes the OpenGL DLL callback function addresses in
the installable client driver.

nProcs

Specifies the

number of OpenGL DLL callback functions in
pProcs
.

pProcs

Specifies the array containing the OpenGL DLL callback function addresses.

The OpenGL DLL passes callback function addresses to this function when the
driver is first loaded for the process.
DrvSet
CallbackProcs

returns no value.

The callback functions in
pProcs

are given in the following order:

PFN_SETCURRENTVALUE:

typedef void (APIENTRY * PFN_SETCURRENTVALUE)(VOID *pv);

The SETCURRENTVALUE callback function stores a value in the current
thread. Onl
y one value is stored per thread. It provides a fast method to store per
-
thread data. The macro SETCURRENTVALUE(PV) further optimizes its use for
alpha platforms.

PFN_GETCURRENTVALUE:

typedef void * (APIENTRY * PFN_GETCURRENTVALUE)(VOID);

The GETCURRENTVAL
UE callback function returns the value stored in the
current thread by PFN_SETCURRENTVALUE. It provides a fast method to
retrieve per
-
thread data. The macro GETCURRENTVALUE further optimizes its
use for alpha platforms.

PFN_GETDHGLRC:

typedef DHGLRC (APIEN
TRY * PFN_GETDHGLRC)(HGLRC hrc);

The GETDHGLRC callback function returns the driver
-
specific rendering context
handle for an OpenGL rendering context handle. This function returns NULL if
the HGLRC is invalid or if there is no driver
-
specific handle. A dri
ver can use this
callback to translate rendering context handles that are passed directly to the
driver through exported extensions.


OpenGL Installable Client Driver

21



DrvSetContext

PGLCLTPROCTABLE DrvSetContext(
hdc
,
dhglrc
,
pfnSetProcTable
)

HDC

hdc
;

DHGLRC

dhglrc
;

PFN_SETPROCTABLE

pfnS
etProcTable
;

DrvSetContext

makes the rendering context specified by
dhglrc

and the device
context specified by
hdc

current for the calling thread.

hdc

A valid handle to a device context.

dhglrc

A valid handle to a rendering context.

pfnSetProcTable

The add
ress of the function to use to set the OpenGL procedure table if such
action is required after the call to
DrvSetContext
.

DrvSetContext

returns a pointer to the OpenGL procedure table to be used for
the rendering context. This table contains function point
ers for all OpenGL
functions. GLCLTPROCTABLE is defined in the header file
gldrv.h
.

PFN_SETPROCTABLE is defined as follows:

typedef void (APIENTRY * PFN_SETPROCTABLE)



(PGLCLTPROCTABLE pProcTable)


22

OpenGL Installable Client Driver



DrvSetLayerPaletteEntries

int DrvSetLayerPaletteEntries
(
hdc, iLayerPlane, iStart, cEntries, pcr
)

HDC

hdc
;

INT

iLayerPlane
;

INT

iStart
;

INT

cEntries
;

CONST

COLORREF

*pcr
;

DrvSetLayerPaletteEntries

sets the palette entries in a given color
-
index layer
plane for the given device context.

hdc

Handle to the dev
ice context of a window whose layer plane’s palette is to be
set.

iLayerPlane

Specifies the overlay or underlay plane for which information is to be set.
Positive values of
iLayerPlane

identify overlay planes, where 1 is the first
overlay plane over the ma
in plane, 2 is the second overlay plane over the first
overlay plane, and so on. Negative values identify underlay planes, where
-
1 is
the first underlay plane under the main plane,
-
2 is the second underlay plane
under the first underlay plane, and so on.

The number of overlay and underlay
planes is given in the
bReserved

field of the PIXELFORMATDESCRIPTOR
structure.

iStart

Specifies the first palette entry to be set.

cEntries

Specifies the number of palette entries to be set.

pcr

Pointer to an array of CO
LORREF structures that contain RGB color
information. The array size is
cEntries
.

DrvSetLayerPaletteEntries

returns the number of palette entries that were set in
the specified layer plane of the window upon successful completion. If the
function fails or
no pixel format is selected, the return value is 0.

Each color
-
index plane in a window has a palette of size 2
n
, where
n

is the number
of bit planes in the layer plane. You cannot modify the transparent index of a
palette.

Initially, the layer palette cont
ains white colors.

DrvSetLayerPaletteEntries

cannot be used to set the palette entries of the main
plane palette.


OpenGL Installable Client Driver

23



DrvSetPixelFormat

BOOL DrvSetPixelFormat(
hdc
,
iPixelFormat
)

HDC
hdc
;

LONG

iPixelFormat
;

DrvSetPixelFormat

sets the pixel format of a window.

hdc

Specifies a device context associated with the window..

iPixelFormat

Index that specifies the device format to which the pixel format is to be set.
The pixel formats that a device supports are identified by positive one
-
based
integer indices starting
at 1.

DrvSetPixelFormat

returns TRUE if the pixel format is set successfully; it
returns FALSE if an error occurs.

Setting the pixel format more than once can result in complications for the
Window Manager and for multi
-
threaded applications. Consequently,

the pixel
format of a window can be set only once and must remain unchanged.



This client driver entry point is supported only for client drivers on Windows 95,
Windows 98 and (in some cases) Windows NT 5.0. The format of the registry
entries on Wi
ndows NT 5.0 determines if this entry point is going to be used or
not (see Client Driver Setup and Installation for details.) When this entry point is
not supported in the client driver, it exists in the display driver.


Note

24

OpenGL Installable Client Driver



DrvShareLists

BOOL DrvShareLists

(
dhglrc1, dhglrc2
)

DHGLRC

dhglrc1
;

DHGLRC

dhglrc2
;

DrvShareLists

allows rendering contexts to share a single display
-
list space.
Rendering contexts that share a single display
-
list space also share a single texture
object space.

dhglrc1

Specifies the c
lient rendering context with which to share display lists.

dhglrc2

Specifies the client rendering context to share display lists with
dhglrc1
. The
client rendering context
dhglrc2

should not contain any existing display lists
when this function is called.

DrvShareLists

returns
TRUE

if the function succeeds. If display lists exist in
dhglrc2

or an error occurs, it returns
FALSE
.

A newly created client rendering context has its own display
-
list space.
DrvShareLists

allows a client context to share a display
-
l
ist space with other
client contexts. Any number of client contexts can share a single display
-
list
space. Once a client context shares a display
-
list space, it always uses the display
-
list space until it is deleted. A shared display
-
list space is deleted

when the last
client context using it is deleted. All display
-
list indexes and definitions in a
shared display
-
list space are shared.

All client rendering contexts of a given device pixel format must be able to share
display lists. Client rendering contex
ts of different device pixel formats may share
display lists if allowed by the implementation.

If a driver implements display lists on the client side, it must ensure that shared
display list operations are thread safe. It should fail or serialize the call

to modify a
shared display list in a thread while another thread is using it. If the driver
implements display lists on the server side and the display list operations are
serialized by
DrvEscape
, then the operations are guaranteed to be thread safe.

The
version number returned by
glGetString

must be “1.1” or later.


OpenGL Installable Client Driver

25



DrvSwapBuffers

BOOL DrvSwapBuffers
(
hdc
)

HDC
hdc
;

DrvSwapBuffers

instructs the driver to display the contents of the hidden buffer
of the window identified by
hdc
.

hdc

Specifies a device contex
t of the window.

DrvSwapBuffers

can affect the display only if the pixel format for the window
specified by
pwo

is double
-
buffered. The content of the hidden buffer is undefined
after the swap occurs.

This function is required if the driver supports a pixe
l format with double
buffering; that is, the PFD_DOUBLEBUFFER is set in the
dwFlags

field of the
PIXELFORMATDESCRIPTOR.

This function returns TRUE upon success; it returns FALSE upon failure.



If a double
-
buffered pixel format uses split pixels for
the front and back buffers, it
should include the PFD_SWAP_EXCHANGE flag in the pixel format descriptor.
See PIXELFORMATDESCRIPTOR for details.

This client driver entry point is supported only for client drivers on Windows 95,
Windows 98 and (in some case
s) Windows NT 5.0. The format of the registry
entries on Windows NT 5.0 determines if this entry point is going to be used or
not (see Client Driver Setup and Installation for details.) When this entry point is
not supported in the client driver, it exis
ts in the display driver.



Notes

26

OpenGL Installable Client Driver



DrvSwapLayerBuffers

BOOL

DrvSwapLayerBuffers
(
hdc, fuPlanes
)

HDC

hdc
;

UINT

fuPlanes
;

DrvSwapLayerBuffers

swaps the front and back buffers in the overlay, underlay,
and main planes of the window referenced by a specified device

context.

hdc

Specifies the device context of the window whose plane buffers are to be
swapped.

fuPlanes

Specifies the overlay, underlay, and main planes whose front and back buffers
are to be swapped. The
bReserved

field of the
PIXELFORMATDESCRIPTOR

struc
ture specifies the number of overlay and
underlay planes. This parameter is a bitwise combination of the following
values.

Value

Meaning

WGL_SWAP_MAIN_PLAN
E

Swaps the front and back buffers of the
main plane.l

WGL_SWAP_OVERLAY
i

Swaps the front and back b
uffers of overlay
plane
i
, where
i
is an integer between 1 and
15. WGL_SWAP_OVERLAY1 identifies
the first overlay over the main plane,
WGL_SWAP_OVERLAY2 identifies the
second overlay over the first plane and so
on.

WGL_SWAP_UNDERLAY
i

Swaps the front and b
ack buffers of
underlay plane
i
, where
i
is an integer
between 1 and 15.
WGL_SWAP_UNDERLAY1 identifies the
first underlay under the main plane,
WGL_SWAP_UNDERLAY2 identifies the
second underlay under the first plane and
so on.


DrvSwapLayerBuffers

returns

TRUE if it succeeds; otherwise, it returns
FALSE.

When a layer plane doesn’t include a back buffer, calling
DrvSwapLayerBuffers
should have no effect on that layer plane. The state of the back buffer’s content
after swapping should be indicated by returni
ng the appropriate flag in the
LAYERPLANEDESCRIPTOR structure of the corresponding layer plane, or in
the PIXELFORMATDESCRIPTOR of the main plane.
DrvSwapLayerBuffers
swaps the front and back buffers in the specified layer planes simultaneously.


OpenGL Installable Client Driver

27



Some devic
es don’t support swapping layer planes individually; they swap all
layer planes as a group. The PFD_SWAP_LAYER_BUFFERS flag of the
PIXELFORMATDESCRIPTOR can be used to indicate that a device can swap
individual layer planes and that
DrvSwapLayerBuffers

can

be called.

28

OpenGL Installable Client Driver



DrvValidateVersion

BOOL

DrvValidateVersion
(
ulVersion
)

ULONG

ulVersion
;

DrvValidateVersion

gives the client driver an opportunity to verify that it is
communicating with the correct version of the display driver. The OpenGL Client
DLL obtains

an IHV
-
defined version number from the display driver via the
OPENGL_GETINFO escape (please refer to the OpenGL Escape Interface
section of this document). This number will be passed to
DrvValidateVersion

as
ulVersion
. If the client driver recognizes the

version number as one it supports, it
must return TRUE; otherwise, it should return FALSE.


OpenGL Installable Client Driver

29



LAYERPLANEDESCRIPTOR

typedef struct tagLAYERPLANEDESCRIPTOR {


WORD


nsize;


WORD


nversion;


DWORD


dwFlags;


BYTE



iPixelType;


BYTE



cColorBits;


BYTE



cRedB
its;


BYTE



cRedShift;


BYTE



cGreenBits;


BYTE



cGreenShift;


BYTE



cBlueBits;


BYTE



cBlueShift;


BYTE



cAlphaBits;


BYTE



cAlphaShift;


BYTE



cAccumBits;


BYTE



cAccumRedBits;


BYTE



cAccumGreenBits;


BYTE



cAccumBlueBits;


BYTE



cAccumAlpha
Bits;


BYTE



cDepthBits;


BYTE



cStencilBits;


BYTE



cAuxBuffers;


BYTE



iLayerPlane;


BYTE



bReserved;


COLORREF

cTransparent;

} LAYERPLANEDESCRIPTOR;

The
LAYERPLANEDESCRIPTOR

structure describes the pixel format of a
drawing surface.

nSize

Specifies

the size of this data structure. Set this value to
sizeof
(LAYERPLANEDESCRIPTOR).

nVersion

Specifies the version of this data structure. Set this value to 1.

dwFlags

A set of bit flags that specify properties of the layer plane. The properties are
generall
y not mutually exclusive; that is, you can set any combination of bit
flags with the exceptions noted. The following bit flag constants are defined.

30

OpenGL Installable Client Driver



Value

Meaning

LPD_SUPPORT_OPENGL

The layer plane supports OpenGL drawing.

LPD_SUPPORT_GDI

The layer plane

supports GDI drawing. The
current implementation of OpenGL does not
support this flag.

LPD_DOUBLEBUFFER

The layer plane is double
-
buffered. A layer
plane can be double
-
buffered even when the
main plane is single
-
buffered and vice versa.

LPD_STEREO

The l
ayer plane is stereoscopic. A layer
plane can be stereoscopic even when the
main plane is monoscopic and vice versa.

LPD_SWAP_EXCHANGE

In a double
-
buffered layer plane, swapping
the color buffer exchanges the front buffer
and the back buffer contents. The

back
buffer then contains the contents of the front
buffer before the swap. This flag is a hint
only and does not have to be supported by a
driver..

LPD_SWAP_COPY

In a double
-
buffered layer plane, swapping
the color buffer copies the back buffer
contents

to the front buffer. The swap does
not affect the back buffer content. This flag
is a hint only and might not be provided by a
driver.

LPD_TRANSPARENT

The
crTransparent

field of this structure
contains a transparent color or index value
that enables unde
rlying layers to show
through this layer. All layer planes, except
the lowest
-
numbered underlay layer, have a
transparent color or index.

LPD_SHARE_DEPTH

The layer plane shares the depth buffer with
the main plane.

LPD_SHARE_STENCIL

The layer plane share
s the stencil buffer with
the main plane.

LPD_SHARE_ACCUM

The layer plane shares the accumulation
buffer with the main plane.


iPixelType

Specifies the type of pixel data. The following types are defined.

Value

Meaning

LPD_TYPE_RGBA

RGBA pixels. Each pi
xel has four
components: red, green, blue, and alpha.

LPD_TYPE_COLORINDEX

Color
-
index pixels. Each pixel uses a color
-
index value.



OpenGL Installable Client Driver

31



cColorBits

Specifies the number of color bitplanes in each color buffer. For RGBA pixel
types, it is the size of the color

buffer, excluding the alpha bitplanes. For color
-
index pixels, it is the size of the color
-
index buffer.

cRedBits

Specifies the number of red bitplanes in each RGBA color buffer.

cRedShift

Specifies the shift count for red bitplanes in each RGBA color buf
fer.

cGreenBits

Specifies the number of green bitplanes in each RGBA color buffer.

cGreenShift

Specifies the shift count for green bitplanes in each RGBA color buffer.

cBlueBits

Specifies the number of blue bitplanes in each RGBA color buffer.

cBlueShift

S
pecifies the shift count for blue bitplanes in each RGBA color buffer.

cAlphaBits

Specifies the number of alpha bitplanes in each RGBA color buffer.

cAlphaShift

Specifies the shift count for alpha bitplanes in each RGBA color buffer.

cAccumBits

Specifies t
he total number of bitplanes in the accumulation buffer.

cAccumRedBits

Specifies the number of red bitplanes in the accumulation buffer.

cAccumGreenBits

Specifies the number of green bitplanes in the accumulation buffer.

cAccumBlueBits

Specifies the number

of blue bitplanes in the accumulation buffer.

cAccumAlphaBits

Specifies the number of alpha bitplanes in the accumulation buffer.

cDepthBits

Specifies the depth of the depth buffer.

cStencilBits

Specifies the depth of the stencil buffer.

cAuxBuffers

Speci
fies the number of auxiliary buffers. Auxiliary buffers are not supported.

iLayerType

Specifies the layer plane number. Positive values identify overlay planes,
where 1 is the first overlay plane over the main plane, 2 is the second overlay
plane over the
first overlay plane, and so on. Negative values identify underlay
32

OpenGL Installable Client Driver



planes, where
-
1 is the first underlay plane under the main plane,
-
2 is the
second underlay plane under the first underlay plane, and so on. The number of
overlay and underlay planes is giv
en in the
bReserved

field of the
PIXELFORMATDESCRIPTOR structure.

bReserved

Not used. This field must be set to zero.

crTransparent

When the LPD_TRANSPARENT flag is set, specifies the transparent color or
index value. Typically, this value is 0.


OpenGL Installable Client Driver

33



Display
Driver Interface

Prototypes and structure definitions for these additional display driver entry points
are located in header files
winddi.h

of the Windows NT DDK. Note that these
entry points only exist on Windows NT 4.0 and, in some cases, Windows NT 5.0
.
The format of the registry entries on Windows NT 5.0 determines if this entry
point is going to be used or not (see Client Driver Setup and Installation for
details.) When these entry points are not supported in the display driver, they
exist in the cl
ient driver.

DrvDescribePixelFormat

DrvSetPixelFormat

DrvSwapBuffers


34

OpenGL Installable Client Driver



DrvDescribePixelFormat

LONG DrvDescribePixelFormat(
dhpdev
,
iPixelFormat
,
cjpfd
,
ppfd
)

DHPDEV

dhpdev
;

LONG


iPixelFormat
;

ULONG

cjpfd
;

PIXELFORMATDESCRIPTOR

*
ppfd
;

DrvDescribePixelFor
mat

describes the pixel format for a
dhpdev

device by
writing the pixel description information to a structure specified by
ppfd
.

dhpdev

Specifies the device for which the pixel format is requested.

iPixelFormat

Specifies the index number of the requested
pixel format.

cjpfd

Specifies the maximum number of bytes that may be written into the structure
pointed to by
ppfd
.

ppfd

Points to the PIXELFORMATDESCRIPTOR structure that is to receive the
information describing the pixel format. This function stores the

number of
bytes copied to the structure in the structure’s
nSize

member.

If the function succeeds, it returns the maximum pixel format index. It returns zero
if an error occurs, and an error code is logged.

A pixel format corresponds to a pixel configurat
ion supported by the graphics
hardware. The PIXELFORMATDESCRIPTOR structure contains information
about a pixel format. PIXELFORMATDESCRIPTOR is defined in
wingdi.h
.

DrvDescribePixelFormat

also fills in the structure pointed to by
ppfd

if it is
successful.

If
ppfd

is NULL, this function simply returns the maximum pixel
format index and writes no data to the structure. This may be used by GDI to
obtain a device context’s maximum pixel format index. The pixel formats that a
device supports are identified by p
ositive one
-
based integer indices starting at 1.



This display driver entry point is only supported only for display drivers on
Windows NT 4.0 and (in some cases) Windows NT 5.0. The format of the registry
entries on Windows NT 5.0 determines if this

entry point is going to be used or
not (see Client Driver Setup and Installation for details.) When this entry point is
not supported in the display driver, it exists in the client driver.


Note


OpenGL Installable Client Driver

35



DrvSetPixelFormat

BOOL DrvSetPixelFormat(
pso
,
iPixelFormat
,
hwn
d
)

SURFOBJ

*
pso
;

LONG

iPixelFormat
;

HWND

hwnd
;

DrvSetPixelFormat

sets the pixel format of a window.

pso

Points to the surface (SURFOBJ) that the window is associated with.

iPixelFormat

Index that specifies the device format to which the pixel format is
to be set.
The pixel formats that a device supports are identified by positive one
-
based
integer indices starting at 1.

hwnd

Identifies the window whose pixel format is to be set.

The display driver may call the graphics engine to create a window object an
d
register a callback routine to be invoked when the window region changes.
Refer also to “Window Object Services” later in this document.

DrvSetPixelFormat

returns TRUE if the pixel format is set successfully; it
returns FALSE if an error occurs.

Setting
the pixel format more than once can result in complications for the
Window Manager and for multi
-
threaded applications. Consequently, the pixel
format of a window can be set only once and must remain unchanged.



Refer also to the section on Window Object Services.

This display driver e
ntry point is only supported only for display drivers on
Windows NT 4.0 and (in some cases) Windows NT 5.0. The format of the registry
entries on Windows NT 5.0 determines if this entry point is going to be used or
not (see Client Driver Setup and Installa
tion for details.) When this entry point is
not supported in the display driver, it exists in the client driver.


Notes

36

OpenGL Installable Client Driver



DrvSwapBuffers

BOOL DrvSwapBuffers
(
pso
,
pwo
)

SURFOBJ

*
pso
;

WNDOBJ

*
pwo
;

DrvSwapBuffers

instructs the driver to display the contents of the

hidden buffer
of the window identified by
pwo

on the surface specified by
pso
.

pso

Points to the target surface that will be modified.

pwo

Points to the window object that defines the region on the target surface with
which the back buffer will be swapped
.

DrvSwapBuffers

can affect the display only if the pixel format for the window
specified by
pwo

is double
-
buffered. The content of the hidden buffer is undefined
after the swap occurs.

This function is required if the driver supports a pixel format with d
ouble
buffering; that is, the PFD_DOUBLEBUFFER is set in the
dwFlags

field of the
PIXELFORMATDESCRIPTOR.

This function returns TRUE upon success; it returns FALSE upon failure.



If a double
-
buffered pixel format uses split pixels for the front and b
ack buffers, it
should include the PFD_SWAP_EXCHANGE flag in the pixel format descriptor.
See PIXELFORMATDESCRIPTOR for details.

This display driver entry point is only supported only for display drivers on
Windows NT 4.0 and (in some cases) Windows NT 5.0
. The format of the registry
entries on Windows NT 5.0 determines if this entry point is going to be used or
not (see Client Driver Setup and Installation for details.) When this entry point is
not supported in the display driver, it exists in the client
driver.



Notes


OpenGL Installable Client Driver

37



OpenGL Escape Interface

The OpenGL installable client driver uses the Win32 API to access non
-
drawing
OpenGL functionality implemented as extended functions (or extensions). These
extensions must be implemented within the video display driver th
at supports an
ICD. Access to the extended functionality is gained through
ExtEscape
; this
function is described in the “Win32 Programmer’s Reference”.

The extensions implemented by the driver,
OPENGL_GETINFO

and
OPENGL_CMD,

are defined by Microsoft and mu
st be supported by all video
display drivers that support an OpenGL installable client library.

OPENGL_GETINFO

OPENGL_CMD



OpenGL extension numbers are defined in header file
winddi.h
. Structure
definitions are contained in header file
gldrv.h
.


Note

38

OpenGL Installable Client Driver



OPE
NGL_GETINFO

OPENGL_GETINFO

is called by the OpenGL DLL to retrieve information from
the video display driver. The return value is TRUE if the video display driver
supports an OpenGL installable client driver; FALSE otherwise.

The first DWORD of the
ExtEsca
pe

input buffer specifies the extension by its
number and is defined as:

ULONG

ulSubEsc

At present, the value of
ulSubEsc

is
OPENGL_GETINFO_DRVNAME. This function
retrieves the name and version of the video
display driver.


The remainder of the input buff
er is unused for this extended function.

The format and content of the
ExtEscape

output buffer will be:

ULONG

ulVersion

This field must be equal to 2. It allows GDI to
identify a display driver that supports the non
-
IHV specific portions of the interface d
escribed in
this document.

Windows NT versions 3.51 and earlier reported 1
for this version number. Such drivers are no
longer supported.

ULONG

ulDriverVersion

This field specifies the IHV
-
specific version
number of the video display driver. It is used t
o
verify that the video display driver matches the
OpenGL ICD.

WCHAR

awch
[
MAX_PATH+1
]

This field contains a NULL
-
terminated string
specifying the name of the video display driver. It
is used by the OpenGL DLL to find the name of
the corresponding OpenGL I
CD in the registry.
The maximum length of this string is
MAX_PATH characters.



OpenGL Installable Client Driver

39



OPENGL_CMD

OPENGL_CMD

is called by the OpenGL installable client driver to process
OpenGL functionality. The first four DWORDS of the
ExtEscape

input buffer are
defined as fol
lows:

ULONG

ulSubEsc

This value is IHV
-
specific.

FLONG

fl

Specifies flags indicating the values of the next two
DWORDS. Possible values are combinations of the
following bitmasks:

OGLCMD_NEEDWNDOBJ
-

Indicates that the
WNDOBJ field should be filled in by
GDI.

OGLCMD_NEEDXLATEOBJ
-

Indicates that the
XLATEOBJ field should be filled in by GDI

WNDOBJ

*
pwo

Points to a window object filled in by the Win32 Kernel
Component if the OGLCMD_NEEDWNDOBJ flag is
set in
fl
.

XLATEOBJ

*
pxlo

Points to a translation objec
t filled in by the Win32
Kernel Component if the
OGLCMD_NEEDXLATEOBJ flag is set in
fl
.


The remainder of the input buffer is IHV
-
specific.

The contents of the output buffer and the return value are IHV
-
specific.

40

OpenGL Installable Client Driver



Service Functions

The video display drive
r is provided with the following additional services. All
prototypes and structure definitions for the new services are located in
winddi.h
.

These services are only available on Windows NT operating systems.



Driver Object

Services
: This feature allows the video display driver to
register resources that should be deleted upon thread detachment.



Window Object Services
: This feature allows the video display driver to
respond to changes in wi
ndow regions.


OpenGL Installable Client Driver

41



Driver Object Services

The driver object services consist of two functions:
EngCreateDriverObj

and
EngDeleteDriverObj
. These two functions are provided to help the display driver
manage per process resources.
EngCreateDriverObj

allows the di
splay driver to
register a resource with GDI and to supply the address of the deletion function for
that object. The returned object is associated with the current process. When a
process terminates, GDI will call the deletion function for all objects asso
ciated
with that process that have not been released by a prior call to
EngDeleteDriverObj
.
EngDeleteDriverObj

is used to delete the object when the
driver explicitly releases the resource (that is, deletion not initiated by process
termination).

For examp
le, the video display driver could provide the following three functions
to allocate and deallocate rendering contexts:

Function Name

Operations Performed


IHVCreateRC

Called in response to
wglCreateContext
.


Allocates the necessary resources for the r
endering
context.


Calls
EngCreateDriverObj
, passing it a unique
identifier for the rendering context, and the address of
the function
IHVDeleteRCResources.

IHVDeleteRC

Called in response to
wglDeleteContext
.


Calls
EngDeleteDriverObj
.


Calls
IHVDelete
RCResources

to free the resources.

IHVDeleteRCResources

Called from
IHVDeleteRC

to free the resources
allocated by
IHVCreateRC
.


If an application does not call
wglDeleteContext

to delete its rendering context,
then, when the application terminates, GDI

will call
IHVDeleteRCResources
,
passing it the unique identifier given to
EngCreateDriverObj

by
IHVCreateRC
.

It is important that
IHVDeleteRC

call
EngDeleteDriverObj

so that GDI will not
attempt to free the resource again upon application termination.

Eng
CreateDriverObj

EngDeleteDriverObj

DRIVEROBJ

42

OpenGL Installable Client Driver



EngCreateDriverObj

HDRVOBJ EngCreateDriverObj(
pvObj
,
pfnFreeObjProc, hdev
)

PVOID

pvObj
;

FREEOBJPROC

pfnFreeObjProc
;

HDEV

hdev
;

EngCreateDriverObj

creates a DRIVEROBJ structure that is used to track a
driver
-
ma
naged resource that must be released when the current client process
terminates.

pvObj

Points to the driver resource that will be tracked by the DRIVEROBJ. The
resource is associated with the current client process.

pFreeObjProc

Points to a driver
-
supplied

callback function that frees the resource pointed to
by
pvObj
. The callback function should be defined as follows, where
pDriverObj

points to the DRIVEROBJ structure.

BOOL CALLBACK DrvobjFreeObjProc(DRIVEROBJ *pDriverObj);


hdev

The GDI handle of the phys
ical device associated with the object.

The return value is a handle that identifies the newly
-
created DRIVEROBJ
structure if the function is successful. Otherwise, it is zero.

Unless the driver explicitly deletes the DRIVEROBJ by calling
EngDeleteDriverOb
j
, when the process that created the DRIVEROBJ
terminates, the engine frees the resource by calling the function pointed to by the
pFreeObjProc

parameter.



OpenGL Installable Client Driver

43



EngDeleteDriverObj

BOOL EngDeleteDriverObj(
hdo, bCallBack, bLocked
)

HDRVOBJ

hdo
;

IN BOOL

bCallBack

IN BOOL

bLocked

EngDeleteDriverObj

deletes the GDI
-
managed object (frees the handle) used for
tracking a driver
-
managed resource.

hdo

Identifies the engine
-
managed object that is to be deleted. This handle was
obtained from
EngCreateDriverObj
.

bCallBack

Specifies whether or not the free callback should be called. If TRUE, GDI will
invoke the free callback before removing the DRIVEROBJ from the handle
manager. If the callback function returns failure,
EngDeleteDriverObj

will
fail.

bLocked

Specifies whether

the object was locked by the driver (through
EngLockDriverObj
) before
EngDeleteDriverObj

was called.


The return value is TRUE if the function is successful; it is FALSE if the handle
has not been freed. If the driver
-
supplied free callback function retur
ns FALSE,
then
EngDeleteDriverObj

will fail and the handle won’t be freed. This could
happen if the cleanup callback needed to lock another DRIVEROBJ, in order to
free the current DRIVEROBJ, and failed because the other DRIVEROBJ was in
use by another thre
ad.

Once the object is deleted, the associated driver resource is no longer tracked by
GDI and the function pointed to by the
pFreeObjProc

parameter of
EngCreateDriverObj

will not be called upon process termination. It is the
responsibility of the driver t
o ensure that the resource is freed.

Most drivers should be consistent in how objects are cleaned up at termination
time. Consequently, they will pass TRUE for
bCallback

indicating to GDI that it
should call the driver’s cleanup function to free this drive
r resource. Passing
FALSE prevents GDI from calling the driver’s cleanup function.

44

OpenGL Installable Client Driver



DRIVEROBJ

typedef struct _DRIVEROBJ {


PVOID




pvObj;


FREEOBJPROC

pFreeProc;


HDEV




hdev;

} DRIVEROBJ;

The DRIVEROBJ structure is used to track a resource allocated by
a driver that
wants to use GDI services. A DRIVEROBJ allows a display driver to request the
GDI service in managing per
-
process resources. By creating a DRIVEROBJ, a
display driver can insure that resources will be released when an application
terminates.

pvObj

Points to the driver resource that will be tracked by the DRIVEROBJ. The
resource is associated with the current client process.

pFreeProc

Points to a driver
-
supplied callback function that frees the resource pointed to
by
pvObj
.

hdev

The GDI handle
of the physical device associated with the object.

Some drivers, in their Escape support, allocate resources on behalf of applications.
In such cases, the DRIVEROBJ structure provides a means for the application to
notify the driver when it terminates. GDI

will call the driver’s cleanup function for
each DRIVEROBJ that was allocated in an application’s context and not deleted
before the application terminated.

This structure provides a locking mechanism for exclusive access to the associated
resource.


OpenGL Installable Client Driver

45



Wind
ow Object Services

A WNDOBJ is a driver
-
level window object that contains information about the
position, size, and the visible client region of a window. By creating a WNDOBJ
corresponding to an application's window, the driver can track the changes in th
at
window.

EngCreateWnd

WNDOBJ_bEnum

WNDOBJ_cEnumStart

WNDOBJ_vSetConsumer

WNDOBJ

46

OpenGL Installable Client Driver



EngCreateWnd

WNDOBJ *EngCreateWnd(
pso
,
hwnd
,
pfn
,
fl
,
iPixelFormat
)

SURFOBJ

*
pso
;

HWND

hwnd
;

WNDOBJCHANGEPROC

pfn
;

FLONG

fl
;

int

iPixelFormat
;

EngCreateWnd

creates a w
indow object for a window referenced by
hwnd
. Since
creating a window object involves locking special window resources, this function
should be called only in the context of the WNDOBJ_SETUP escape in
DrvEscape
. It was previously possible to call this in
D
rvSetPixelFormat
,
because GDI was invoking
DrvSetPixelFormat

as part of a Win32
SetPixelFormat

call and held the necessary locks. However, with the change in
pixel format management, the display driver’s
DrvSetPixelFormat

will never be
called by the system

itself. So, it is up to the driver to ensure that
EngCreateWnd

is called only on a path reached by the WNDOBJ_SETUP escape.

This function supports window tracking by multiple drivers. Each driver is
identified by a unique
pfn

function pointer. For example
, a live video driver can
track changes to live video windows while an OpenGL driver is tracking changes
to OpenGL windows.

GDI will call the
pfn

function with the most recent window state if a new
WNDOBJ is created in
DrvEscape
. GDI will also notify the
p
fn

function when a
window referenced by a WNDOBJ is destroyed.

pso

Identifies the display surface.

hwnd

A handle to an application created window obtained from
CreateWindow

or
an equivalent function.

pfn

Points to a driver defined callback routine that GDI

calls for changes to the
window in question. In the context of this routine, the WNDOBJ states will
stay unchanged. The callback function should be defined as follows:


VOID CALLBACK WndobjChangeProc(WNDOBJ *pwo, FLONG
fl);


where:

pwo

points to the windo
w object that is currently changing and contains the
new size and position of the window (
pwo

is NULL if
fl

is
WOC_CHANGED);

fl

can be one of the values listed in the following table.


OpenGL Installable Client Driver

47



Flag

Meaning


WOC_RGN_CLIENT_DELTA

The window object contains a delta

client
region. The delta region is valid for this call
only.

WOC_RGN_CLIENT

The window object contains a new visible
client region.

WOC_RGN_SURFACE_DELTA

The window object contains a delta surface
region. The pvConsumer field of the
WNDOBJ contains 0. T
he delta region is valid

for this call only.

WOC_RGN_SURFACE

The window object refers to a surface region
created by GDI. The pvConsumer field of the
WNDOBJ contains 0.

WOC_CHANGED

Indicates that all WNDOBJ callbacks have
been made for the current deskto
p update.
GDI always notifies the driver at the end of a
desktop update. Note that
pwo

is NULL here.

WOC_DELETE

The window object is deleted as a result of the
deletion of the window.



fl

Specifies the type of changes to track. The bits may be one or
more of the
following and it must be the same for all WNDOBJ requests by this driver.

Flag

Meaning


WO_RGN_CLIENT_DELTA

GDI notifies the driver when the window's visible
client region changes. The region that is enumerated in
the callback function is a
non
-
empty delta area that is
in the new region but not in the old region. For
example, GDI updates the driver with a new delta
region to the callback routine as follows:


WndobjChangeProc(pwo,WOC_RGN_CLIENT_DELTA)


The delta region is valid during the call
back only

WO_RGN_CLIENT

GDI notifies the driver when the window's visible
client region changes. The region that is enumerated in
the callback function is the new visible client area of
the window.

48

OpenGL Installable Client Driver




WO_RGN_SURFACE_DELTA

GDI notifies the driver when the

surface region
changes. The region that is enumerated in the callback
function is a non empty delta area that is in the new
surface region but not in the old surface region.

The delta surface region is valid during the callback
only.

WO_RGN_SURFACE

GDI n
otifies the driver when the surface region
changes. The surface region is the display surface area
excluding all visible client region of the windows
being tracked by the driver

WO_RGN_UPDATE_ALL

GDI notifies the driver for all windows it tracks when
any
of its window's visible client region changes. This
flag must be used in conjunction with the
WO_RGN_CLIENT flag.



iPixelFormat

Specifies the pixel format associated with the window object. The pixel format

of a window object is fixed. This may be zero

if there is no associated pixel
format.

If
EngCreateWnd

is successful, the return value is a pointer to a WNDOBJ. The
return value is
-
1 if the same
hwnd

is already being tracked by this driver function;
otherwise it is 0.


OpenGL Installable Client Driver

49



WNDOBJ_bEnum

BOOL WNDOBJ_bEnum
(
pwo, cj, pul
)

WNDOBJ

*
pwo
;

ULONG

cj
;

ULONG

*
pul
;

The
WNDOBJ_bEnum

callback function gets a batch of rectangles from the
visible region of a window. The order of enumeration is determined by the call to
WNDOBJ_cEnumStart
.

pwo

Points to a WNDOBJ structure

created by calling
EngCreateWnd
.

cj

Size of the buffer in bytes. GDI will not write beyond this limit.

pul

Pointer to the buffer where the data is to be returned. The following structure is
written, where
c

is a count of the rectangles returned and
arcl[]

is an array of
rectangles.


typedef struct _ENUMRECTS


{



ULONG c;



RECTL arcl[1];


} ENUMRECTS;


WNDOBJ_bEnum

returns TRUE if there is more data to be enumerated and the
driver should repeat the call. It returns FALSE if the enumeration is complete.
No
error code is logged.

The loop structure for calling this routine is as follows. The count of objects
written to the buffer is put into the buffer itself.

do

{


bMore = WNDOBJ_bEnum(pwo,sizeof(buffer),&buffer.c);


for (i=0; i<buffer.c; i++)


{ /* Proces
s the data */ }

} while (bMore);


WNDOBJ_bEnum

should be called only in the context of the driver callback
routine supplied to GDI in the
EngCreateWnd

function or the DDI functions
where a WNDOBJ is given.

50

OpenGL Installable Client Driver



WNDOBJ_cEnumStart

ULONG WNDOBJ_cEnumStart(
pwo, iT
ype, iDirection, cLimit
)

WNDOBJ *

pwo
;

ULONG

iType
;

ULONG

iDirection
;

ULONG

cLimit
;

WNDOBJ_cEnumStart

is a callback function that sets parameters for
enumeration of the rectangles in the visible region of a window.

pwo

Points to a WNDOBJ structure crea
ted by calling
EngCreateWnd
.

iType

Determines the type of data structures to be returned by
WNDOBJ_bEnum
.
This parameter must be set to CT_RECTANGLES, indicating that the region
is to be enumerated as a list of rectangles.

iDirection

Determines the order i
n which the rectangles are returned. This order can be
essential when an overlapping
DrvBitBlt

is being performed to and from the
same surface. If the order is not relevant to the device driver then CD_ANY
should be specified. This allows GDI to optimize i
ts enumeration for complex
regions.
iDirection

must be one of the following values:


Value

Meaning


CD_RIGHTDOWN

Left to right, top to bottom.

CD_LEFTDOWN

Right to left, top to bottom.

CD_RIGHTUP

Left to right, bottom to top.

CD_LEFTUP

Right to left,

bottom to top.

CD_LEFTWARDS

Left to right, vertical direction is not defined.

CD_UPWARDS

Bottom to top, horizontal direction is not defined.

CD_ANY

Any order convenient for GDI.


cLimit

An indication of how many objects the driver is interested in cac
hing. This is
only used to decide when to stop counting rectangles when GDI is computing
the return value for this function. (If the region is complex, it can take a long
time to compute just how complex it is.) If
cLimit

is zero, no counting is done.


WND
OBJ_cEnumStart

returns a count of how many objects would be
enumerated, if this number does not exceed
cLimit
. If the count exceeds
cLimit

then 0xFFFFFFFF is returned. No error code is logged.


OpenGL Installable Client Driver

51



WNDOBJ_cEnumStart

should be called only in the context of the d
river
callback routine supplied to GDI in the
EngCreateWnd

function, or the DDI
functions where a WNDOBJ is given.

Enumeration can be restarted by calling this routine again.

52

OpenGL Installable Client Driver



WNDOBJ_vSetConsumer

VOID WNDOBJ_vSetConsumer(
pwo, pvConsumer
)

WNDOBJ

*
pwo
;

PVO
ID

pvConsumer
;

The
WNDOBJ_vSetConsumer

callback function sets a driver defined value in
the
pvConsumer

field in the given
WNDOBJ
.

pwo

Points to a WNDOBJ structure created by calling
EngCreateWnd
.

pvConsumer

A driver
-
defined value for identifying this part
icular WNDOBJ. It overrides
the previous value stored in the WNDOBJ.

WNDOBJ_vSetConsumer

should be called only in the context of the driver
callback routine supplied to GDI in the
EngCreateWnd

function or the DDI
functions where a WNDOBJ is given. It can a
lso be called in the context of
DrvSetPixelFormat

function or the
WNDOBJ_SETUP

escape in
DrvEscape

function after a new WNDOBJ is created.


OpenGL Installable Client Driver

53



WNDOBJ

typedef struct _WINDOBJ {


CLIPOBJ


coClient;


PVOID


pvConsumer;


RECTL


rclClient;

} WNDOBJ;

The WNDOBJ str
ucture allows the driver to keep track of the position, size, and
visible client region changes of a window. The visible client region may be