home *** CD-ROM | disk | FTP | other *** search
/ NEXT Generation 27 / NEXT27.iso / pc / demos / emperor / dx3.exe / DOCS / README / DDRAW.TXT < prev    next >
Text File  |  1996-09-10  |  39KB  |  785 lines
  1. ************************
  2. ***                  ***
  3. ***                  ***
  4. *** DirectDraw Notes ***
  5. ***                  ***
  6. ***                  ***
  7. ************************
  8.  
  9. Last updated  September 10, 1996
  10.  
  11. Notes for DirectDraw 3.0
  12. ========================================
  13. The CoCreateInstance API cannot be used to create an IDirectDraw2 object.
  14. To work around this problem, create a DirectDraw object and call 
  15. QueryInterface on it to get the IDirectDraw2 interface. 
  16.  
  17. IDirectDrawSurface2::Flip may cause your machine to hang. To work around this
  18. problem, call IDirectDrawSurface::Flip instead.
  19.  
  20.  
  21. Notes for DirectDraw 2.0  
  22. ========================================
  23.  
  24. In some hardware configurations, stretched transparent blits do not work
  25. correctly. If at all possible, when writing DirectDraw applications, you 
  26. should avoid using stretched transparent blits. To work around this 
  27. limitation, you can do a stretched blit to an intermediate surface, followed
  28. by a transparent blit to your original destination surface.
  29.  
  30. On some, relatively rare, older video boards, source color key blitting 
  31. to the primary surface may not work. You can work around this by composing 
  32. your image with transparency to a back buffer, then blitting the result to
  33. the primary surface.
  34.  
  35. DirectDraw::Initialize() is now called if the DirectDraw object
  36. is created with standard COM methods.
  37.  
  38.  
  39. Notes for DirectDraw 2.0  Beta 3
  40. ========================================
  41.  
  42.  
  43. SetDisplayMode now supports setting the monitor refresh rate
  44. ------------------------------------------------------------
  45. The IDirectDraw2::SetDisplayMode function now takes two additional 
  46. parameters.  The dwRefreshRate parameter can be used to specify a 
  47. monitor refresh rate in Hz.  Valid refresh rates can now be enumerated
  48. with the IDirectDraw2::EnumDisplayModes function. The refresh rate is 
  49. returned in the dwRefreshRate field of the DDSURFACEDESC structure.
  50.  
  51. If a refresh rate of 0 is specified in SetDisplayMode, this means to 
  52. revert back to the IDirectDraw behaviour and set the default refresh
  53. rate for the specified mode.  The display driver may or may not enumerate
  54. specific refresh rates for each mode.  If no refresh rate is specified
  55. by the driver for a particular mode, the dwRefreshRate field in the 
  56. DDSURFACEDESC structure set by EnumDisplayModes will be 0.
  57.  
  58.  
  59. Direct Draw modes now respect monitor settings
  60. ----------------------------------------------
  61. Windows 95 allows a user to specify the type of monitor that is being 
  62. used.  DirectDraw now checks the display modes that it knows about against
  63. the display restrictions of the installed monitor.  If it is determined 
  64. that the requested mode is not compatible with the monitor, then SetDisplayMode
  65. will fail.  Only modes which are supported on the installed monitor will be 
  66. enumerated in EnumDisplayModes.
  67.  
  68.  
  69. IDirectDrawSurface2::DDGetInterface now supported
  70. -------------------------------------------------
  71. A new method has been added to the IDirectDrawSurface2 interface which is 
  72. call DDGetInterface.  This function returns a pointer to the DirectDraw 
  73. object that was used to create the specified surface.
  74.  
  75. Direct Draw clipper objects now have a COM class factory
  76. --------------------------------------------------------
  77. Direct Draw clipper objects now have full class factory support for COM
  78. compliance. Clippers can now be created using either CoGetClassObject
  79. to obtain a class factory and then calling CreateInstance or by calling
  80. CoCreateInstance directly. The class identifier for the clipper class is
  81. CLSID_DirectDrawClipper. Please note that it is still possible to create
  82. clipper objects using either of the two existing API functions;
  83. DirectDrawCreateClipper or IDirectDraw::CreateClipper. Class factory 
  84. support is provided in addition to these functions rather than in
  85. replacement of them.
  86.  
  87. Clippers created by the class factory mechanism must be initialized
  88. with the IDirectDrawClipper::Initialize member before use. Initialize
  89. takes two parameters; a DirectDraw driver object interface pointer and
  90. a flags field. Currently the flags field must be 0. If a NULL driver object
  91. is specified then the clipper is not owned by a Direct Draw driver object
  92. and behaves identically to clippers created with DirectDrawCreateClipper.
  93. If a driver object is specified the clipper will be owned by that driver
  94. object and behaves identically to IDirectDraw::CreateClipper.
  95.  
  96. Flip now flips all levels of a mip-map
  97. --------------------------------------
  98. Previously, Flip only flipped the the mip-map level supplied as an
  99. argument. Now, however, Flip will flip all the levels of a mip-map
  100. from the level supplied to the lowest level in the map. A destination
  101. surface can also be provided in which case all levels in the mip-map will
  102. flip to the back buffer in thier flippable chain which matches the supplied
  103. override. For example, if the third back buffer in the top level
  104. flippable chain is supplied all levels in the mip-map will flip to thier
  105. third back buffer.
  106.  
  107. The number of levels in a mip-map is now stored explicitly
  108. ----------------------------------------------------------
  109. The number of levels in a mip-map chain is now stored explicitly.
  110. When the surface description of a mip-map is obtained (via
  111. IDirectDrawSurface::Lock or IDirectDrawSurface::GetSurfaceDesc) the
  112. dwMipMapCount field will contain the number of levels in a mip-map
  113. including the top-level. Note, for levels other than the top-level
  114. in the map, dwMipMapCount will specify the number of levels from
  115. that map to the smallest map in the chain.
  116.  
  117. New surface capability bit for Direct3D texture loading
  118. -------------------------------------------------------
  119. A new surface capability bit, DDSCAPS_ALLOCONLOAD, has been added
  120. to support device dependent and compressed texture surfaces. This
  121. capability bit specifies that a given texture surface does not
  122. have memory allocated for it when it is created. Instead, sufficient
  123. memory will be allocated when the texture is loaded using the Direct3D
  124. texture Load member. Currently the semantics of this bit are not fully
  125. implemented and the width, height and pixel format of the texture
  126. surface should be specified when DDSCAPS_ALLOCONLOAD is specified.
  127. However, for the final release, width, height and pixel format will
  128. not be specified at create time but will be initialized when the
  129. texture is loaded. If DDSCAPS_ALLOCONLOAD is specified so must
  130. DDSCAPS_TEXTURE. For further information see the Direct3D documentation
  131. on the IDirect3DTexture::Load member function.
  132.  
  133.  
  134. Notes for DirectDraw 2.0  Beta 2
  135. ========================================
  136.  
  137.  
  138. Support for high resolutions and TrueColor bit depths
  139. -----------------------------------------------------
  140. Direct Draw supports all of the screen resolutions and depths supported 
  141. by the Display Driver.  Version 1.0 of Direct Draw limited the available 
  142. video modes to 640x480 with pixel depths of 8 bits per pixel and 16 bits 
  143. per pixel.  This restriction has been relaxed and Direct Draw now allows 
  144. an application to change the mode into any mode supported by the Display 
  145. Driver.  This includes all supported 24 and 32 bits-per-pixel modes.
  146.  
  147. Note that this release of Direct Draw does not check the monitor capabilities 
  148. stored by the system to determine if a particular display resolution is 
  149. compatible with the monitor.  This means that an application may use 
  150. EnumerateDisplayModes to determine the available video modes and then switch 
  151. into a mode that is not supported by the monitor.  This is a defect which 
  152. will be corrected in the next release.
  153.  
  154.  
  155. HEL Blitting Support for 24 and 32 bit Surfaces 
  156. -----------------------------------------------
  157. Direct Draw now supports HEL blitting of 24 and 32 bits-per-pixel surfaces.  
  158. If the Display Driver supports blitting at these resolutions then the 
  159. hardware blitter will be used for vram to vram blits.  Otherwise, the 
  160. Hardware Emulation Layer (HEL) will be used to do the blits.
  161.  
  162.  
  163. Multiple Direct Draw Objects per Process
  164. ----------------------------------------
  165. Direct Draw 1.0 only allowed the creation of one Direct Draw object per 
  166. process.  If your process happened to use another system component (such 
  167. as Direct Play) that created a Direct Draw object, the process would be 
  168. unable to create another Direct Draw object for its own use.
  169.  
  170. This restriction has been eliminated in this release.  It is now possible 
  171. for a process to call DirectDrawCreate as many times as necessary.  A 
  172. unique and independent interface will be returned from each call.  Each 
  173. DirectDraw object may be used as desired.  There are no dependencies 
  174. between the objects.  They behave exactly as they would if they had been 
  175. created by two different processes.
  176.  
  177. Since the Direct Draw objects are independent, surface, palette, and 
  178. clipper objects which are created with a particular Direct Draw object 
  179. should not be used with other Direct Draw objects.  This is because these 
  180. objects are automatically released when the Direct Draw object is 
  181. destroyed.  If they are used with another Direct Draw object, they 
  182. may go away if the original object is destroyed.
  183.  
  184. Clipper objects which are created with DirectDrawClipperCreate are 
  185. independent of any particular Direct Draw object and may be used with 
  186. one or more Direct Draw objects.
  187.  
  188.  
  189. SetCooperativeLevel Doesn't Require an HWND for non-Exclusive Mode
  190. ------------------------------------------------------------------
  191. Direct Draw 1.0 required an HWND to be specified in the SetCooperativeLevel 
  192. call regardless of whether or not Full-screen Exclusive mode was being 
  193. requested.  This function no longer requires an HWND to be specified 
  194. if the application is requesting DDSCL_NORMAL mode.  It is now possible 
  195. for an application to use Direct Draw with multiple windows.  All of these 
  196. windows may be used simultaneously in normal windowed mode.
  197.  
  198.  
  199. New IDirectDraw2 and IDirectDrawSurface2 interfaces
  200. ---------------------------------------------------
  201. The COM model that Direct Draw uses specifies that additional functionality 
  202. is provided by providing new interfaces.  This release of Direct Draw 
  203. implements a new Direct Draw interface and a new Direct Draw Surface 
  204. interface.  These new interfaces may be obtained by using QueryInterface 
  205. as shown in the following code fragment:
  206.  
  207.     /*
  208.      * create an IDirectDraw2 interface
  209.      */
  210.     LPDIRECTDRAW        lpDD;
  211.     LPDIRECTDRAW2       lpDD2;
  212.  
  213.     ddrval = DirectDrawCreate( NULL, &lpDD, NULL );
  214.     if( ddrval != DD_OK )
  215.         return;
  216.  
  217.     ddrval = lpDD->SetCooperativeLevel( hwnd, DDSCL_NORMAL );
  218.     if( ddrval != DD_OK )
  219.         return;
  220.  
  221.  
  222.     ddrval = lpDD->QueryInterface( IID_IDirectDraw2, (LPVOID *)&lpDD2);
  223.     if( ddrval != DD_OK )
  224.         return;
  225.  
  226.  
  227.     ddscaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
  228.     ddrval = lpDD2->GetAvailableVidMem(&ddscaps, &total, &free);
  229.     if( ddrval != DD_OK )
  230.         return;
  231.  
  232. This code fragment shows C++ syntax for creating an IDirectDraw interface 
  233. and then using QueryInterface to create an IDirectDraw2 interface.  It is 
  234. this interface which contains the GetAvailableVidMem function.  An attempt 
  235. to use the GetAvailableVidMem function from an IDirectDraw interface will 
  236. result in a compile-time error.
  237.  
  238. The IDirectDraw2 interface contains all of the same member functions as the 
  239. IDirectDraw interface along with one additional member functions called  
  240. GetAvailableVidMem.  The SetDisplayMode function in this interface will 
  241. allow refresh rates to be specified.  This is not enabled for this beta and 
  242. this function will return DDERR_UNSUPPORTED.  The SetDisplayMode function 
  243. in the IDirectDraw interface can be used instead.
  244.  
  245. The IDirectDrawSurface2 interface contains all of the same member functions 
  246. as the IDirectDrawSurface interface with two additional member functions 
  247. called PageLock and PageUnlock.  The following code fragment shows how to 
  248. create an IDirectDrawSurface2 interface:
  249.  
  250.     LPDIRECTDRAWSURFACE     lpSurf;
  251.     LPDIRECTDRAWSURFACE2    lpSurf2;
  252.  
  253.     // Create surfaces
  254.     memset( &ddsd, 0, sizeof( ddsd ) );
  255.     ddsd.dwSize = sizeof( ddsd );
  256.     ddsd.dwFlags = DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;
  257.     ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN |
  258.                           DDSCAPS_SYSTEMMEMORY;
  259.     ddsd.dwWidth = 10;
  260.     ddsd.dwHeight = 10;
  261.  
  262.     ddrval = lpDD2->CreateSurface( &ddsd, &lpSurf, NULL );
  263.     if( ddrval != DD_OK )
  264.         return;
  265.  
  266.     ddrval = lpSurf->QueryInterface( IID_IDirectDrawSurface2, (LPVOID *)&lpSurf2);
  267.     if( ddrval != DD_OK )
  268.         return;
  269.  
  270.     ddrval = lpSurf2->PageLock( 0 );
  271.     if( ddrval != DD_OK )
  272.         return;
  273.  
  274.     ddrval = lpSurf2->PageUnlock( 0 );
  275.     if( ddrval != DD_OK )
  276.         return;
  277.     
  278.  
  279. New PageLock and PageUnlock functions
  280. -------------------------------------
  281. A new feature that is supported with this release is the capability for 
  282. DirectDraw to allow a driver to control the blitting to or from a system 
  283. memory surface.  A driver may choose to do this blitting by copying the 
  284. bytes one by one or by using DMA transfers.  If the driver uses a DMA 
  285. transfer, it is important that the system memory which contains the bits 
  286. for the surface is locked so that it cannot be paged out while the DMA is 
  287. in progress.  This can be done using the PageLock and PageUnlock functions 
  288. available in the IDirectDrawSurface2 interface.
  289.  
  290. HRESULT PageLock( LPDIRECTDRAWSURFACE lpddSurf, DWORD dwFlags );
  291. HRESULT PageUnlock( LPDIRECTDRAWSURFACE lpddSurf, DWORD dwFlags );
  292.  
  293. There are no flags currently defined for these functions so the only valid 
  294. value for dwFlags is 0.  This function may be called on a vram surface but 
  295. it will simply return DD_OK without doing anything.  If called on a Sytem 
  296. Memory surface (ddsCaps.dwCaps & DDSCAPS_SYSTEMMEMORY is nonzero) then all 
  297. of the memory pages used by this surface will be locked so that they canít 
  298. be paged out.  A Lock count is maintained for each surface and incremented 
  299. each time PageLock is called for that surface.  The count is decremented 
  300. when PageUnlock is called.  When the count reaches 0, the memory is unlocked 
  301. and may then be paged by the operating system.  Note that the performance 
  302. of the operating system may be negatively affected if too much memory is 
  303. locked.
  304.  
  305. The following codes may be returned from these two functions:
  306. DD_OK
  307. DDERR_INVALIDOBJECT
  308. DDERR_INVALIDPARAMS
  309. DDERR_SURFACE_LOCK
  310. DDERR_CANTPAGELOCK
  311.  
  312.  
  313. Driver can now Blit to and from System Memory surfaces
  314. ------------------------------------------------------
  315. In DirectDraw 1.0, if a surface was in system memory, the HEL automatically 
  316. performed the blit.  Some display cards have DMA hardware which allows them 
  317. to efficiently blit to and from system memory surfaces.  The DDCAPS 
  318. structure has been expanded to allow drivers to report this capability.  
  319. The following fields have been added.
  320.  
  321. DWORD   dwSVBCaps
  322. DWORD   dwSVBCKeyCaps
  323. DWORD   dwSVBFXCaps
  324. DWORD   dwSVBRops[DD_ROP_SPACE]
  325.  
  326. DWORD   dwVSBCaps
  327. DWORD   dwVSBCKeyCaps
  328. DWORD   dwVSBFXCaps
  329. DWORD   dwVSBRops[DD_ROP_SPACE]
  330.  
  331. DWORD   dwSSBCaps
  332. DWORD   dwSSBCKeyCaps
  333. DWORD   dwSSBFXCaps
  334. DWORD   dwSSBRops[DD_ROP_SPACE]
  335.  
  336. The SVB prefix indicates capabilities bits that relate to System memory to 
  337. Video memory Blits.  The VSB prefix indicates capabilities bits that relate 
  338. to Video memory to System memory Blits.  The SSB prefix indicates 
  339. capabilities bits that relate to System memory to System memory Blits.
  340.  
  341. The dwSVBCaps field corresponds to the dwCaps field except that it describes 
  342. the blitting capabilities of the display driver for System Memory to Video 
  343. Memory blits.  Likewise, the dwSVBCKeyCaps corresponds to the dwCKeyCaps 
  344. field and dwSVBFXCaps corresponds to dwFXCaps.  The dwSVBRops array describes 
  345. the raster ops that the driver supports for this type of blit.
  346.  
  347. These fields are only valid if the DDCAPS_CANBLTSYSMEM bit is set in dwCaps 
  348. indicating that the driver is able to blit to or from system memory.
  349.  
  350. If the system memory surface being used by the hardware blitter is not 
  351. locked, Direct Draw will automatically call PageLock on the surface to insure 
  352. that the memory has been locked.  
  353.  
  354.  
  355. DirectDraw Palette Objects
  356. ==========================
  357.  
  358. Setting Palettes on Non-Primary surfaces
  359. ----------------------------------------
  360. In DirectDraw 1.0 palettes could only be attached to the primary surface.
  361. Palettes can now be attached to any palletized surface (primary, back
  362. buffer, offscreen plain or texture map). Only those palettes attached 
  363. to primary surfaces will have any effect on the system palette. In it
  364. important to note that DirectDraw blits never perform color conversion -
  365. any palettes attached to the source or destination surface of a blit are 
  366. ignored. Furthermore, the DirectDraw surface function GetDC() also ignores
  367. any DirectDraw palette selected into the surface.
  368.  
  369. Non-primary surface palettes are intended for use by applications or
  370. Direct3D (or other 3D renderer).
  371.  
  372. Sharing Palettes
  373. ----------------
  374. Palettes can now be shared between multiple surfaces. The same palette
  375. can be set on the front and back buffer of a flipping chain or shared
  376. between multiple texture surfaces. When a palette is attached to a
  377. surface with SetPalette(), the surface increments the reference count 
  378. of that palette. When the reference count of the surface reaches zero
  379. it will decrement the reference count of the attached palette. In
  380. addition, if a palette is detached from a surface by calling SetPalette()
  381. with a NULL palette interface pointer, the reference count of the
  382. surface's palette will be decremented. Please note that if SetPalette()
  383. is called several times consecutively for the same surface with the 
  384. same palette the reference count for the palette will be incremented
  385. once only. Subsequent calls will not effect the paletteís reference count.
  386.  
  387. New Palette Types
  388. -----------------
  389. In additional to the 8-bit (256 entry) palettes supported previously,
  390. DirectDraw 2.0 supports 1-bit (2 entry), 2-bit (4 entry) and 4-bit
  391. (16 entry) palettes. Such palettes can by created by specifying one of
  392. the new palette capability flags; DDPCAPS_1BIT, DDPCAPS_2BIT and
  393. DDPCAPS_4BIT. Matching capability flags have been added for surface
  394. pixel formats (DDPF_PALETTEINDEXED1, DDPF_PALETTEINDEXED2 and
  395. DDPF_PALETTEINDEXED4). A palette can only be attached to a surface with
  396. a matching pixel format. For example, a 2 entry palette created with the
  397. DDPCAPS_1BIT flag can only be attached to a 1-bit surface created with
  398. the pixel format flag DDPF_PALETTEINDEXED1 etc. Furthermore, it is now
  399. possible to create indexed palettes. An indexed palette is one whose
  400. entries do not hold RGB colors but integer indices into the array of
  401. PALETTEENTRYs of some target palette. An indexed palette's color table
  402. is an array of 2, 4, 16 or 256 bytes where each byte is an index into
  403. some unspecified, destination palette.
  404.  
  405. To create an indexed palette specify the palette capability flag
  406. DDPCAPS_8BITENTRIES when calling CreatePalette(). For example, to
  407. create a 4-bit, indexed palette specify DPCAPS_4BIT | DDPCAPS_8BITENTRIES.
  408. When creating an indexed palette a pointer to an array of BYTEs is passed
  409. rather than a pointer to an array of PALETTEENTRY structures. The pointer
  410. to the array of BYTEs must be cast to an LPPALETTEENTRY when calling
  411. CreatePalette().
  412.  
  413. DirectDraw Clipper Objects
  414. ==========================
  415.  
  416. Sharing Clippers
  417. ----------------
  418. Clippers can now be shared between multiple surfaces. For example, the
  419. same clipper can be set on both the front and back buffers of a flipping
  420. chain. When a clipper is attached to a surface with SetClipper(), the
  421. surface increments the reference count of that clipper. When the reference
  422. count of the surface reaches zero it will decrement the reference count 
  423. of the attached clipper. In addition, if a clipper is detached from a
  424. surface by calling SetClipper() with a NULL clipper interface pointer,
  425. the reference count of the surface's clipper will be decremented.
  426.  
  427. Please note that if SetClipper() is called several times consecutively
  428. for the same surface with the same clipper the reference count for the
  429. clipper will be incremented once only. Subsequent calls will not 
  430. effect the clipper's reference count.
  431.  
  432. Driver Independent Clippers
  433. ---------------------------
  434. It is now possible to create clipper objects which are not owned by a
  435. DirectDraw driver object. Such clippers can be shared across multiple
  436. driver objects. Driver independent clipper objects are created with 
  437. the new DirectDraw API function DirectDrawCreateClipper(). This function
  438. can be called before any DirectDraw driver objects are created. As these
  439. clippers are not owned by any DirectDraw driver object, they are not
  440. automatically released when an application's driver objects are released.
  441. If not released explicitly by the application such clippers will be
  442. released by DirectDraw when the application terminates.
  443.  
  444. It is still possible to create clippers with the DirectDraw interface
  445. member function CreateClipper(). Such clippers behave identically to
  446. the clippers of DirectDraw 1.0. Specifically they will be automatically
  447. released when the driver object from which they were created is released.
  448.  
  449. Enhanced Surface Format Support in the Hardware Emulation Layer (HEL)
  450. =====================================================================
  451.  
  452. In DirectDraw 1.0 the Hardware Emulation Layer (HEL) could only create
  453. surfaces whose pixel format exactly matched that of the current primary
  454. surface. This restriction has been relaxed for DirectDraw 2.0. 
  455.  
  456. The HEL now supports the following pixel formats for offscreen plain
  457. surfaces.
  458.  
  459. Pixel Format Flags                Bit Depth  Red Mask   Green Mask  Blue Mask  Alpha Mask
  460. DDPF_RGB | DDPF_PALETTEINDEXED1    1         0x00000000 0x00000000  0x00000000 0x00000000
  461. DDPF_RGB | DDPF_PALETTEINDEXED2    2         0x00000000 0x00000000  0x00000000 0x00000000
  462. DDPF_RGB | DDPF_PALETTEINDEXED4    4         0x00000000 0x00000000  0x00000000 0x00000000
  463. DDPF_RGB | DDPF_PALETTEINDEXED8    8         0x00000000 0x00000000  0x00000000 0x00000000
  464. DDPF_RGB                          16         0x0000F800 0x000007E0  0x0000001F 0x00000000
  465. DDPF_RGB                          16         0x00007C00 0x000003E0  0x0000001F 0x00000000
  466. DDPF_RGB                          24         0x00FF0000 0x0000FF00  0x000000FF 0x00000000
  467. DDPF_RGB                          24         0x000000FF 0x0000FF00  0x00FF0000 0x00000000
  468. DDPF_RGB                          32         0x00FF0000 0x0000FF00  0x000000FF 0x00000000
  469. DDPF_RGB                          32         0x000000FF 0x0000FF00  0x00FF0000 0x00000000
  470.  
  471. In addition to supporting a wider range of offscreen surface formats the
  472. HEL also supports surfaces intended for use by Direct3D (or other 3D
  473. renders). These surfaces are discussed in the next section.
  474.  
  475. Support for 3D Surfaces
  476. =======================
  477.  
  478. Support for surfaces specific to 3D rendering has been enhanced in
  479. DirectDraw 2.0. The 3D specific surface types; texture maps, mipmaps
  480. and Z-buffers will be discussed below.
  481.  
  482. Texture Maps
  483. ------------
  484. The surface capability flag used to indicate that a surface is a texture
  485. is DDSCAPS_TEXTURE. This flag was previously DDSCAPS_TEXTUREMAP but was
  486. modified for consistency with Direct3D. Texture maps can now be allocated
  487. in system memory using the HEL. To allocate a texture map surface specify
  488. the DDSCAPS_TEXTURE flag in the ddsCaps field of the surface description
  489. passed to CreateSurface(). A wide range of texture pixel formats are
  490. supported by the HEL. These formats are as follows:
  491.  
  492. Pixel Format Flags                 Bit Depth  Red Mask   Green Mask  Blue Mask  Alpha Mask
  493. DDPF_RGB | DDPF_PALETTEINDEXED1,    1         0x00000000 0x00000000  0x00000000 0x00000000 
  494. DDPF_RGB | DDPF_PALETTEINDEXED1 |
  495.            DDPF_PALETTEINDEXEDTO8   1         0x00000000 0x00000000  0x00000000 0x00000000
  496. DDPF_RGB | DDPF_PALETTEINDEXED2     2         0x00000000 0x00000000  0x00000000 0x00000000
  497. DDPF_RGB | DDPF_PALETTEINDEXED2 |
  498.            DDPF_PALETTEINDEXEDTO8   2         0x00000000 0x00000000  0x00000000 0x00000000
  499. DDPF_RGB | DDPF_PALETTEINDEXED4     4         0x00000000 0x00000000  0x00000000 0x00000000
  500. DDPF_RGB | DDPF_PALETTEINDEXED4 |
  501.            DDPF_PALETTEINDEXEDTO8   4         0x00000000 0x00000000  0x00000000 0x00000000
  502. DDPF_RGB | DDPF_PALETTEINDEXED8     8         0x00000000 0x00000000  0x00000000 0x00000000
  503. DDPF_RGB,                           8         0x000000E0 0x0000001C  0x00000003 0x00000000
  504. DDPF_RGB | DDPF_ALPHAPIXELS,       16         0x00000F00 0x000000F0  0x0000000F 0x0000F000
  505. DDPF_RGB,                          16         0x0000F800 0x000007E0  0x0000001F 0x00000000
  506. DDPF_RGB,                          16         0x0000001F 0x000007E0  0x0000F800 0x00000000
  507. DDPF_RGB,                          16         0x00007C00 0x000003E0  0x0000001F 0x00000000
  508. DDPF_RGB | DDPF_ALPHAPIXELS,       16         0x00007C00 0x000003E0  0x0000001F 0x00008000
  509. DDPF_RGB,                          24         0x00FF0000 0x0000FF00  0x000000FF 0x00000000
  510. DDPF_RGB,                          24         0x000000FF 0x0000FF00  0x00FF0000 0x00000000
  511. DDPF_RGB,                          32         0x00FF0000 0x0000FF00  0x000000FF 0x00000000
  512. DDPF_RGB,                          32         0x000000FF 0x0000FF00  0x00FF0000 0x00000000
  513. DDPF_RGB | DDPF_ALPHAPIXELS,       32         0x00FF0000 0x0000FF00  0x000000FF 0xFF000000
  514. DDPF_RGB | DDPF_ALPHAPIXELS,       32         0x000000FF 0x0000FF00  0x00FF0000 0xFF000000
  515.  
  516. The above formats are those which can be created by the HEL in system
  517. memory. The DirectDraw driver for a 3D accelerated video card is free to
  518. create textures of other formats in video memory. Such a driver should
  519. export the DDSCAPS_TEXTURE bit to indicate that it can create textures
  520. and should be prepared to handle the DirectDraw HAL callback,
  521. CanCreateSurface() to verify that the surface description for a texture
  522. map is one the driver is prepared to create.
  523.  
  524. Mipmaps
  525. -------
  526. DirectDraw 2.0 supports mipmapped texture surfaces. A mipmap is a
  527. sequence of textures, each of which is a progressively lower resolution,
  528. pre-filtered representation of the same image. Mipmaps are a
  529. computationally low cost way of improving the quality of rendered textures.
  530. Each pre-filtered image (or level) in the mipmap is a power of two
  531. smaller than the previous level. In DirectDraw 2.0 mipmaps are represented
  532. as a chain of attached surfaces. The highest resolution texture is at the
  533. head of the chain and has, as an attachment, the next level of the mipmap
  534. which has, in turn, an attachment which is the next level in the mipmap
  535. and so on down to the lowest resolution level of the mipmap.
  536.  
  537. To create a surface representing a single level of a mipmap specify the
  538. DDSCAPS_MIPMAP surface capability in the surface description passed to
  539. CreateSurface(). As all mipmaps are also textures the DDSCAPS_TEXTURE
  540. capability must also be specified. It is possible to create each level
  541. manually and build the chain with AddAttachedSurface(). However,
  542. CreateSurface() can be used to build an entire mipmap chain in a single
  543. operation. The following code fragment demonstrates building a chain 
  544. of five mipmap levels of sizes 256x256, 128x128, 64x64, 32x32 and 16x16.
  545.  
  546.         DDSURFACEDESC       ddsd;
  547.         LPDIRECTDRAWSURFACE lpDDMipMap;
  548.         ZeroMemory(&ddsd, sizeof(ddsd));
  549.         ddsd.dwSize = sizeof(ddsd);
  550.         ddsd.dwFlags = DDSD_CAPS | DDSD_MIPMAPCOUNT;
  551.         ddsd.dwMipMapCount = 5;
  552.         ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE | DDSCAPS_MIPMAP | 
  553.                 DDSCAPS_COMPLEX;
  554.         ddsd.dwWidth = 256UL;
  555.         ddsd.dwHeight = 256UL;
  556.  
  557.         ddres = lpDD->CreateSurface(&ddsd, &lpDDMipMap);
  558.         if (FAILED(ddres))
  559.                 ...
  560.                 
  561. It is permissible to omit the number of mipmaps levels, in which case
  562. CreateSurface() will create a chain of surfaces each a power of two
  563. smaller than the previous one down to the smallest possible size. It is 
  564. also possible to omit the width and height in which case CreateSurface()
  565. will create the number of levels you specify with a minimum level size of
  566. 1x1.
  567.  
  568. A chain of mipmap surfaces is traversed using GetAttachedSurface()
  569. specifying the DDSCAPS_MIPMAP and DDSCAPS_TEXTURE capability flags. The
  570. following code fragment traverses a mipmap chain from highest to lowest
  571. resolutions.
  572.  
  573.         LPDIRECTDRAWSURFACE lpDDLevel, lpDDNextLevel;
  574.         DDSCAPS ddsCaps;
  575.  
  576.         lpDDLevel = lpDDMipMap;
  577.         lpDDLevel->AddRef();
  578.         ddsCaps.dwCaps = DDSCAPS_TEXTURE | DDSCAPS_MIPMAP;
  579.         ddres = DD_OK;
  580.         while (ddres == DD_OK)
  581.         {
  582.                 // Process this level
  583.                 ...     
  584.                 ddres = lpDDLevel->GetAttachedSurface(&ddsCaps,                 
  585.                         &lpDDNextLevel);
  586.                 lpDDLevel->Release();
  587.                 lpDDLevel = lpDDNextLevel;
  588.         }
  589.         if ((ddres != DD_OK) && (ddres != DDERR_NOTFOUND))
  590.                 ...
  591.                 
  592. It is also possible to build flippable chains of mipmaps. In this
  593. scenario each mipmap level has an associated chain of back buffer
  594. texture surfaces. Each back buffer texture is attached to one level
  595. of the mipmap. Only the front buffer in the chain has DDSCAPS_MIPMAP
  596. set, the others are simply texture maps (DDSCAPS_TEXTURE). A mipmap
  597. level can have two attached texture maps, one with the capability flag 
  598. DDSCAPS_MIPMAP set, which is the next level in the mipmap chain, and one
  599. with the capability flag DDSCAPS_BACKBUFFER set, which is back buffer
  600. of the flippable chain. Note that all the surfaces in each flippable
  601. chain must be of the same size.
  602.  
  603. It is not possible to build such a surface arrangement with a single
  604. call to CreateSurface(). To construct a flippable mipmap either build
  605. a complex mipmap chain and manually attach backbuffers with
  606. AddAttachedSurface() or create a sequence of flippable chains and
  607. build the mipmap with AddAttachedSurface().
  608.  
  609. It is important to note that blit operations apply to only a single
  610. level in the mipmap chain. To blit an entire chain of mipmaps each
  611. level must be blit separately. Also note that Flip()will not currently
  612. flip an entire mipmap chain but only a single level of the mipmap. This
  613. is a defect and will be corrected.
  614.  
  615. Z Buffers
  616. ---------
  617. The DirectDraw HEL can now create Z buffers for use by Direct3D (or
  618. other 3D rendering software). The HEL supports both 16 and 32-bit
  619. Z buffers. The DirectDraw driver for a 3D accelerated video card can 
  620. permit the creation of Z buffers in video memory by exporting the surface
  621. capability bit DDSCAPS_ZBUFFER. It should also specify the Z buffer
  622. depths it supports using the dwZBufferBitDepth field of the DDCAPS
  623. structure.
  624.  
  625. Z buffers can be cleared using the DirectDraw surface function Blt().
  626. A new DDBLT_ flag (DDBLT_DEPTHFILL) has been defined to indicate that
  627. the blit is a Z buffer clear. If this flag is specified the DDBLTFX
  628. structure passed to Blt() should have its dwFillDepth field set to
  629. the required Z depth. If the DirectDraw driver for a 3D accelerated
  630. video card wishes to provide support for Z buffer clearing in hardware
  631. it should export the capability flag DDCAPS_BLTDEPTHFILL and should
  632. have code to handle DDBLT_DEPTHFILL blits. The destination surface
  633. of a depth fill blit must be a Z buffer. Please note that the actual
  634. interpretation of depth value is 3D renderer specific.
  635.  
  636. Direct3D Integration
  637. ====================
  638.  
  639. DirectDraw 2.0 is very tightly integrated with Direct3D. The most
  640. important aspects of this integration are discussed below.
  641.  
  642. The Direct3D Driver Interface
  643. -----------------------------
  644. DirectDraw 2.0 presents a single, unified driver object to the
  645. application programmer. This driver object encapsulates both
  646. DirectDraw and Direct3D state. The DirectDraw driver COM interfaces 
  647. (IID_IDirectDraw or IID_IDirectDraw2) and the Direct3D driver COM interface 
  648. (IID_IDirect3D) are both interfaces which allow the application programmer
  649. to communicate with the same underlying driver object. Hence no Direct3D
  650. driver object is created. Rather a Direct3D interface to the DirectDraw
  651. driver object is obtained. This is achieved using the standard COM 
  652. QueryInterface() function.
  653.  
  654. The following code fragment demonstrates creating the DirectDraw driver
  655. object and obtaining a Direct3D interface for communicating with that object.
  656.  
  657.         LPDIRECTDRAW lpDD;
  658.         LPDIRECT3D   lpD3D;
  659.         ddres = DirectDrawCreate(NULL, &lpDD, NULL);
  660.         if (FAILED(ddres))
  661.                 ...
  662.         ddres = lpDD->QueryInterface(IID_IDirect3D, &lpD3D);
  663.         if (FAILED(ddres))
  664.                 ...
  665.                 
  666. The above code creates a single object and obtains two interfaces to
  667. that object. Hence, the reference count of the driver object after the
  668. QueryInterface() is two. The important implication of this is that the
  669. lifetime of the Direct3D driver state is the same as that of the DirectDraw
  670. object. Releasing the Direct3D interface does not destroy the Direct3D
  671. driver state. That state is not destroyed until all references (both
  672. DirectDraw and Direct3D) to that driver object have been released.
  673. Hence, if you release a Direct3D interface, while holding a reference
  674. to a DirectDraw driver interface, and then re-query the Direct3D
  675. interface all the Direct3D state will be preserved.
  676.  
  677. The Direct3D Device Interface
  678. -----------------------------
  679. As with the driver object, there is no distinct Direct3D device object.
  680. A Direct3D device is simply an interface for communicating with a
  681. DirectDraw surface used as a 3D rendering target. For example, the 
  682. following code fragment creates a Direct3D device interface to a
  683. DirectDraw surface object.
  684.  
  685.         LPDIRECTDRAWSURFACE lpDDSurface;
  686.         LPDIRECT3DDEVICE    lpD3DDevice;
  687.  
  688.         ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface, NULL);
  689.         if (FAILED(ddres))
  690.                 ...
  691.         ddres = lpDDSurface->QueryInterface(lpGuid, &lpD3DDevice);
  692.         if (FAILED(ddres))
  693.                 ...
  694.                 
  695. The same rules of reference counting and state lifetime discussed for
  696. driver objects apply to DirectDraw surfaces and Direct3D devices.
  697. Additionally, multiple, distinct Direct3D device interfaces can be
  698. obtained for the same DirectDraw surface. Hence, it is possible that
  699. a single DirectDraw surface be the target for both a ramp based device
  700. and an RGB based device.
  701.  
  702. The Direct3D Texture Interface
  703. ------------------------------
  704. Direct3D textures are, once again, not a distinct object type but
  705. rather another interface of DirectDraw surface objects. The following
  706. code fragment obtains a Direct3D texture interface from a DirectDraw 
  707. surface object.
  708.  
  709.         LPDIRECTDRAWSURFACE lpDDSurface;
  710.         LPDIRECT3DTEXTURE   lpD3DTexture;
  711.  
  712.         ddres = lpDD->CreateSurface(&ddsd, &lpDDSurface, NULL);
  713.         if (FAILED(ddres))
  714.                 ...
  715.         ddres = lpDDSurface->QueryInterface(IID_IDirect3DTexture, 
  716.                 &lpD3DTexture);
  717.         if (FAILED(ddres))
  718.                 ...
  719.                 
  720. The same reference counting and state lifetime rules of driver objects
  721. and devices apply. It is possible to use a single DirectDraw surface as
  722. both a rendering target and a texture.
  723.  
  724. The DirectDraw HEL and Direct3D
  725. -------------------------------
  726. The DirectDraw HEL has been enhanced to support the creation of texture,
  727. mipmap and Z buffer surfaces. Furthermore, due to the tight integration
  728. of DirectDraw and Direct3D, a DirectDraw enabled system will always
  729. provide Direct3D support (in software emulation at least). Hence, the
  730. DirectDraw HEL exports the DDCAPS_3D capability flag to indicate the
  731. availability of Direct3D in software emulation. A DirectDraw driver for
  732. a hardware accelerated 3D video card should export this capability flag
  733. to indicate the presence of hardware accelerated 3D.
  734.  
  735. GetAvailableVidMem
  736. ==================
  737. DirectDraw 2.0 adds a new DirectDraw interface function to query the
  738. amount of video memory available to a specific type of surface as
  739. defined by surface capability flags. To ensure COM compliance this 
  740. function is not a member of the DirectDraw 1.0 interface but is part
  741. of the new DirectDraw 2.0 interface, IID_IDirectDraw2. To invoke this
  742. function you must first query for the new DirectDraw interface. 
  743.  
  744. The following code fragment demonstrates using GetAvailableVidMem()
  745. to determine both the total and free video memory available for
  746. texture map surfaces.
  747.  
  748.         LPDIRECTDRAW2 lpDD2;
  749.         DDSCAPS       ddsCaps;
  750.         DWORD         dwTotal;
  751.         DWORD         dwFree;
  752.  
  753.         ddres = lpDD->QueryInterface(IID_IDirectDraw2, &lpDD2);
  754.         if (FAILED(ddres))
  755.                 ...
  756.         ddsCaps.dwCaps = DDSCAPS_TEXTURE;
  757.         ddres = lpDD2->GetAvailableVidMem(&ddsCaps, &dwTotal, &dwFree);
  758.         if (FAILED(ddres))
  759.                 ...
  760.                 
  761. It should be noted that this function gives a snapshot of the current
  762. video memory state only. The amount of free video memory is subject to
  763. change as surfaces are created and released. Hence, the free memory 
  764. figure should be used as a rough guide only. In addition, a particular
  765. video card may make no distinction between two different memory types.
  766. For example, it may use the same portion of video memory to store Z 
  767. buffers and textures. Hence, allocating one type of surface (a Z buffer
  768. say) may affect the amount of video memory available for another type
  769. of surface (textures say). Therefore, it is best to first allocate an 
  770. application's fixed resources (such as front, back and Z buffer) before
  771. determining how much memory is available for dynamic use (for texture
  772. mapping, for example).
  773.  
  774. Miscellaneous Changes
  775. =====================
  776.  
  777. New Error Return Codes
  778. ----------------------
  779. DDERR_NOMIPMAPHW - an attempt was made to create a mipmap in video
  780. memory but the hardware DirectDraw driver does not support mipmaps.
  781.  
  782. DDERR_INVALIDSURFACETYPE - an attempt was made to perform an operation
  783. on a surface but the capabilities of that surface do not support the
  784. operation.
  785.