source: trunk/src/ddraw/dive.h

Last change on this file was 211, checked in by hugh, 26 years ago

Include for DX6 verion of ddraw
File size: 17.7 KB
RevLine 
[211]1/***************************************************************************\
2*
3* Module Name: DIVE.H
4*
5* OS/2 2.1 Multimedia Extensions Display Engine API data structures
6*
7* Copyright (c) International Business Machines Corporation 1993, 1994
8* All Rights Reserved
9*
10*
11\****************************************************************************/
12#ifdef __cplusplus
13 extern "C" {
14#endif
15
16#ifndef _DIVE_H_
17#define _DIVE_H_
18
19#define MAX_DIVE_INSTANCES 64
20
21#define FOURCC ULONG
22#define HDIVE ULONG
23
24#define DIVE_SUCCESS 0x00000000
25#define DIVE_ERR_INVALID_INSTANCE 0x00001000
26#define DIVE_ERR_SOURCE_FORMAT 0x00001001
27#define DIVE_ERR_DESTINATION_FORMAT 0x00001002
28#define DIVE_ERR_BLITTER_NOT_SETUP 0x00001003
29#define DIVE_ERR_INSUFFICIENT_LENGTH 0x00001004
30#define DIVE_ERR_TOO_MANY_INSTANCES 0x00001005
31#define DIVE_ERR_NO_DIRECT_ACCESS 0x00001006
32#define DIVE_ERR_NOT_BANK_SWITCHED 0x00001007
33#define DIVE_ERR_INVALID_BANK_NUMBER 0x00001008
34#define DIVE_ERR_FB_NOT_ACQUIRED 0x00001009
35#define DIVE_ERR_FB_ALREADY_ACQUIRED 0x0000100a
36#define DIVE_ERR_ACQUIRE_FAILED 0x0000100b
37#define DIVE_ERR_BANK_SWITCH_FAILED 0x0000100c
38#define DIVE_ERR_DEACQUIRE_FAILED 0x0000100d
39#define DIVE_ERR_INVALID_PALETTE 0x0000100e
40#define DIVE_ERR_INVALID_DESTINATION_RECTL 0x0000100f
41#define DIVE_ERR_INVALID_BUFFER_NUMBER 0x00001010
42#define DIVE_ERR_SSMDD_NOT_INSTALLED 0x00001011
43#define DIVE_ERR_BUFFER_ALREADY_ACCESSED 0x00001012
44#define DIVE_ERR_BUFFER_NOT_ACCESSED 0x00001013
45#define DIVE_ERR_TOO_MANY_BUFFERS 0x00001014
46#define DIVE_ERR_ALLOCATION_ERROR 0x00001015
47#define DIVE_ERR_INVALID_LINESIZE 0x00001016
48#define DIVE_ERR_FATAL_EXCEPTION 0x00001017
49#define DIVE_ERR_INVALID_CONVERSION 0x00001018
50#define DIVE_ERR_VSD_ERROR 0x00001019
51#define DIVE_ERR_COLOR_SUPPORT 0x0000101a
52#define DIVE_ERR_OUT_OF_RANGE 0x0000101b
53#define DIVE_WARN_NO_SIZE 0x00001100
54
55#define DIVE_BUFFER_SCREEN 0x00000000
56#define DIVE_BUFFER_GRAPHICS_PLANE 0x00000001
57#define DIVE_BUFFER_ALTERNATE_PLANE 0x00000002
58
59#define DIVE_FULLY_VISIBLE 0xffffffff
60
61
62/* Notes:
63 Associated/Allocated memory buffers start at: 0x00000010
64
65 Specifing DIVE_BUFFER_GRAPHICS_PLANE results in the image being
66 transferred to the graphics plane.
67 Specifing DIVE_BUFFER_ALTERNATE_PLANE results in the image being
68 transferred to the alternate (e.g. overlay) plane. If your
69 hardware doesn't support such a plane, this is an error.
70 Specifing DIVE_BUFFER_SCREEN will result in the image being
71 transferred to either the graphics plane buffer or the alternate
72 plane buffer based on if an alternate buffer exists and based on
73 the suitability the overlay plane to accelerate the scaling of
74 the image. If DIVE chooses to use the alternate buffer, it
75 will also paint the overlay "key" color on the graphics plane.
76 This automatic painting does not occur if the alternate plane
77 is explicitly specified.
78*/
79
80
81
82typedef struct _DIVE_CAPS {
83
84 ULONG ulStructLen; /* Set equal to sizeof(DIVE_CAPS) */
85 ULONG ulPlaneCount; /* Number of defined planes. */
86
87 /* Info returned in the following fields pertains to ulPlaneID. */
88 BOOL fScreenDirect; /* TRUE if can get addressability to vram. */
89 BOOL fBankSwitched; /* TRUE if vram is bank-switched. */
90 ULONG ulDepth; /* Number of bits per pixel. */
91 ULONG ulHorizontalResolution; /* Screen width in pixels. */
92 ULONG ulVerticalResolution; /* Screen height in pixels. */
93 ULONG ulScanLineBytes; /* Screen scan line size in bytes. */
94 FOURCC fccColorEncoding; /* Colorspace encoding of the screen. */
95 ULONG ulApertureSize; /* Size of vram aperture in bytes. */
96
97 ULONG ulInputFormats; /* Number of input color formats. */
98 ULONG ulOutputFormats; /* Number of output color formats. */
99 ULONG ulFormatLength; /* Length of format buffer. */
100 PVOID pFormatData; /* Pointer to color format buffer FOURCC's.*/
101
102 } DIVE_CAPS;
103typedef DIVE_CAPS *PDIVE_CAPS;
104
105
106
107
108typedef struct _SETUP_BLITTER {
109
110 /* Set the ulStructLen field equal to the amount of the structure used. */
111 /* allowable: blank lines below mark sizes of 8, 28, 32, 52, 60, or 68. */
112 ULONG ulStructLen;
113 /* Set the ulInvert flags based on the following: */
114 /* b0001 = d01 = h01 = flip the image in the horizontal direction. */
115 /* b0010 = d02 = h02 = flip the image in the vertical direction. */
116 /* All other bits ignored. */
117 ULONG fInvert;
118
119 /* This is the color format of the source data. See "FOURCC.H" */
120 FOURCC fccSrcColorFormat;
121 /* This is the width of the source image in pixels. */
122 ULONG ulSrcWidth;
123 /* This is the height of the source image in pixels. */
124 ULONG ulSrcHeight;
125 /* This is the horizontal offset from which to start displaying for */
126 /* use in displaying a sub-portion of the source image. */
127 ULONG ulSrcPosX;
128 /* This is the vertical offset from which to start displaying. */
129 ULONG ulSrcPosY;
130
131 /* This is the dither type to use. 0 defines no dither and 1 */
132 /* defines 2x2 dither (all others ignored). Note: dithering is only */
133 /* supported in direct color to LUT8 conversions. */
134 ULONG ulDitherType;
135
136 /* This is the color format of the destinaion data. See "FOURCC.H" */
137 FOURCC fccDstColorFormat;
138 /* This is the width of the destination image in pixels. */
139 ULONG ulDstWidth;
140 /* This is the height of the destination image in pixels. */
141 ULONG ulDstHeight;
142 /* This is the horizontal offset from which to start displaying for */
143 /* use in displaying to sub-portion of the destination image. */
144 LONG lDstPosX;
145 /* This is the vertical offset from which to start displaying. */
146 LONG lDstPosY;
147
148 /* This is the world screen horizontal position, where 0 is left. */
149 /* These are ignored if the destination is not the screen. */
150 LONG lScreenPosX;
151 /* This is the world screen vertical position, where 0 is bottom. */
152 LONG lScreenPosY;
153
154 /* This is the number of visible rectangular regions being passed in. */
155 /* These are ignored if the destination is not the screen. */
156 /* Also, if you application *KNOWS* that the region is fully visible */
157 /* (like not going to the screen), the you can use DIVE_FULLY_VISIBLE */
158 /* instead of making up a bogus visible region structure. */
159 ULONG ulNumDstRects;
160 /* This points to an array of visible regions which defines what */
161 /* portions of the source image are to be displayed. */
162 PRECTL pVisDstRects; /* Pointer to array of visible rectangles. */
163
164 } SETUP_BLITTER;
165typedef SETUP_BLITTER *PSETUP_BLITTER;
166
167
168
169ULONG APIENTRY DiveQueryCaps ( PDIVE_CAPS pDiveCaps,
170 ULONG ulPlaneBufNum );
171
172ULONG APIENTRY DiveOpen ( HDIVE *phDiveInst,
173 BOOL fNonScreenInstance,
174 PVOID ppFrameBuffer );
175
176ULONG APIENTRY DiveSetupBlitter ( HDIVE hDiveInst,
177 PSETUP_BLITTER pSetupBlitter );
178
179ULONG APIENTRY DiveBlitImage ( HDIVE hDiveInst,
180 ULONG ulSrcBufNumber,
181 ULONG ulDstBufNumber );
182
183#ifdef INCL_MM_OS2
184/* Same as DiveBlitImage, except pbLineMask points to one byte per line */
185/* in source image buffer such that 0: unchanged, 0xFF: changed */
186ULONG APIENTRY DiveBlitImageLines ( HDIVE hDiveInst,
187 ULONG ulSrcBufNumber,
188 ULONG ulDstBufNumber,
189 PBYTE pbLineMask );
190#endif
191
192ULONG APIENTRY DiveClose ( HDIVE hDiveInst );
193
194ULONG APIENTRY DiveAcquireFrameBuffer ( HDIVE hDiveInst,
195 PRECTL prectlDst );
196
197ULONG APIENTRY DiveSwitchBank ( HDIVE hDiveInst,
198 ULONG ulBankNumber );
199
200ULONG APIENTRY DiveDeacquireFrameBuffer ( HDIVE hDiveInst );
201
202ULONG APIENTRY DiveCalcFrameBufferAddress ( HDIVE hDiveInst,
203 PRECTL prectlDest,
204 PBYTE *ppDestinationAddress,
205 PULONG pulBankNumber,
206 PULONG pulRemLinesInBank );
207
208/* Notes on DiveAllocImageBuffer:
209 If pbImageBuffer is not NULL, the buffer is associated rather than
210 allocated. If pbImageBuffer is not NULL and the buffer number
211 pointed to by pulBufferNumber is non-zero, a new buffer pointer is
212 associated with the buffer number. Even though no memory is
213 allocated by DiveAllocImageBuffer when user-allocated buffers are
214 associated, DiveFreeImageBuffer should be called to release the
215 buffer association to avoid using up available buffer indexes.
216 The specified line size will be used if a buffer is allocated in
217 system memory, or if a user buffer is associated. If the
218 specified line size is zero, the allocated line size is rounded up
219 to the nearest DWORD boundry.
220*/
221
222ULONG APIENTRY DiveAllocImageBuffer ( HDIVE hDiveInst,
223 PULONG pulBufferNumber,
224 FOURCC fccColorSpace,
225 ULONG ulWidth,
226 ULONG ulHeight,
227 ULONG ulLineSizeBytes,
228 PBYTE pbImageBuffer );
229
230ULONG APIENTRY DiveFreeImageBuffer ( HDIVE hDiveInst,
231 ULONG ulBufferNumber );
232
233ULONG APIENTRY DiveBeginImageBufferAccess ( HDIVE hDiveInst,
234 ULONG ulBufferNumber,
235 PBYTE *ppbImageBuffer,
236 PULONG pulBufferScanLineBytes,
237 PULONG pulBufferScanLines );
238
239ULONG APIENTRY DiveEndImageBufferAccess ( HDIVE hDiveInst,
240 ULONG ulBufferNumber );
241
242
243
244/* Notes on palettes:
245 Neither DiveSetSourcePalette nor DiveSetDestinationPalette API's will set
246 the physical palette. If your application MUST set the PHYSICAL palette,
247 try using no more than 236 entries (the middle 236: 10-245, thus leaving
248 the top and bottom 10 entries for the Workplace Shell). If your
249 application MUST use ALL 256 entries, it must do so as a full-screen
250 (i.e. maximized) application. Remember, No WM_REALIZEPALETTE message
251 will be sent to other running applications, meaning they will not redraw
252 and their colors will be all wrong. It is not recommended that a
253 developer use these commands:
254
255 To set physical palette, do the following:
256 hps = WinGetPS ( HWND_DESKTOP );
257 hdc = GpiQueryDevice ( hps );
258 GpiCreateLogColorTable ( hps, LCOL_PURECOLOR | LCOL_REALIZABLE,
259 LCOLF_CONSECRGB, 0, 256, (PLONG)plRGB2Entries );
260 Gre32EntrY3 ( hdc, 0L, 0x000060C6L );
261 WinInvalidateRect ( HWND_DESKTOP, (PRECTL)NULL, TRUE );
262 WinReleasePS ( hps );
263
264 To reset physical palette, do the following:
265 hps = WinGetPS ( HWND_DESKTOP );
266 hdc = GpiQueryDevice ( hps );
267 Gre32EntrY3 ( hdc, 0L, 0x000060C7L );
268 WinInvalidateRect ( HWND_DESKTOP, (PRECTL)NULL, TRUE );
269 WinReleasePS ( hps );
270*/
271
272
273/* Use either of the two defines as the pRGB2Entries pointer to have DIVE */
274/* query and set the physical or default palette as source or destination. */
275
276#define DIVE_PALETTE_PHYSICAL (PBYTE)0x00000000
277#define DIVE_PALETTE_DEFAULT (PBYTE)0xffffffff
278
279ULONG APIENTRY DiveSetDestinationPalette ( HDIVE hDiveInst,
280 ULONG ulStartIndex,
281 ULONG ulNumEntries,
282 PBYTE pbRGB2Entries );
283
284ULONG APIENTRY DiveSetSourcePalette ( HDIVE hDiveInst,
285 ULONG ulStartIndex,
286 ULONG ulNumEntries,
287 PBYTE pbRGB2Entries );
288
289#ifdef INCL_MM_OS2
290ULONG APIENTRY DiveSetTransparentBlitMode ( HDIVE hDiveInst,
291 ULONG ulTransBlitMode,
292 ULONG ulValue1,
293 ULONG ulValue2 );
294
295/* The following transparent blitting modes are supported: */
296
297#define DIVE_TBM_NONE 0x0
298/* No transparency, i.e. all pixels are transferred (default) */
299
300#define DIVE_TBM_EXCLUDE_SOURCE_VALUE 0x01
301/* Source pixels with values that exactly match the value specified in */
302/* ulValue1 are not transferred. */
303
304#define DIVE_TBM_EXCLUDE_SOURCE_RGB_RANGE 0x02
305/* Source pixels with values that lie within the range specified in RGB */
306/* color space specified by ulValue1 (minimum) and ulValue2 (maximum) */
307/* are not transferred by DiveBlitImage. */
308
309#define DIVE_TBM_INCLUDE_SOURCE_RGB_RANGE 0x03
310/* Source pixels with values that lie outside the range specified in RGB */
311/* color space specified by ulValue1 (minimum) and ulValue2 (maximum) */
312/* are not transferred by DiveBlitImage. */
313
314#define DIVE_TBM_EXCLUDE_SOURCE_YUV_RANGE 0x04
315/* Source pixels with values that lie within the range specified in RGB */
316/* color space specified by ulValue1 (minimum) and ulValue2 (maximum) */
317/* are not transferred by DiveBlitImage. */
318
319#define DIVE_TBM_INCLUDE_SOURCE_YUV_RANGE 0x05
320/* Source pixels with values that lie outside the range specified in RGB */
321/* color space specified by ulValue1 (minimum) and ulValue2 (maximum) */
322/* are not transferred by DiveBlitImage. */
323
324/* Notes on transparent blitting:
325 Supported transparent blitting functions are all based on source pixel
326 values. A pixel in the destination image buffer is not modified if the
327 corresponding pixel in the source buffer is "transparent". The color
328 values or color value ranges specified in ulValue1 and ulValue2 are
329 dependent on the source image color format (fccSrcColorFormat) and the
330 color space in which the range comparison is taking place.
331
332 FOURCC_LUT8:
333 The color value is specified in the low 8 bits of parameter
334
335 FOURCC_Y888, FOURCC_Y2X2, FOURCC_Y4X4, FOURCC_YUV9, FOURCC_Y644, FOURCC_Y422:
336 23:8 - Y, 15:8 - U, 7:8 - V (bits 31:8 ignored)
337
338 FOURCC_R565, FOURCC_R555, FOURCC_R664, FOURCC_RGB3, FOURCC_BGR3, FOURCC_RGB4,
339 FOURCC_BGR4:
340 23:8 - R, 15:8 - G, 7:8 - B (bits 31:8 ignored)
341 R, G, and B components are specified with 8 bit significance, regardless
342 of significance in the source data.
343
344 Transparent blitting of other source image formats is not supported.
345
346 For range comparisons in RGB or YUV, the three components are compared
347 independently against the minimum and maximum values specified by the
348 ulValue1 and ulValue2 parameters respectively. A value is considered to
349 within the specified range if all three components satisfy:
350 min <= value <= max.
351
352 For EXCLUDE_SOURCE_VALUE tranparent blitting, the specified value in
353 ulValue1 is assumed to be in the source color space as described above.
354 For range comparisons, the values specified in ulValue1 and ulValue2 are
355 assumed to be in the color space in which the range comparison is to be
356 performed, either YUV or RGB.
357
358 - For range comparisons in YUV where the source data format is a YUV
359 form, the values in ulValue1 and ulValue2 are in the source YUV
360 format.
361
362 - For range comparisons in YUV where the source data format is RGB,
363 conversion of source data format from RGB to YUV using standard
364 CCIR601 equations is assumed (refer to fourcc.h).
365
366 - For range comparisons in RGB where the source data format is an RGB
367 form, the values in ulValue1 and ulValue2 specify the RGB range with
368 5 bits significance in R, 6 bits in G, and 5 bits in B.
369
370 - For range comparisons in RGB where the source data format is YUV,
371 conversion of source data format from YUV to RGB using standard
372 CCIR601 equations is assumed (refer to fourcc.h).
373
374
375
376*/
377
378#endif
379
380#endif
381#ifdef __cplusplus
382}
383#endif
384
Note: See TracBrowser for help on using the repository browser.