1 #ifndef _INCLUDED_AWTEXLD_H_ 2 #define _INCLUDED_AWTEXLD_H_ 3 4 #ifdef __cplusplus 5 extern "C" { 6 #define _AWTL_DEFAULTPARM(v) = (v) 7 #else /* ! __cplusplus */ 8 #define _AWTL_DEFAULTPARM(v) 9 #endif /* ? __cplusplus */ 10 11 #ifdef _MSC_VER 12 #define _AWTL_VARARG __cdecl 13 #else 14 #define _AWTL_VARARG 15 #endif 16 17 #include "aw.h" 18 19 /******************************/ 20 /* return codes & error codes */ 21 /******************************/ 22 23 typedef 24 enum AwTlErc 25 { 26 /* General Errors */ 27 AW_TLE_OK /* apparent success */ 28 , AW_TLE_DXERROR /* unexpected DirectX error - see awTlLastDxErr */ 29 , AW_TLE_BADPARMS /* parameters passed to function were invalid, or requested unsupported functionality */ 30 , AW_TLE_NOINIT /* initialization functions have not been successfully called */ 31 /* File reading errors */ 32 , AW_TLE_CANTOPENFILE /* file open failed - see awTlLastWinErr for the Windows error code */ 33 , AW_TLE_CANTREADFILE /* unexpected error reading file - see awTlLastWinErr for the Windows error code */ 34 , AW_TLE_EOFMET /* unexpected end of file encountered */ 35 , AW_TLE_BADFILEFORMAT /* file format identifier not recognized */ 36 , AW_TLE_BADFILEDATA /* file data not consistent */ 37 /* Conversion errors */ 38 , AW_TLE_CANTPALETTIZE /* texture format is palettized; file data is not */ 39 , AW_TLE_IMAGETOOLARGE /* image size is larger in one or both dimensions than maximum texture size */ 40 , AW_TLE_CANTRELOAD /* loading a new texture into an existing surface failed because the existing surface is an unsuitable size, etc. */ 41 } 42 AW_TL_ERC; 43 44 45 /*********/ 46 /* Flags */ 47 /*********/ 48 49 enum 50 { 51 AW_TLF_DEFAULT = 0x00000000U /* no flags set */ 52 , AW_TLF_TRANSP = 0x00000001U /* src data has transparency */ 53 , AW_TLF_PREVSRC = 0x00000002U /* in AwRestoreTexture, use previously stored source data flags (AW_TLF_TRANSP only) */ 54 , AW_TLF_COMPRESS = 0x00000004U /* use ALLOCONLOAD flag */ 55 , AW_TLF_CHROMAKEY = 0x00000008U /* use chroma keying for transparency when the texture format has an alpha channel */ 56 , AW_TLF_VIDMEM = 0x00000010U /* use Video memory for surfaces which are not textures */ 57 , AW_TLF_PREVSRCALL = 0x00000020U /* in AwRestoreTexture, use ALL previously stored flags, except AW_TLF_CHECKLOST and AW_TLF_SKIPNOTLOST */ 58 , AW_TLF_TEXTURE = 0x00000040U /* in AwCreateSurface, create a surface in the texture format with the texture flag set */ 59 , AW_TLF_MINSIZE = 0x00000080U /* with the 'a' option, ensure all surfaces/textures created are at least as big as the rectangle specified even if the rect is partially off the image */ 60 , AW_TLF_CHECKLOST = 0x00000100U /* checks for lost surfaces and calls restore on them */ 61 , AW_TLF_SKIPNOTLOST = 0x00000200U /* if the above flag also is specified, does not bother trying to restore surfaces which weren't lost */ 62 63 , _AW_TLF_FORCE32BITENUM = 0x0fffffffU /* probably entirely unnecessary */ 64 }; 65 66 /* SBF - alt_tab junk */ 67 #define ATIncludeSurfaceDb(p, d, s) fprintf(stderr, "ATIncludeSurfaceDb: %s/%d: %s\n", __FILE__, __LINE__, s) 68 #define ATIncludeTextureDb(p, d, s) fprintf(stderr, "ATIncludeTextureDb: %s/%d: %s\n", __FILE__, __LINE__, s) 69 void ATIncludeSurface(DDSurface * pSurface, AW_BACKUPTEXTUREHANDLE hBackup); 70 void ATRemoveSurface(DDSurface * pSurface); 71 void ATRemoveTexture(D3DTexture * pTexture); 72 73 74 extern AW_TL_ERC awTlLastErr; 75 76 extern D3DTexture * AwCreateTexture(char const * _argFormatS, ...); 77 extern DDSurface * AwCreateSurface(char const * _argFormatS, ...); 78 79 extern AW_TL_ERC AwDestroyBackupTexture(AW_BACKUPTEXTUREHANDLE _bH); 80 81 82 typedef int (* AW_TL_PFN_CALLBACK) (void *); 83 84 /* Structure for receiving specific regions of an image in a surface or texture. 85 * A pointer to an array of thise structures is passed to the AwCreate... 86 * functions if the 'a' format specifier is used. The fields 'left', 'right', 87 * 'top' and 'bottom' specify the rectangle to cut out of the image being loaded 88 * and must be valid. In AwCreateSurface, the 'pSurface' field is used and is a 89 * pointer to the Direct Draw surface created; in AwCreateTexture, the 90 * 'pTexture' field is used and is a pointer to the Direct 3D texture created. 91 * If an error occurs all the pointers in the array will be set to NULL. The 92 * 'width' and 'height' fields will be filled in with the width and height of 93 * the surface or texture that is created. If the rectangle specified is 94 * completely outsided the main image, the width and height will be set to zero, 95 * and the pointer field will be set to NULL, but this does not constitute an 96 * error. If the 't' option is used, the pointer fields are assumed to be valid 97 * textures or surfaces into which to load the new textures or surfaces. If the 98 * pointer is NULL, the structure is ignored. The pointers will remain unchanged 99 * even in the event of an error or a rectangle specified outside the main 100 * image, though the width and height will still be set to zero. 101 */ 102 struct AwCreateGraphicRegion 103 { 104 unsigned left, top, right, bottom; /* rectangle to cut from the original image */ 105 unsigned width, height; /* width and height of the resulting surface or texture */ 106 #if 0 107 union /* DDSurface or D3DTexture pointer depending on the context used */ 108 { 109 DDSurface * pSurface; /* Direct Draw Surface object pointer */ 110 D3DTexture * pTexture; /* Direct 3D Texture object pointer */ 111 }; 112 #endif 113 }; 114 115 /* typedef to save typing 'struct' when not using C++ */ 116 typedef struct AwCreateGraphicRegion AW_CREATEGRAPHICREGION; 117 118 extern char const * AwTlErrorToString(AW_TL_ERC _AWTL_DEFAULTPARM(awTlLastErr)); 119 120 #if 0 121 122 #include <windows.h> 123 #include <d3d.h> 124 125 /*********************************************/ 126 /* Note: */ 127 /* */ 128 /* This header file contains typedefs for */ 129 /* DDObject */ 130 /* D3DDevice */ 131 /* D3DTexture */ 132 /* D3DSurface */ 133 /* and #defines for their corresponding IIDs */ 134 /* GUID_DD_SURFACE */ 135 /* GUID_D3D_TEXTURE */ 136 /* */ 137 /* They are currently typedeffed as follows */ 138 /* typedef IDirectDraw2 DDObject; */ 139 /* typedef IDirect3DDevice D3DDevice; */ 140 /* typedef IDirect3DTexture D3DTexture; */ 141 /* typedef IDirect3DSurface DDSurface; */ 142 /*********************************************/ 143 #include "aw.h" 144 145 /***********************************************************************************/ 146 /* awTexLd.h - Author: Jake Hotson */ 147 /* */ 148 /* Loading of textures into D3D surfaces */ 149 /* requires DirectX 5 or later */ 150 /* requires db.c and db.h */ 151 /* also requires */ 152 /* Watcom C++ 11.0 or later */ 153 /* or Microsoft Visual C++ 5.0 or later */ 154 /* or another suitable compiler */ 155 /* */ 156 /* Load any known file format */ 157 /* Microsoft bitmap (.BMP) */ 158 /* OS/2 1.x bitmap (.BMP) */ 159 /* OS/2 2.x bitmap (.BMP) */ 160 /* Portable Bitmap (.PBM) */ 161 /* Portable Graymap (.PGM) */ 162 /* Portable Pixelmap (.PPM) */ 163 /* */ 164 /* Load from various media */ 165 /* File name */ 166 /* Windows file handle */ 167 /* Raw file data in memory */ 168 /* */ 169 /* Load into any given texture format provided a conversion is possible */ 170 /* Pad to the required size that the driver will accept */ 171 /* */ 172 /* Optional handling of transparency */ 173 /* Use alpha bits if available */ 174 /* Otherwise chroma keying to be used */ 175 /* Transparency colour is RGB(0,0,0) for non palettized data */ 176 /* Or index 0 in palettized data */ 177 /* */ 178 /* Optional storing of processed raw data */ 179 /* Use internal format independent of DirectX */ 180 /* Function to reload from this data into a possibly different texture format */ 181 /* */ 182 /* Five optional levels of diagnostics possible */ 183 /* 1. Logs when a function returns because of an error */ 184 /* 2. Logs the nature of the error */ 185 /* 3. Logs immediately when an error occurs */ 186 /* 4. Logs information as data is parsed, and when main functions are called */ 187 /* 5. Logs success of every small subsection of code */ 188 /* */ 189 /* Maximum error reporting */ 190 /* */ 191 /* Optimal Loading Speed */ 192 /***********************************************************************************/ 193 194 /* Version 2.1 */ 195 #define AW_TL_VERSION 210 /* Preprocessor constant can be used to determine the version of this code */ 196 197 /* 198 Version History: 199 ---------------- 200 version AW_TL_VERSION 201 0.9 090 Incomplete & May still contain bugs 202 0.91 091 AW_TLF_CHROMAKEY flag, and 't' option supported. Fewer bugs 203 0.92 092 Slightly more debug code 204 0.93 093 Using typedefs DDObject, D3DDevice, D3DTexture 205 1.0 100 Assumed to be bug-free 206 1.1 110 Internal redesign with interface to support any file format 207 1.2 120 Allow for loading into Direct Draw surfaces which are not textures 208 1.21 121 Two extra format flags to get width and height of actual image (as opposed to DD/D3D surface) 209 1.22 122 Split up the initialization function AwSetD3DDevice() into DD part and D3D part 210 1.3 130 New function: AwGetTextureSize() 211 1.31 131 New format flag for a callback function for when video mem runs out 212 1.4 140 Support for loading image split into several surfaces/textures and for loading surfaces as textures 213 1.5 150 Multiple texture format support 214 215 2.0 200 Beginning support for DX 6.0 - new AwSet..Format functions take LPDDPIXELFORMAT not LPDDSURFACEDESC 216 2.1 210 AW_TLF_CHECKLOST and AW_TLF_SKIPNOTLOST flags added 217 */ 218 219 /**********************************************/ 220 /* Handle C++ linkage and optional parameters */ 221 /**********************************************/ 222 223 #ifdef __cplusplus 224 extern "C" { 225 #define _AWTL_DEFAULTPARM(v) = (v) 226 #else /* ! __cplusplus */ 227 #define _AWTL_DEFAULTPARM(v) 228 #endif /* ? __cplusplus */ 229 230 #ifdef _MSC_VER 231 #define _AWTL_VARARG __cdecl 232 #else 233 #define _AWTL_VARARG 234 #endif 235 236 /******************************/ 237 /* return codes & error codes */ 238 /******************************/ 239 240 typedef 241 enum AwTlErc 242 { 243 /* General Errors */ 244 AW_TLE_OK /* apparent success */ 245 , AW_TLE_DXERROR /* unexpected DirectX error - see awTlLastDxErr */ 246 , AW_TLE_BADPARMS /* parameters passed to function were invalid, or requested unsupported functionality */ 247 , AW_TLE_NOINIT /* initialization functions have not been successfully called */ 248 /* File reading errors */ 249 , AW_TLE_CANTOPENFILE /* file open failed - see awTlLastWinErr for the Windows error code */ 250 , AW_TLE_CANTREADFILE /* unexpected error reading file - see awTlLastWinErr for the Windows error code */ 251 , AW_TLE_EOFMET /* unexpected end of file encountered */ 252 , AW_TLE_BADFILEFORMAT /* file format identifier not recognized */ 253 , AW_TLE_BADFILEDATA /* file data not consistent */ 254 /* Conversion errors */ 255 , AW_TLE_CANTPALETTIZE /* texture format is palettized; file data is not */ 256 , AW_TLE_IMAGETOOLARGE /* image size is larger in one or both dimensions than maximum texture size */ 257 , AW_TLE_CANTRELOAD /* loading a new texture into an existing surface failed because the existing surface is an unsuitable size, etc. */ 258 } 259 AW_TL_ERC; 260 261 extern AW_TL_ERC awTlLastErr; 262 extern HRESULT awTlLastDxErr; 263 extern DWORD awTlLastWinErr; 264 265 #ifdef NDEBUG 266 #define AwTlErrorToString ThisIsADebugFunction! /* generate compiler error */ 267 #define AwDxErrorToString ThisIsADebugFunction! /* generate compiler error */ 268 #define AwWinErrorToString ThisIsADebugFunction! /* generate compiler error */ 269 #else /* ! NDEBUG */ 270 extern char const * AwTlErrorToString(AW_TL_ERC _AWTL_DEFAULTPARM(awTlLastErr)); 271 extern char const * AwDxErrorToString(HRESULT _AWTL_DEFAULTPARM(awTlLastDxErr)); 272 extern char const * AwWinErrorToString(DWORD _AWTL_DEFAULTPARM(awTlLastWinErr)); 273 #endif /* ? NDEBUG */ 274 275 /*********/ 276 /* Flags */ 277 /*********/ 278 279 enum 280 { 281 AW_TLF_DEFAULT = 0x00000000U /* no flags set */ 282 , AW_TLF_TRANSP = 0x00000001U /* src data has transparency */ 283 , AW_TLF_PREVSRC = 0x00000002U /* in AwRestoreTexture, use previously stored source data flags (AW_TLF_TRANSP only) */ 284 , AW_TLF_COMPRESS = 0x00000004U /* use ALLOCONLOAD flag */ 285 , AW_TLF_CHROMAKEY = 0x00000008U /* use chroma keying for transparency when the texture format has an alpha channel */ 286 , AW_TLF_VIDMEM = 0x00000010U /* use Video memory for surfaces which are not textures */ 287 , AW_TLF_PREVSRCALL = 0x00000020U /* in AwRestoreTexture, use ALL previously stored flags, except AW_TLF_CHECKLOST and AW_TLF_SKIPNOTLOST */ 288 , AW_TLF_TEXTURE = 0x00000040U /* in AwCreateSurface, create a surface in the texture format with the texture flag set */ 289 , AW_TLF_MINSIZE = 0x00000080U /* with the 'a' option, ensure all surfaces/textures created are at least as big as the rectangle specified even if the rect is partially off the image */ 290 , AW_TLF_CHECKLOST = 0x00000100U /* checks for lost surfaces and calls restore on them */ 291 , AW_TLF_SKIPNOTLOST = 0x00000200U /* if the above flag also is specified, does not bother trying to restore surfaces which weren't lost */ 292 293 , _AW_TLF_FORCE32BITENUM = 0x0fffffffU /* probably entirely unnecessary */ 294 }; 295 296 /*********/ 297 /* Types */ 298 /*********/ 299 300 /* a callback function */ 301 typedef int (* AW_TL_PFN_CALLBACK) (void *); 302 303 /* Structure for receiving specific regions of an image in a surface or texture. 304 * A pointer to an array of thise structures is passed to the AwCreate... 305 * functions if the 'a' format specifier is used. The fields 'left', 'right', 306 * 'top' and 'bottom' specify the rectangle to cut out of the image being loaded 307 * and must be valid. In AwCreateSurface, the 'pSurface' field is used and is a 308 * pointer to the Direct Draw surface created; in AwCreateTexture, the 309 * 'pTexture' field is used and is a pointer to the Direct 3D texture created. 310 * If an error occurs all the pointers in the array will be set to NULL. The 311 * 'width' and 'height' fields will be filled in with the width and height of 312 * the surface or texture that is created. If the rectangle specified is 313 * completely outsided the main image, the width and height will be set to zero, 314 * and the pointer field will be set to NULL, but this does not constitute an 315 * error. If the 't' option is used, the pointer fields are assumed to be valid 316 * textures or surfaces into which to load the new textures or surfaces. If the 317 * pointer is NULL, the structure is ignored. The pointers will remain unchanged 318 * even in the event of an error or a rectangle specified outside the main 319 * image, though the width and height will still be set to zero. 320 */ 321 struct AwCreateGraphicRegion 322 { 323 unsigned left, top, right, bottom; /* rectangle to cut from the original image */ 324 unsigned width, height; /* width and height of the resulting surface or texture */ 325 union /* DDSurface or D3DTexture pointer depending on the context used */ 326 { 327 DDSurface * pSurface; /* Direct Draw Surface object pointer */ 328 D3DTexture * pTexture; /* Direct 3D Texture object pointer */ 329 }; 330 }; 331 332 /* typedef to save typing 'struct' when not using C++ */ 333 typedef struct AwCreateGraphicRegion AW_CREATEGRAPHICREGION; 334 335 /********************/ 336 /* Public functions */ 337 /********************/ 338 339 /* AwSetD3DDevice(DDObject * _ddP, D3DDevice * _d3ddeviceP) 340 341 Description: 342 Tells the texture loaders about the DirectDraw and 343 Direct3D setup. You must call this function before 344 loading any textures, and also every time you change 345 the DirectDraw or Direct3D device setup. 346 As of v1.22 this function is overloaded and only 347 available to C++ programmers. 348 349 Parameters: 350 _ddP 351 Pointer to the DirectDraw object obtained from 352 a call to DirectDrawCreate(). 353 _d3ddeviceP 354 Pointer to the Direct3DDevice object obtained 355 from its GUID which is the lpGuid parameter in 356 a call to a D3DENUMDEVICESCALLBACK function for 357 your chosen driver. 358 359 Returns: 360 AW_TLE_OK if the function completed successfully; 361 AW_TLE_BADPARMS if the parameters passed to the 362 function were incorrect 363 AW_TLE_DXERROR if a DirectX SDK call failed 364 */ 365 #ifdef __cplusplus 366 extern "C++" AW_TL_ERC AwSetD3DDevice(DDObject * _ddP, D3DDevice * _d3ddeviceP); 367 #endif 368 369 /* AwSetDDObject(DDObject * _ddP) 370 AwSetD3DDevice(D3DDevice * _d3ddeviceP) 371 372 Description: 373 These functions together do what the two parameter 374 version of AwSetD3DDevice(), above, does. You 375 needn't call AwSetD3DDevice() if you are only 376 loading direct draw surfaces. The parameters and 377 return values are as described above. 378 */ 379 380 extern AW_TL_ERC AwSetD3DDevice(D3DDevice * _d3ddeviceP); 381 extern AW_TL_ERC AwSetDDObject(DDObject * _ddP); 382 383 /* AwSetTextureFormat2(LPDDPIXELFORMAT _ddpfP) 384 385 Description: 386 Informs the texture loaders of the currently slected 387 texture format. You must call this function before 388 loading any textures, and also every time you change 389 the texture format. 390 391 Parameters: 392 _ddpfP 393 Pointer to a DDPIXELFORMAT structure which 394 describes the texture format. 395 396 Returns: 397 AW_TLE_OK if the function completed successfully; 398 AW_TLE_BADPARMS if the parameters passed to the 399 function were incorrect 400 */ 401 extern AW_TL_ERC AwSetTextureFormat2(LPDDPIXELFORMAT _ddpfP); 402 #define AwSetTextureFormat(_descP) (AwSetTextureFormat2((_descP) ? &(_descP)->ddpfPixelFormat : NULL)) 403 404 /* AwSetAdditionalTextureFormat2(LPDDPIXELFORMAT _ddpfP, unsigned _maxAlphaBits, int _canDoTransp, unsigned _maxColours) 405 406 Description: 407 Informs the texture loaders an additional texture 408 format that should be used in certain cases. After 409 a call to AwSetTextureFormat, there are no 410 additional formats. Each additional format that you 411 want to make available should be set with a call to 412 this function. When a texture is being loaded, the 413 additional formats are considered in the order that 414 they were set (ie. the order in which the calls to 415 this function were made). For each format 416 considered, if it could be used for the image and 417 the image's specification passes the tests for this 418 format, the format will replace the previously 419 chosen format (either the base format set by 420 AwSetTextureFormat or an earlier additional format 421 whose conditions of use were also met). 422 423 Parameters: 424 _ddpfP 425 Pointer to a DDPIXELFORMAT structure which 426 describes the texture format. 427 _maxAlphaBits 428 Specifies that this format should only be used 429 for images that do not have more bits of alpha 430 information than this value. 431 _canDoTransp 432 If zero, specifies that this format should not 433 be used for images which have a transparent 434 colour. 435 _maxColours 436 Specifies that this format should only be used 437 for images that do not contain more unique 438 colours than this value. If this value is zero, 439 the format can be used for images with any 440 number of colours. If this value is non-zero, 441 this format will not be used for images whose 442 number of unique colours cannot be determined. 443 444 Returns: 445 AW_TLE_OK if the function completed successfully; 446 AW_TLE_NOINIT if AwSetTextureFormat was not 447 previously called. 448 AW_TLE_BADPARMS if the parameters passed to the 449 function were incorrect 450 */ 451 extern AW_TL_ERC AwSetAdditionalTextureFormat2(LPDDPIXELFORMAT _ddpfP, unsigned _maxAlphaBits, int _canDoTransp, unsigned _maxColours); 452 #define AwSetAdditionalTextureFormat(_descP, _maxAlphaBits, _canDoTransp, _maxColours) (AwSetAdditionalTextureFormat2((_descP) ? &(_descP->ddpfPixelFormat) : NULL,_maxAlphaBits,_canDoTransp,_maxColours)) 453 454 /* AwSetSurfaceFormat2(LPDDPIXELFORMAT _ddpfP) 455 456 Description: 457 As for AwSetTextureFormat but tells AwCreateSurface() 458 what format surfaces for blitting should be in 459 */ 460 extern AW_TL_ERC AwSetSurfaceFormat2(LPDDPIXELFORMAT _ddpfP); 461 #define AwSetSurfaceFormat(_descP) (AwSetSurfaceFormat2((_descP) ? &(_descP)->ddpfPixelFormat : NULL)) 462 463 /* AwGetTextureSize(unsigned * _widthP, unsigned * _heightP, unsigned _width, unsigned _height) 464 465 Description: 466 Calculates the size required for a texture on the 467 current driver, given a minimum size required to 468 hold the proposed image. 469 470 Parameters: 471 _widthP 472 Pointer to a variable which will receive the 473 width required for a Direct 3D texture. 474 _heightP 475 Pointer to a variable which will receive the 476 height. 477 _width 478 Minimum width required for the proposed image. 479 _height 480 Minimum height required. 481 482 Returns: 483 AW_TLE_OK if the required Direct 3D texture size was 484 calculated; 485 AW_TLE_IMAGETOOLARGE if the driver specifies a 486 maximum texture size which is less than the size 487 that would be required to hold an image of the 488 proposed size; 489 AW_TLE_NOINIT if driver information was unavailable 490 because initialization functions weren't called. 491 */ 492 extern AW_TL_ERC AwGetTextureSize(unsigned * _widthP, unsigned * _heightP, unsigned _width, unsigned _height); 493 494 /* AwCreateTexture(char const * _argFormatS, ...) 495 496 Description: 497 Creates a Direct3D texture for use by the device 498 renderer. The exact functionality is determined by 499 the first argument which is a format specifier 500 string. 501 502 Parameters: 503 _argFormatS 504 Pointer to a null terminated string which 505 specifies the order, types and interpretations 506 of the other parameters. Each character in the 507 string corresponds to a parameter passed to the 508 function, and the parameters are parsed in the 509 same order as their format specifiers appear in 510 the string. For clarity, upper case letters are 511 used to indicate paramters which are pointers to 512 data that will be filled in by the function, and 513 lower case letters are used for parameters which 514 are simply data to be used by the function. 515 516 The following specifiers are permitted: 517 518 s The next argument is of type 'LPCTSTR' and is a 519 pointer to a ASCII or UNICODE string which is 520 the filename of an image file to load. 521 h The next argument is of type 'HANDLE' and is a 522 Windows file handle with its file pointer set to 523 the start of an image file's data. 524 p The next argument is of type 'void const *' and 525 is a pointer to an image file's data in memory. 526 r The next argument is of type 527 'AW_BACKUPTEXTUREHANDLE' and is used to restore 528 a previously loaded texture, possibly with the 529 texture format or Direct3D device having 530 changed. 531 x The next argument is of type 'unsigned' and is 532 the maximum number of bytes that should be read 533 from a file or memory. If parsing the file data 534 would cause more bytes to be read than this 535 value, the function fails and the error is 536 'AW_TLE_EOFMET'. This may be useful in 537 conjunction with format specifier 'm' in order 538 to prevent a general protection (GP) fault. 539 N The next argument is of type 'unsigned *' and 540 points to a variable which will receive the 541 number of bytes which are actually read from a 542 file or memory. This value will be filled in 543 even if the function fails (unless the error is 544 'AW_TLE_BADPARMS'). 545 f The next argument is of type 'unsigned' and can 546 be any combination of 'AW_TLF_...' flags (above) 547 which control special functionality. 548 W The next argument is of type 'unsigned *' and 549 points to a variable which will receive the 550 width of the texture that is created. 551 H The next argument is of type 'unsigned *' and 552 points to a variable which will receive the 553 height of the texture that is created. 554 X The next argument is of type 'unsigned *' and 555 points to a variable which will receive the 556 width of the original image. 557 Y The next argument is of type 'unsigned *' and 558 points to a variable which will receive the 559 height of the original image. 560 B The next argument is of type 561 'AW_BACKUPTEXTUREHANDLE *' and points to a 562 variable which will receive a handle that can 563 later be used with format specifier 'r' in a 564 call to this function in order to avoid 565 reloading from a file an image that has 566 previously been loaded. This value will be 567 filled in only if the function succeeds. When 568 you no longer need this handle, you should 569 deallocate the memory associated with it by 570 calling 'AwDestroyBackupTexture()'. 571 t The next argument is of type 'D3DTexture *' 572 and is used to load the new texture into an 573 existing texture surface. The parameter is NOT 574 Release()d; you should do this yourself. This is 575 only guaranteed to work if the new texture is of 576 the same height and pitch as the previous one 577 and compression is not used on either. 578 c The next two arguments indicate a callback 579 function which will be called if a texture cannot 580 be created due to insufficient video memory. The 581 idea is to allow the callee to free some video 582 memory and request further attempts at creating 583 the texture. The first of the two arguments is of 584 type AW_TL_PFN_CALLBACK and is a function pointer 585 to the function that would be called. This 586 function takes one parameter of type 'void *' 587 which is an implementation-specific value, and 588 returns type 'int', which is non-zero if another 589 attempt at creating the texture should be made. 590 If the callback function returns zero, then the 591 texture load will be aborted. The second of the 592 two arguments is of type 'void *' and is the 593 implementation-specific value passed to the 594 callback function. 595 a The next two arguments indicate an array of 596 rectangles to cut out of the original image and 597 create textures for each rectangle. The first of 598 these two arguments is of type 'unsigned' and is 599 the size of the array. The second argument is of 600 type 'AW_CREATEGRAPHICREGION *' and points to an 601 array of AwCreateGraphicRegion structs, each 602 indicating a region to cut out of the original 603 image and create a texture for. In this case, the 604 function always returns NULL, and you should test 605 for failure by examining awTlLastErr. The 't' 606 option, if used, must appear after 'a' in the 607 format string, and does not correspond to any 608 parameter, since the texture into which to 609 reload will be specified for each region in 610 the array of structures. The 'W' and 'H' options 611 will be ignored. For more information, see the 612 definition of this structure above. 613 614 There are some restrictions on parameters: 615 616 Exactly one of 's', 'h', 'p' or 'r' must be 617 used. 618 619 Neither 'x' nor 'N' may be used with 'r'. 620 621 'r' cannot be used with 'B'. 622 623 Neither 'W' or 'H' should be used with 'a'. 624 625 Each specifier should be used only once. 626 627 't' may not appear before 'a'. 628 629 There are no other restriction on the order 630 that the parameters occur. 631 632 Returns: 633 A valid D3DTexture * if the function succeeds; 634 awTlLastErr will also be AW_TLE_OK 635 NULL if the function fails. awTlLastErr will be 636 AW_TLE_BADPARMS if the parameters were 637 incorrect, or any other error code if the 638 parameters were correct but another error 639 occurred. 640 */ 641 extern D3DTexture * _AWTL_VARARG AwCreateTexture(char const * _argFormatS, ...); 642 643 /* AwCreateSurface(char const * _argFormatS, ...) 644 645 Description: 646 As for AwCreateTexture(), but returns a pointer to 647 a newly created direct draw surface which is not a 648 texture 649 650 Parameters: 651 _argFormatS 652 As AwCreateTexture(), except 653 654 t The next argument is of type 'DDSurface *' 655 656 */ 657 extern DDSurface * _AWTL_VARARG AwCreateSurface(char const * _argFormatS, ...); 658 659 /* AwDestroyBackupTexture(AW_BACKUPTEXTUREHANDLE _bH) 660 661 Description: 662 Deallocates the memory associated with a backup 663 texture handle, created by a call to 664 'AwCreateTexture()' with a 'B' specifier. The handle 665 cannot be used after this. 666 667 Parameters: 668 _bH 669 The handle whose associated memory should be 670 deallocated. 671 672 Returns: 673 AW_TLE_OK if the function succeeds. 674 AW_TLE_BADPARMS if the handle was not valid. 675 */ 676 extern AW_TL_ERC AwDestroyBackupTexture(AW_BACKUPTEXTUREHANDLE _bH); 677 678 #endif 679 680 681 682 683 684 685 686 687 688 689 /* End Wrappers */ 690 #ifdef __cplusplus 691 } 692 #endif /* __cplusplus */ 693 694 #endif /* ! _INCLUDED_AWTEXLD_H_ */ 695