1 /* 2 DSDL 3 Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20 21 ========================================================================== 22 23 Simple DirectMedia Layer 24 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 25 26 This software is provided 'as-is', without any express or implied 27 warranty. In no event will the authors be held liable for any damages 28 arising from the use of this software. 29 30 Permission is granted to anyone to use this software for any purpose, 31 including commercial applications, and to alter it and redistribute it 32 freely, subject to the following restrictions: 33 34 1. The origin of this software must not be misrepresented; you must not 35 claim that you wrote the original software. If you use this software 36 in a product, an acknowledgment in the product documentation would be 37 appreciated but is not required. 38 2. Altered source versions must be plainly marked as such, and must not be 39 misrepresented as being the original software. 40 3. This notice may not be removed or altered from any source distribution. 41 */ 42 43 /** 44 SDL Surfaces 45 46 See_Also: 47 $(LINK2 https://wiki.libsdl.org/SDL3/CategorySurface, SDL3 Surface Documentation) 48 49 Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga 50 License: Subject to the terms of the Zlib License, as written in the LICENSE file. 51 Authors: 52 Luna Nielsen 53 */ 54 module sdl.surface; 55 import sdl.stdc; 56 import sdl.properties; 57 import sdl.pixels; 58 import sdl.blendmode; 59 import sdl.rect; 60 import sdl.iostream; 61 62 extern(C) nothrow @nogc: 63 64 65 /** 66 The flags on an SDL_Surface. 67 68 These are generally considered read-only. 69 */ 70 alias SDL_SurfaceFlags = Uint32; 71 72 enum SDL_SurfaceFlags SDL_SURFACE_PREALLOCATED = 0x00000001u; /**< Surface uses preallocated pixel memory */ 73 enum SDL_SurfaceFlags SDL_SURFACE_LOCK_NEEDED = 0x00000002u; /**< Surface needs to be locked to access pixels */ 74 enum SDL_SurfaceFlags SDL_SURFACE_LOCKED = 0x00000004u; /**< Surface is currently locked */ 75 enum SDL_SurfaceFlags SDL_SURFACE_SIMD_ALIGNED = 0x00000008u; /**< Surface uses pixel memory allocated with SDL_aligned_alloc() */ 76 77 /** 78 The scaling mode. 79 */ 80 enum SDL_ScaleMode { 81 82 /** 83 Nearest pixel sampling 84 */ 85 SDL_SCALEMODE_NEAREST, 86 87 /** 88 Linear filtering 89 */ 90 SDL_SCALEMODE_LINEAR, 91 } 92 93 /** 94 The flip mode. 95 */ 96 enum SDL_FlipMode { 97 98 /** 99 Do not flip 100 */ 101 SDL_FLIP_NONE, 102 103 /** 104 Flip horizontally 105 */ 106 SDL_FLIP_HORIZONTAL, 107 108 /** 109 Flip vertically 110 */ 111 SDL_FLIP_VERTICAL 112 } 113 114 /** 115 A collection of pixels used in software blitting. 116 117 Pixels are arranged in memory in rows, with the top row first. Each row 118 occupies an amount of memory given by the pitch (sometimes known as the row 119 stride in non-SDL APIs). 120 121 Within each row, pixels are arranged from left to right until the width is 122 reached. Each pixel occupies a number of bits appropriate for its format, 123 with most formats representing each pixel as one or more whole bytes (in 124 some indexed formats, instead multiple pixels are packed into each byte), 125 and a byte order given by the format. After encoding all pixels, any 126 remaining bytes to reach the pitch are used as padding to reach a desired 127 alignment, and have undefined contents. 128 129 When a surface holds YUV format data, the planes are assumed to be 130 contiguous without padding between them, e.g. a 32x32 surface in NV12 131 format with a pitch of 32 would consist of 32x32 bytes of Y plane followed 132 by 32x16 bytes of UV plane. 133 134 See_Also: 135 $(D SDL_CreateSurface) 136 $(D SDL_DestroySurface) 137 */ 138 struct SDL_Surface; 139 140 /** 141 Allocate a new surface with a specific pixel format. 142 143 The pixels of the new surface are initialized to zero. 144 145 Params: 146 width = the width of the surface. 147 height = the height of the surface. 148 format = the $(D SDL_PixelFormat) for the new surface's pixel format. 149 150 Returns: 151 The new SDL_Surface structure that is created or $(D null) on failure; 152 call $(D SDL_GetError) for more information. 153 154 See_Also: 155 $(D SDL_CreateSurfaceFrom) 156 $(D SDL_DestroySurface) 157 */ 158 extern SDL_Surface* SDL_CreateSurface(int width, int height, SDL_PixelFormat format); 159 160 /** 161 Allocate a new surface with a specific pixel format and existing pixel 162 data. 163 164 No copy is made of the pixel data. Pixel data is not managed automatically; 165 you must free the surface before you free the pixel data. 166 167 Pitch is the offset in bytes from one row of pixels to the next, e.g. 168 `width*4` for `SDL_PIXELFORMAT_RGBA8888`. 169 170 You may pass $(D null) for pixels and 0 for pitch to create a surface that you 171 will fill in with valid values later. 172 173 Params: 174 width = the width of the surface. 175 height = the height of the surface. 176 format = the SDL_PixelFormat for the new surface's pixel format. 177 pixels = a pointer to existing pixel data. 178 pitch = the number of bytes between each row, including padding. 179 180 Returns: 181 The new $(D SDL_Surface) structure that is created or $(D null) on failure; 182 call $(D SDL_GetError) for more information. 183 184 See_Also: 185 $(D SDL_CreateSurface) 186 $(D SDL_DestroySurface) 187 */ 188 extern SDL_Surface* SDL_CreateSurfaceFrom(int width, int height, SDL_PixelFormat format, void* pixels, int pitch); 189 190 /** 191 Free a surface. 192 193 It is safe to pass $(D null) to this function. 194 195 Params: 196 surface = the SDL_Surface to free. 197 198 See_Also: 199 $(D SDL_CreateSurface) 200 $(D SDL_CreateSurfaceFrom) 201 */ 202 extern void SDL_DestroySurface(SDL_Surface* surface); 203 204 /** 205 Get the properties associated with a surface. 206 207 The following properties are understood by SDL: 208 209 - `SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating point 210 surfaces, this defines the value of 100% diffuse white, with higher 211 values being displayed in the High Dynamic Range headroom. This defaults 212 to 203 for HDR10 surfaces and 1.0 for floating point surfaces. 213 - `SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT`: for HDR10 and floating point 214 surfaces, this defines the maximum dynamic range used by the content, in 215 terms of the SDR white point. This defaults to 0.0, which disables tone 216 mapping. 217 - `SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING`: the tone mapping operator 218 used when compressing from a surface with high dynamic range to another 219 with lower dynamic range. Currently this supports "chrome", which uses 220 the same tone mapping that Chrome uses for HDR content, the form "*=N", 221 where N is a floating point scale factor applied in linear space, and 222 "none", which disables tone mapping. This defaults to "chrome". 223 224 Params: 225 surface = the SDL_Surface structure to query. 226 227 Returns: 228 a valid property ID on success or 0 on failure; call 229 $(D SDL_GetError) for more information. 230 */ 231 extern SDL_PropertiesID SDL_GetSurfaceProperties(SDL_Surface* surface); 232 233 enum SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT = "SDL.surface.SDR_white_point"; 234 enum SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT = "SDL.surface.HDR_headroom"; 235 enum SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING = "SDL.surface.tonemap"; 236 237 /** 238 Set the colorspace used by a surface. 239 240 Setting the colorspace doesn't change the pixels, only how they are 241 interpreted in color operations. 242 243 Params: 244 surface = the SDL_Surface structure to update. 245 colorspace = an SDL_Colorspace value describing the surface 246 colorspace. 247 248 Returns: 249 true on success or false on failure; call SDL_GetError() for more 250 information. 251 252 See_Also: 253 $(D SDL_GetSurfaceColorspace) 254 */ 255 extern bool SDL_SetSurfaceColorspace(SDL_Surface* surface, SDL_Colorspace colorspace); 256 257 /** 258 Get the colorspace used by a surface. 259 260 The colorspace defaults to SDL_COLORSPACE_SRGB_LINEAR for floating point 261 formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for 262 other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures. 263 264 Params: 265 surface = the SDL_Surface structure to query. 266 267 Returns: 268 The colorspace used by the surface, or $(D SDL_COLORSPACE_UNKNOWN) if 269 the surface is $(D null). 270 271 See_Also: 272 $(D SDL_SetSurfaceColorspace) 273 */ 274 extern SDL_Colorspace SDL_GetSurfaceColorspace(SDL_Surface* surface); 275 276 /** 277 Create a palette and associate it with a surface. 278 279 This function creates a palette compatible with the provided surface. The 280 palette is then returned for you to modify, and the surface will 281 automatically use the new palette in future operations. You do not need to 282 destroy the returned palette, it will be freed when the reference count 283 reaches 0, usually when the surface is destroyed. 284 285 Bitmap surfaces (with format SDL_PIXELFORMAT_INDEX1LSB or 286 SDL_PIXELFORMAT_INDEX1MSB) will have the palette initialized with 0 as 287 white and 1 as black. Other surfaces will get a palette initialized with 288 white in every entry. 289 290 If this function is called for a surface that already has a palette, a new 291 palette will be created to replace it. 292 293 Params: 294 surface the SDL_Surface structure to update. 295 296 Returns: 297 a new SDL_Palette structure on success or NULL on failure (e.g. if 298 the surface didn't have an index format); call SDL_GetError() for 299 more information. 300 301 See_Also: 302 $(D SDL_SetPaletteColors) 303 */ 304 extern SDL_Palette* SDL_CreateSurfacePalette(SDL_Surface* surface); 305 306 /** 307 Set the palette used by a surface. 308 309 A single palette can be shared with many surfaces. 310 311 Params: 312 surface = the SDL_Surface structure to update. 313 palette = the SDL_Palette structure to use. 314 315 Returns: 316 true on success or false on failure; call SDL_GetError() for more 317 information. 318 319 See_Also: 320 $(D SDL_CreatePalette) 321 $(D SDL_GetSurfacePalette) 322 */ 323 extern bool SDL_SetSurfacePalette(SDL_Surface* surface, SDL_Palette* palette); 324 325 /** 326 Get the palette used by a surface. 327 328 Params: 329 surface = the SDL_Surface structure to query. 330 331 Returns: 332 a pointer to the palette used by the surface, or NULL if there is 333 no palette used. 334 335 See_Also: 336 $(D SDL_SetSurfacePalette) 337 */ 338 extern SDL_Palette* SDL_GetSurfacePalette(SDL_Surface* surface); 339 340 /** 341 Add an alternate version of a surface. 342 343 This function adds an alternate version of this surface, usually used for 344 content with high DPI representations like cursors or icons. The size, 345 format, and content do not need to match the original surface, and these 346 alternate versions will not be updated when the original surface changes. 347 348 This function adds a reference to the alternate version, so you should call 349 SDL_DestroySurface() on the image after this call. 350 351 Params: 352 surface = the SDL_Surface structure to update. 353 image = a pointer to an alternate SDL_Surface to associate with this 354 surface. 355 356 Returns: 357 true on success or false on failure; call SDL_GetError() for more 358 information. 359 360 See_Also: 361 $(D SDL_RemoveSurfaceAlternateImages) 362 $(D SDL_GetSurfaceImages) 363 $(D SDL_SurfaceHasAlternateImages) 364 */ 365 extern bool SDL_AddSurfaceAlternateImage(SDL_Surface* surface, SDL_Surface* image); 366 367 /** 368 Return whether a surface has alternate versions available. 369 370 Params: 371 surface = the SDL_Surface structure to query. 372 373 Returns: 374 true if alternate versions are available or false otherwise. 375 376 See_Also: 377 $(D SDL_AddSurfaceAlternateImage) 378 $(D SDL_RemoveSurfaceAlternateImages) 379 $(D SDL_GetSurfaceImages) 380 */ 381 extern bool SDL_SurfaceHasAlternateImages(SDL_Surface* surface); 382 383 /** 384 Get an array including all versions of a surface. 385 386 This returns all versions of a surface, with the surface being queried as 387 the first element in the returned array. 388 389 Freeing the array of surfaces does not affect the surfaces in the array. 390 They are still referenced by the surface being queried and will be cleaned 391 up normally. 392 393 Params: 394 surface = the SDL_Surface structure to query. 395 count = a pointer filled in with the number of surface pointers 396 returned, may be NULL. 397 398 Returns: 399 a NULL terminated array of SDL_Surface pointers or NULL on 400 failure; call SDL_GetError() for more information. This should be 401 freed with SDL_free() when it is no longer needed. 402 403 See_Also: 404 $(D SDL_AddSurfaceAlternateImage) 405 $(D SDL_RemoveSurfaceAlternateImages) 406 $(D SDL_SurfaceHasAlternateImages) 407 */ 408 extern SDL_Surface* * SDL_GetSurfaceImages(SDL_Surface* surface, int* count); 409 410 /** 411 Remove all alternate versions of a surface. 412 413 This function removes a reference from all the alternative versions, 414 destroying them if this is the last reference to them. 415 416 Params: 417 surface = the SDL_Surface structure to update. 418 419 See_Also: 420 $(D SDL_AddSurfaceAlternateImage) 421 $(D SDL_GetSurfaceImages) 422 $(D SDL_SurfaceHasAlternateImages) 423 */ 424 extern void SDL_RemoveSurfaceAlternateImages(SDL_Surface* surface); 425 426 /** 427 Set up a surface for directly accessing the pixels. 428 429 Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to 430 and read from `surface->pixels`, using the pixel format stored in 431 `surface->format`. Once you are done accessing the surface, you should use 432 SDL_UnlockSurface() to release it. 433 434 Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to 435 0, then you can read and write to the surface at any time, and the pixel 436 format of the surface will not change. 437 438 Params: 439 surface = the SDL_Surface structure to be locked. 440 441 Returns: 442 true on success or false on failure; call SDL_GetError() for more 443 information. 444 445 See_Also: 446 $(D SDL_MUSTLOCK) 447 $(D SDL_UnlockSurface) 448 */ 449 extern bool SDL_LockSurface(SDL_Surface* surface); 450 451 /** 452 Release a surface after directly accessing the pixels. 453 454 Params: 455 surface = the SDL_Surface structure to be unlocked. 456 457 See_Also: 458 $(D SDL_LockSurface) 459 */ 460 extern void SDL_UnlockSurface(SDL_Surface* surface); 461 462 /** 463 Load a BMP image from a seekable SDL data stream. 464 465 The new surface should be freed with SDL_DestroySurface(). Not doing so 466 will result in a memory leak. 467 468 Params: 469 src = the data stream for the surface. 470 closeio = if true, calls SDL_CloseIO() on `src` before returning, even 471 in the case of an error. 472 473 Returns: 474 a pointer to a new SDL_Surface structure or NULL on failure; call 475 SDL_GetError() for more information. 476 477 See_Also: 478 $(D SDL_DestroySurface) 479 $(D SDL_LoadBMP) 480 $(D SDL_SaveBMP_IO) 481 */ 482 extern SDL_Surface* SDL_LoadBMP_IO(SDL_IOStream* src, bool closeio); 483 484 /** 485 Load a BMP image from a file. 486 487 The new surface should be freed with SDL_DestroySurface(). Not doing so 488 will result in a memory leak. 489 490 Params: 491 file = the BMP file to load. 492 493 Returns: 494 a pointer to a new SDL_Surface structure or NULL on failure; call 495 SDL_GetError() for more information. 496 497 See_Also: 498 $(D SDL_DestroySurface) 499 $(D SDL_LoadBMP_IO) 500 $(D SDL_SaveBMP) 501 */ 502 extern SDL_Surface* SDL_LoadBMP(const(char)* file); 503 504 /** 505 Save a surface to a seekable SDL data stream in BMP format. 506 507 Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the 508 BMP directly. Other RGB formats with 8-bit or higher get converted to a 509 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit 510 surface before they are saved. YUV and paletted 1-bit and 4-bit formats are 511 not supported. 512 513 Params: 514 surface = the SDL_Surface structure containing the image to be saved. 515 dst = a data stream to save to. 516 closeio = if true, calls SDL_CloseIO() on `dst` before returning, even 517 in the case of an error. 518 519 Returns: 520 true on success or false on failure; call SDL_GetError() for more 521 information. 522 523 See_Also: 524 $(D SDL_LoadBMP_IO) 525 $(D SDL_SaveBMP) 526 */ 527 extern bool SDL_SaveBMP_IO(SDL_Surface* surface, SDL_IOStream* dst, bool closeio); 528 529 /** 530 Save a surface to a file. 531 532 Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the 533 BMP directly. Other RGB formats with 8-bit or higher get converted to a 534 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit 535 surface before they are saved. YUV and paletted 1-bit and 4-bit formats are 536 not supported. 537 538 Params: 539 surface = the SDL_Surface structure containing the image to be saved. 540 file = a file to save to. 541 542 Returns: 543 true on success or false on failure; call SDL_GetError() for more 544 information. 545 546 See_Also: 547 $(D SDL_LoadBMP) 548 $(D SDL_SaveBMP_IO) 549 */ 550 extern bool SDL_SaveBMP(SDL_Surface* surface, const(char)* file); 551 552 /** 553 Set the RLE acceleration hint for a surface. 554 555 If RLE is enabled, color key and alpha blending blits are much faster, but 556 the surface must be locked before directly accessing the pixels. 557 558 Params: 559 surface = the SDL_Surface structure to optimize. 560 enabled = true to enable RLE acceleration, false to disable it. 561 562 Returns: 563 true on success or false on failure; call SDL_GetError() for more 564 information. 565 566 See_Also: 567 $(D SDL_BlitSurface) 568 $(D SDL_LockSurface) 569 $(D SDL_UnlockSurface) 570 */ 571 extern bool SDL_SetSurfaceRLE(SDL_Surface* surface, bool enabled); 572 573 /** 574 Returns whether the surface is RLE enabled. 575 576 It is safe to pass a NULL `surface` here; it will return false. 577 578 Params: 579 surface = the SDL_Surface structure to query. 580 581 Returns: 582 true if the surface is RLE enabled, false otherwise. 583 584 See_Also: 585 $(D SDL_SetSurfaceRLE) 586 */ 587 extern bool SDL_SurfaceHasRLE(SDL_Surface* surface); 588 589 /** 590 Set the color key (transparent pixel) in a surface. 591 592 The color key defines a pixel value that will be treated as transparent in 593 a blit. For example, one can use this to specify that cyan pixels should be 594 considered transparent, and therefore not rendered. 595 596 It is a pixel of the format used by the surface, as generated by 597 SDL_MapRGB(). 598 599 Params: 600 surface = the SDL_Surface structure to update. 601 enabled = true to enable color key, false to disable color key. 602 key = the transparent pixel. 603 604 Returns: 605 true on success or false on failure; call SDL_GetError() for more 606 information. 607 608 See_Also: 609 $(D SDL_GetSurfaceColorKey) 610 $(D SDL_SetSurfaceRLE) 611 $(D SDL_SurfaceHasColorKey) 612 */ 613 extern bool SDL_SetSurfaceColorKey(SDL_Surface* surface, bool enabled, Uint32 key); 614 615 /** 616 Returns whether the surface has a color key. 617 618 It is safe to pass a NULL `surface` here; it will return false. 619 620 Params: 621 surface = the SDL_Surface structure to query. 622 623 Returns: 624 true if the surface has a color key, false otherwise. 625 626 See_Also: 627 $(D SDL_SetSurfaceColorKey) 628 $(D SDL_GetSurfaceColorKey) 629 */ 630 extern bool SDL_SurfaceHasColorKey(SDL_Surface* surface); 631 632 /** 633 Get the color key (transparent pixel) for a surface. 634 635 The color key is a pixel of the format used by the surface, as generated by 636 SDL_MapRGB(). 637 638 If the surface doesn't have color key enabled this function returns false. 639 640 Params: 641 surface = the SDL_Surface structure to query. 642 key = a pointer filled in with the transparent pixel. 643 644 Returns: 645 true on success or false on failure; call SDL_GetError() for more 646 information. 647 648 See_Also: 649 $(D SDL_SetSurfaceColorKey) 650 $(D SDL_SurfaceHasColorKey) 651 */ 652 extern bool SDL_GetSurfaceColorKey(SDL_Surface* surface, Uint32* key); 653 654 /** 655 Set an additional color value multiplied into blit operations. 656 657 When this surface is blitted, during the blit operation each source color 658 channel is modulated by the appropriate color value according to the 659 following formula: 660 661 `srcC = srcC* (color / 255)` 662 663 Params: 664 surface = the SDL_Surface structure to update. 665 r = the red color value multiplied into blit operations. 666 g = the green color value multiplied into blit operations. 667 b = the blue color value multiplied into blit operations. 668 669 Returns: 670 true on success or false on failure; call SDL_GetError() for more 671 information. 672 673 See_Also: 674 $(D SDL_GetSurfaceColorMod) 675 $(D SDL_SetSurfaceAlphaMod) 676 */ 677 extern bool SDL_SetSurfaceColorMod(SDL_Surface* surface, Uint8 r, Uint8 g, Uint8 b); 678 679 680 /** 681 Get the additional color value multiplied into blit operations. 682 683 Params: 684 surface = the SDL_Surface structure to query. 685 r = a pointer filled in with the current red color value. 686 g = a pointer filled in with the current green color value. 687 b = a pointer filled in with the current blue color value. 688 689 Returns: 690 true on success or false on failure; call SDL_GetError() for more 691 information. 692 693 See_Also: 694 $(D SDL_GetSurfaceAlphaMod) 695 $(D SDL_SetSurfaceColorMod) 696 */ 697 extern bool SDL_GetSurfaceColorMod(SDL_Surface* surface, Uint8* r, Uint8* g, Uint8* b); 698 699 /** 700 Set an additional alpha value used in blit operations. 701 702 When this surface is blitted, during the blit operation the source alpha 703 value is modulated by this alpha value according to the following formula: 704 705 `srcA = srcA* (alpha / 255)` 706 707 Params: 708 surface = the SDL_Surface structure to update. 709 alpha = the alpha value multiplied into blit operations. 710 711 Returns: 712 true on success or false on failure; call SDL_GetError() for more 713 information. 714 715 See_Also: 716 $(D SDL_GetSurfaceAlphaMod) 717 $(D SDL_SetSurfaceColorMod) 718 */ 719 extern bool SDL_SetSurfaceAlphaMod(SDL_Surface* surface, Uint8 alpha); 720 721 /** 722 Get the additional alpha value used in blit operations. 723 724 Params: 725 surface = the SDL_Surface structure to query. 726 alpha = a pointer filled in with the current alpha value. 727 728 Returns: 729 true on success or false on failure; call SDL_GetError() for more 730 information. 731 732 See_Also: 733 $(D SDL_GetSurfaceColorMod) 734 $(D SDL_SetSurfaceAlphaMod) 735 */ 736 extern bool SDL_GetSurfaceAlphaMod(SDL_Surface* surface, Uint8* alpha); 737 738 /** 739 Set the blend mode used for blit operations. 740 741 To copy a surface to another surface (or texture) without blending with the 742 existing data, the blendmode of the SOURCE surface should be set to 743 `SDL_BLENDMODE_NONE`. 744 745 Params: 746 surface = the SDL_Surface structure to update. 747 blendMode = the SDL_BlendMode to use for blit blending. 748 749 Returns: 750 true on success or false on failure; call SDL_GetError() for more 751 information. 752 753 See_Also: 754 $(D SDL_GetSurfaceBlendMode) 755 */ 756 extern bool SDL_SetSurfaceBlendMode(SDL_Surface* surface, SDL_BlendMode blendMode); 757 758 /** 759 Get the blend mode used for blit operations. 760 761 Params: 762 surface = the SDL_Surface structure to query. 763 blendMode = a pointer filled in with the current SDL_BlendMode. 764 765 Returns: 766 true on success or false on failure; call SDL_GetError() for more 767 information. 768 769 See_Also: 770 $(D SDL_SetSurfaceBlendMode) 771 */ 772 extern bool SDL_GetSurfaceBlendMode(SDL_Surface* surface, SDL_BlendMode* blendMode); 773 774 /** 775 Set the clipping rectangle for a surface. 776 777 When `surface` is the destination of a blit, only the area within the clip 778 rectangle is drawn into. 779 780 Note that blits are automatically clipped to the edges of the source and 781 destination surfaces. 782 783 Params: 784 surface = the SDL_Surface structure to be clipped. 785 rect = the SDL_Rect structure representing the clipping rectangle, or 786 NULL to disable clipping. 787 788 Returns: 789 true if the rectangle intersects the surface, otherwise false and 790 blits will be completely clipped. 791 792 See_Also: 793 $(D SDL_GetSurfaceClipRect) 794 */ 795 extern bool SDL_SetSurfaceClipRect(SDL_Surface* surface, const(SDL_Rect)* rect); 796 797 /** 798 Get the clipping rectangle for a surface. 799 800 When `surface` is the destination of a blit, only the area within the clip 801 rectangle is drawn into. 802 803 Params: 804 surface = the SDL_Surface structure representing the surface to be 805 clipped. 806 rect = an SDL_Rect structure filled in with the clipping rectangle for 807 the surface. 808 809 Returns: 810 true on success or false on failure; call SDL_GetError() for more 811 information. 812 813 See_Also: 814 $(D SDL_SetSurfaceClipRect) 815 */ 816 extern bool SDL_GetSurfaceClipRect(SDL_Surface* surface, SDL_Rect* rect); 817 818 /** 819 Flip a surface vertically or horizontally. 820 821 Params: 822 surface = the surface to flip. 823 flip = the direction to flip. 824 825 Returns: 826 true on success or false on failure; call SDL_GetError() for more 827 information. 828 */ 829 extern bool SDL_FlipSurface(SDL_Surface* surface, SDL_FlipMode flip); 830 831 /** 832 Creates a new surface identical to the existing surface. 833 834 If the original surface has alternate images, the new surface will have a 835 reference to them as well. 836 837 The returned surface should be freed with SDL_DestroySurface(). 838 839 Params: 840 surface = the surface to duplicate. 841 842 Returns: 843 a copy of the surface or NULL on failure; call SDL_GetError() for 844 more information. 845 846 See_Also: 847 $(D SDL_DestroySurface) 848 */ 849 extern SDL_Surface* SDL_DuplicateSurface(SDL_Surface* surface); 850 851 /** 852 Creates a new surface identical to the existing surface, scaled to the 853 desired size. 854 855 The returned surface should be freed with SDL_DestroySurface(). 856 857 Params: 858 surface = the surface to duplicate and scale. 859 width = the width of the new surface. 860 height = the height of the new surface. 861 scaleMode = the SDL_ScaleMode to be used. 862 863 Returns: 864 a copy of the surface or NULL on failure; call SDL_GetError() for 865 more information. 866 867 See_Also: 868 $(D SDL_DestroySurface) 869 */ 870 extern SDL_Surface* SDL_ScaleSurface(SDL_Surface* surface, int width, int height, SDL_ScaleMode scaleMode); 871 872 /** 873 Copy an existing surface to a new surface of the specified format. 874 875 This function is used to optimize images for faster* repeat* blitting. This 876 is accomplished by converting the original and storing the result as a new 877 surface. The new, optimized surface can then be used as the source for 878 future blits, making them faster. 879 880 If you are converting to an indexed surface and want to map colors to a 881 palette, you can use SDL_ConvertSurfaceAndColorspace() instead. 882 883 If the original surface has alternate images, the new surface will have a 884 reference to them as well. 885 886 Params: 887 surface = the existing SDL_Surface structure to convert. 888 format = the new pixel format. 889 890 Returns: 891 the new SDL_Surface structure that is created or NULL on failure; 892 call SDL_GetError() for more information. 893 894 See_Also: 895 $(D SDL_ConvertSurfaceAndColorspace) 896 $(D SDL_DestroySurface) 897 */ 898 extern SDL_Surface* SDL_ConvertSurface(SDL_Surface* surface, SDL_PixelFormat format); 899 900 /** 901 Copy an existing surface to a new surface of the specified format and 902 colorspace. 903 904 This function converts an existing surface to a new format and colorspace 905 and returns the new surface. This will perform any pixel format and 906 colorspace conversion needed. 907 908 If the original surface has alternate images, the new surface will have a 909 reference to them as well. 910 911 Params: 912 surface = the existing SDL_Surface structure to convert. 913 format = the new pixel format. 914 palette = an optional palette to use for indexed formats, may be NULL. 915 colorspace = the new colorspace. 916 props = an SDL_PropertiesID with additional color properties, or 0. 917 918 Returns: 919 the new SDL_Surface structure that is created or NULL on failure; 920 call SDL_GetError() for more information. 921 922 See_Also: 923 $(D SDL_ConvertSurface) 924 $(D SDL_DestroySurface) 925 */ 926 extern SDL_Surface* SDL_ConvertSurfaceAndColorspace(SDL_Surface* surface, SDL_PixelFormat format, SDL_Palette* palette, SDL_Colorspace colorspace, SDL_PropertiesID props); 927 928 /** 929 Copy a block of pixels of one format to another format. 930 931 Params: 932 width = the width of the block to copy, in pixels. 933 height = the height of the block to copy, in pixels. 934 src_format = an SDL_PixelFormat value of the `src` pixels format. 935 src = a pointer to the source pixels. 936 src_pitch = the pitch of the source pixels, in bytes. 937 dst_format = an SDL_PixelFormat value of the `dst` pixels format. 938 dst = a pointer to be filled in with new pixel data. 939 dst_pitch = the pitch of the destination pixels, in bytes. 940 941 Returns: 942 true on success or false on failure; call SDL_GetError() for more 943 information. 944 945 See_Also: 946 $(D SDL_ConvertPixelsAndColorspace) 947 */ 948 extern bool SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const(void)* src, int src_pitch, SDL_PixelFormat dst_format, void* dst, int dst_pitch); 949 950 /** 951 Copy a block of pixels of one format and colorspace to another format and 952 colorspace. 953 954 width = the width of the block to copy, in pixels. 955 height = the height of the block to copy, in pixels. 956 src_format = an SDL_PixelFormat value of the `src` pixels format. 957 src_colorspace = an SDL_Colorspace value describing the colorspace of 958 the `src` pixels. 959 src_properties = an SDL_PropertiesID with additional source color 960 properties, or 0. 961 src = a pointer to the source pixels. 962 src_pitch = the pitch of the source pixels, in bytes. 963 dst_format = an SDL_PixelFormat value of the `dst` pixels format. 964 dst_colorspace = an SDL_Colorspace value describing the colorspace of 965 the `dst` pixels. 966 dst_properties = an SDL_PropertiesID with additional destination color 967 properties, or 0. 968 dst = a pointer to be filled in with new pixel data. 969 dst_pitch = the pitch of the destination pixels, in bytes. 970 971 Returns: 972 true on success or false on failure; call SDL_GetError() for more 973 information. 974 975 See_Also: 976 $(D SDL_ConvertPixels) 977 */ 978 extern bool SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const(void)* src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void* dst, int dst_pitch); 979 980 /** 981 Premultiply the alpha on a block of pixels. 982 983 This is safe to use with src == dst, but not for other overlapping areas. 984 985 Params: 986 width = the width of the block to convert, in pixels. 987 height = the height of the block to convert, in pixels. 988 src_format = an SDL_PixelFormat value of the `src` pixels format. 989 src = a pointer to the source pixels. 990 src_pitch = the pitch of the source pixels, in bytes. 991 dst_format = an SDL_PixelFormat value of the `dst` pixels format. 992 dst = a pointer to be filled in with premultiplied pixel data. 993 dst_pitch = the pitch of the destination pixels, in bytes. 994 linear = true to convert from sRGB to linear space for the alpha 995 multiplication, false to do multiplication in sRGB space. 996 997 Returns: 998 true on success or false on failure; call SDL_GetError() for more 999 information. 1000 */ 1001 extern bool SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const(void)* src, int src_pitch, SDL_PixelFormat dst_format, void* dst, int dst_pitch, bool linear); 1002 1003 /** 1004 Premultiply the alpha in a surface. 1005 1006 This is safe to use with src == dst, but not for other overlapping areas. 1007 1008 Params: 1009 surface = the surface to modify. 1010 linear = true to convert from sRGB to linear space for the alpha 1011 multiplication, false to do multiplication in sRGB space. 1012 1013 Returns: 1014 true on success or false on failure; call SDL_GetError() for more 1015 information. 1016 */ 1017 extern bool SDL_PremultiplySurfaceAlpha(SDL_Surface* surface, bool linear); 1018 1019 /** 1020 Clear a surface with a specific color, with floating point precision. 1021 1022 This function handles all surface formats, and ignores any clip rectangle. 1023 1024 If the surface is YUV, the color is assumed to be in the sRGB colorspace, 1025 otherwise the color is assumed to be in the colorspace of the suface. 1026 1027 surface = the SDL_Surface to clear. 1028 r = the red component of the pixel, normally in the range 0-1. 1029 g = the green component of the pixel, normally in the range 0-1. 1030 b = the blue component of the pixel, normally in the range 0-1. 1031 a = the alpha component of the pixel, normally in the range 0-1. 1032 1033 Returns: 1034 true on success or false on failure; call SDL_GetError() for more 1035 information. 1036 */ 1037 extern bool SDL_ClearSurface(SDL_Surface* surface, float r, float g, float b, float a); 1038 1039 /** 1040 Perform a fast fill of a rectangle with a specific color. 1041 1042 `color` should be a pixel of the format used by the surface, and can be 1043 generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an 1044 alpha component then the destination is simply filled with that alpha 1045 information, no blending takes place. 1046 1047 If there is a clip rectangle set on the destination (set via 1048 SDL_SetSurfaceClipRect()), then this function will fill based on the 1049 intersection of the clip rectangle and `rect`. 1050 1051 Params: 1052 dst = the SDL_Surface structure that is the drawing target. 1053 rect = the SDL_Rect structure representing the rectangle to fill, or 1054 NULL to fill the entire surface. 1055 color = the color to fill with. 1056 1057 Returns: 1058 true on success or false on failure; call SDL_GetError() for more 1059 information. 1060 1061 See_Also: 1062 $(D SDL_FillSurfaceRects) 1063 */ 1064 extern bool SDL_FillSurfaceRect(SDL_Surface* dst, const(SDL_Rect)* rect, Uint32 color); 1065 1066 /** 1067 Perform a fast fill of a set of rectangles with a specific color. 1068 1069 `color` should be a pixel of the format used by the surface, and can be 1070 generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an 1071 alpha component then the destination is simply filled with that alpha 1072 information, no blending takes place. 1073 1074 If there is a clip rectangle set on the destination (set via 1075 SDL_SetSurfaceClipRect()), then this function will fill based on the 1076 intersection of the clip rectangle and `rect`. 1077 1078 Params: 1079 dst = the SDL_Surface structure that is the drawing target. 1080 rects = an array of SDL_Rects representing the rectangles to fill. 1081 count = the number of rectangles in the array. 1082 color = the color to fill with. 1083 1084 Returns: 1085 true on success or false on failure; call SDL_GetError() for more 1086 information. 1087 1088 See_Also: 1089 $(D SDL_FillSurfaceRect) 1090 */ 1091 extern bool SDL_FillSurfaceRects(SDL_Surface* dst, const(SDL_Rect)* rects, int count, Uint32 color); 1092 1093 /** 1094 Performs a fast blit from the source surface to the destination surface 1095 with clipping. 1096 1097 If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or 1098 `dst`) is copied while ensuring clipping to `dst->clip_rect`. 1099 1100 The final blit rectangles are saved in `srcrect` and `dstrect` after all 1101 clipping is performed. 1102 1103 The blit function should not be called on a locked surface. 1104 1105 The blit semantics for surfaces with and without blending and colorkey are 1106 defined as follows: 1107 1108 ``` 1109 RGBA->RGB: 1110 Source surface blend mode set to SDL_BLENDMODE_BLEND: 1111 alpha-blend (using the source alpha-channel and per-surface alpha) 1112 SDL_SRCCOLORKEY ignored. 1113 Source surface blend mode set to SDL_BLENDMODE_NONE: 1114 copy RGB. 1115 if SDL_SRCCOLORKEY set, only copy the pixels that do not match the 1116 RGB values of the source color key, ignoring alpha in the 1117 comparison. 1118 1119 RGB->RGBA: 1120 Source surface blend mode set to SDL_BLENDMODE_BLEND: 1121 alpha-blend (using the source per-surface alpha) 1122 Source surface blend mode set to SDL_BLENDMODE_NONE: 1123 copy RGB, set destination alpha to source per-surface alpha value. 1124 both: 1125 if SDL_SRCCOLORKEY set, only copy the pixels that do not match the 1126 source color key. 1127 1128 RGBA->RGBA: 1129 Source surface blend mode set to SDL_BLENDMODE_BLEND: 1130 alpha-blend (using the source alpha-channel and per-surface alpha) 1131 SDL_SRCCOLORKEY ignored. 1132 Source surface blend mode set to SDL_BLENDMODE_NONE: 1133 copy all of RGBA to the destination. 1134 if SDL_SRCCOLORKEY set, only copy the pixels that do not match the 1135 RGB values of the source color key, ignoring alpha in the 1136 comparison. 1137 1138 RGB->RGB: 1139 Source surface blend mode set to SDL_BLENDMODE_BLEND: 1140 alpha-blend (using the source per-surface alpha) 1141 Source surface blend mode set to SDL_BLENDMODE_NONE: 1142 copy RGB. 1143 both: 1144 if SDL_SRCCOLORKEY set, only copy the pixels that do not match the 1145 source color key. 1146 ``` 1147 1148 Params: 1149 src = the SDL_Surface structure to be copied from. 1150 srcrect = the SDL_Rect structure representing the rectangle to be 1151 copied, or NULL to copy the entire surface. 1152 dst = the SDL_Surface structure that is the blit target. 1153 dstrect = the SDL_Rect structure representing the x and y position in 1154 the destination surface, or NULL for (0,0). The width and 1155 height are ignored, and are copied from `srcrect`. If you 1156 want a specific width and height, you should use 1157 SDL_BlitSurfaceScaled(). 1158 1159 Returns: 1160 true on success or false on failure; call SDL_GetError() for more 1161 information. 1162 1163 Threadsafety: 1164 The same destination surface should not be used from two 1165 threads at once. It is safe to use the same source surface 1166 from multiple threads. 1167 1168 See_Also: 1169 $(D SDL_BlitSurfaceScaled) 1170 */ 1171 extern bool SDL_BlitSurface(SDL_Surface* src, const(SDL_Rect)* srcrect, SDL_Surface* dst, const(SDL_Rect)* dstrect); 1172 1173 /** 1174 Perform low-level surface blitting only. 1175 1176 This is a semi-private blit function and it performs low-level surface 1177 blitting, assuming the input rectangles have already been clipped. 1178 1179 Params: 1180 src = the SDL_Surface structure to be copied from. 1181 srcrect = the SDL_Rect structure representing the rectangle to be 1182 copied, may not be NULL. 1183 dst = the SDL_Surface structure that is the blit target. 1184 dstrect = the SDL_Rect structure representing the target rectangle in 1185 the destination surface, may not be NULL. 1186 1187 Returns: 1188 true on success or false on failure; call SDL_GetError() for more 1189 information. 1190 1191 Threadsafety: 1192 The same destination surface should not be used from two 1193 threads at once. It is safe to use the same source surface 1194 from multiple threads. 1195 1196 See_Also: 1197 $(D SDL_BlitSurface) 1198 */ 1199 extern bool SDL_BlitSurfaceUnchecked(SDL_Surface* src, const(SDL_Rect)* srcrect, SDL_Surface* dst, const(SDL_Rect)* dstrect); 1200 1201 /** 1202 Perform a scaled blit to a destination surface, which may be of a different 1203 format. 1204 1205 Params: 1206 src = the SDL_Surface structure to be copied from. 1207 srcrect = the SDL_Rect structure representing the rectangle to be 1208 copied, or NULL to copy the entire surface. 1209 dst = the SDL_Surface structure that is the blit target. 1210 dstrect = the SDL_Rect structure representing the target rectangle in 1211 the destination surface, or NULL to fill the entire 1212 destination surface. 1213 scaleMode = the SDL_ScaleMode to be used. 1214 1215 Returns: 1216 true on success or false on failure; call SDL_GetError() for more 1217 information. 1218 1219 Threadsafety: 1220 The same destination surface should not be used from two 1221 threads at once. It is safe to use the same source surface 1222 from multiple threads. 1223 1224 See_Also: 1225 $(D SDL_BlitSurface) 1226 */ 1227 extern bool SDL_BlitSurfaceScaled(SDL_Surface* src, const(SDL_Rect)* srcrect, SDL_Surface* dst, const(SDL_Rect)* dstrect, SDL_ScaleMode scaleMode); 1228 1229 /** 1230 Perform low-level surface scaled blitting only. 1231 1232 This is a semi-private function and it performs low-level surface blitting, 1233 assuming the input rectangles have already been clipped. 1234 1235 Params: 1236 src = the SDL_Surface structure to be copied from. 1237 srcrect = the SDL_Rect structure representing the rectangle to be 1238 copied, may not be NULL. 1239 dst = the SDL_Surface structure that is the blit target. 1240 dstrect = the SDL_Rect structure representing the target rectangle in 1241 the destination surface, may not be NULL. 1242 scaleMode = the SDL_ScaleMode to be used. 1243 1244 Returns: 1245 true on success or false on failure; call SDL_GetError() for more 1246 information. 1247 1248 Threadsafety: 1249 The same destination surface should not be used from two 1250 threads at once. It is safe to use the same source surface 1251 from multiple threads. 1252 1253 See_Also: 1254 $(D SDL_BlitSurfaceScaled) 1255 */ 1256 extern bool SDL_BlitSurfaceUncheckedScaled(SDL_Surface* src, const(SDL_Rect)* srcrect, SDL_Surface* dst, const(SDL_Rect)* dstrect, SDL_ScaleMode scaleMode); 1257 1258 /** 1259 Perform a tiled blit to a destination surface, which may be of a different 1260 format. 1261 1262 The pixels in `srcrect` will be repeated as many times as needed to 1263 completely fill `dstrect`. 1264 1265 Params: 1266 src = the SDL_Surface structure to be copied from. 1267 srcrect = the SDL_Rect structure representing the rectangle to be 1268 copied, or NULL to copy the entire surface. 1269 dst = the SDL_Surface structure that is the blit target. 1270 dstrect = the SDL_Rect structure representing the target rectangle in 1271 the destination surface, or NULL to fill the entire surface. 1272 1273 Returns: 1274 true on success or false on failure; call SDL_GetError() for more 1275 information. 1276 1277 Threadsafety: 1278 The same destination surface should not be used from two 1279 threads at once. It is safe to use the same source surface 1280 from multiple threads. 1281 1282 See_Also: 1283 $(D SDL_BlitSurface) 1284 */ 1285 extern bool SDL_BlitSurfaceTiled(SDL_Surface* src, const(SDL_Rect)* srcrect, SDL_Surface* dst, const(SDL_Rect)* dstrect); 1286 1287 /** 1288 Perform a scaled and tiled blit to a destination surface, which may be of a 1289 different format. 1290 1291 The pixels in `srcrect` will be scaled and repeated as many times as needed 1292 to completely fill `dstrect`. 1293 1294 Params: 1295 src = the SDL_Surface structure to be copied from. 1296 srcrect = the SDL_Rect structure representing the rectangle to be 1297 copied, or NULL to copy the entire surface. 1298 scale = the scale used to transform srcrect into the destination 1299 rectangle, e.g. a 32x32 texture with a scale of 2 would fill 1300 64x64 tiles. 1301 scaleMode = scale algorithm to be used. 1302 dst = the SDL_Surface structure that is the blit target. 1303 dstrect = the SDL_Rect structure representing the target rectangle in 1304 the destination surface, or NULL to fill the entire surface. 1305 1306 Returns: 1307 true on success or false on failure; call SDL_GetError() for more 1308 information. 1309 1310 Threadsafety: 1311 The same destination surface should not be used from two 1312 threads at once. It is safe to use the same source surface 1313 from multiple threads. 1314 1315 See_Also: 1316 $(D SDL_BlitSurface) 1317 */ 1318 extern bool SDL_BlitSurfaceTiledWithScale(SDL_Surface* src, const(SDL_Rect)* srcrect, float scale, SDL_ScaleMode scaleMode, SDL_Surface* dst, const(SDL_Rect)* dstrect); 1319 1320 /** 1321 Perform a scaled blit using the 9-grid algorithm to a destination surface, 1322 which may be of a different format. 1323 1324 The pixels in the source surface are split into a 3x3 grid, using the 1325 different corner sizes for each corner, and the sides and center making up 1326 the remaining pixels. The corners are then scaled using `scale` and fit 1327 into the corners of the destination rectangle. The sides and center are 1328 then stretched into place to cover the remaining destination rectangle. 1329 1330 Params: 1331 src = the SDL_Surface structure to be copied from. 1332 srcrect = the SDL_Rect structure representing the rectangle to be used 1333 for the 9-grid, or NULL to use the entire surface. 1334 left_width = the width, in pixels, of the left corners in `srcrect`. 1335 right_width = the width, in pixels, of the right corners in `srcrect`. 1336 top_height = the height, in pixels, of the top corners in `srcrect`. 1337 bottom_height = the height, in pixels, of the bottom corners in 1338 `srcrect`. 1339 scale = the scale used to transform the corner of `srcrect` into the 1340 corner of `dstrect`, or 0.0f for an unscaled blit. 1341 scaleMode = scale algorithm to be used. 1342 dst = the SDL_Surface structure that is the blit target. 1343 dstrect = the SDL_Rect structure representing the target rectangle in 1344 the destination surface, or NULL to fill the entire surface. 1345 1346 Returns: 1347 true on success or false on failure; call SDL_GetError() for more 1348 information. 1349 1350 Threadsafety: 1351 The same destination surface should not be used from two 1352 threads at once. It is safe to use the same source surface 1353 from multiple threads. 1354 1355 See_Also: 1356 $(D SDL_BlitSurface) 1357 */ 1358 extern bool SDL_BlitSurface9Grid(SDL_Surface* src, const(SDL_Rect)* srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, SDL_Surface* dst, const(SDL_Rect)* dstrect); 1359 1360 /** 1361 Map an RGB triple to an opaque pixel value for a surface. 1362 1363 This function maps the RGB color value to the specified pixel format and 1364 returns the pixel value best approximating the given RGB color value for 1365 the given pixel format. 1366 1367 If the surface has a palette, the index of the closest matching color in 1368 the palette will be returned. 1369 1370 If the surface pixel format has an alpha component it will be returned as 1371 all 1 bits (fully opaque). 1372 1373 If the pixel format bpp (color depth) is less than 32-bpp then the unused 1374 upper bits of the return value can safely be ignored (e.g., with a 16-bpp 1375 format the return value can be assigned to a Uint16, and similarly a Uint8 1376 for an 8-bpp format). 1377 1378 Params: 1379 surface = the surface to use for the pixel format and palette. 1380 r = the red component of the pixel in the range 0-255. 1381 g = the green component of the pixel in the range 0-255. 1382 b = the blue component of the pixel in the range 0-255. 1383 1384 Returns: 1385 A pixel value. 1386 1387 See_Also: 1388 $(D SDL_MapSurfaceRGBA) 1389 */ 1390 extern Uint32 SDL_MapSurfaceRGB(SDL_Surface* surface, Uint8 r, Uint8 g, Uint8 b); 1391 1392 /** 1393 Map an RGBA quadruple to a pixel value for a surface. 1394 1395 This function maps the RGBA color value to the specified pixel format and 1396 returns the pixel value best approximating the given RGBA color value for 1397 the given pixel format. 1398 1399 If the surface pixel format has no alpha component the alpha value will be 1400 ignored (as it will be in formats with a palette). 1401 1402 If the surface has a palette, the index of the closest matching color in 1403 the palette will be returned. 1404 1405 If the pixel format bpp (color depth) is less than 32-bpp then the unused 1406 upper bits of the return value can safely be ignored (e.g., with a 16-bpp 1407 format the return value can be assigned to a Uint16, and similarly a Uint8 1408 for an 8-bpp format). 1409 1410 Params: 1411 surface = the surface to use for the pixel format and palette. 1412 r = the red component of the pixel in the range 0-255. 1413 g = the green component of the pixel in the range 0-255. 1414 b = the blue component of the pixel in the range 0-255. 1415 a = the alpha component of the pixel in the range 0-255. 1416 1417 Returns: 1418 A pixel value. 1419 1420 See_Also: 1421 $(D SDL_MapSurfaceRGB) 1422 */ 1423 extern Uint32 SDL_MapSurfaceRGBA(SDL_Surface* surface, Uint8 r, Uint8 g, Uint8 b, Uint8 a); 1424 1425 /** 1426 Retrieves a single pixel from a surface. 1427 1428 This function prioritizes correctness over speed: it is suitable for unit 1429 tests, but is not intended for use in a game engine. 1430 1431 Like SDL_GetRGBA, this uses the entire 0..255 range when converting color 1432 components from pixel formats with less than 8 bits per RGB component. 1433 1434 Params: 1435 surface = the surface to read. 1436 x = the horizontal coordinate, 0 <= x < width. 1437 y = the vertical coordinate, 0 <= y < height. 1438 r = a pointer filled in with the red channel, 0-255, or NULL to ignore 1439 this channel. 1440 g = a pointer filled in with the green channel, 0-255, or NULL to 1441 ignore this channel. 1442 b = a pointer filled in with the blue channel, 0-255, or NULL to 1443 ignore this channel. 1444 a = a pointer filled in with the alpha channel, 0-255, or NULL to 1445 ignore this channel. 1446 1447 Returns: 1448 true on success or false on failure; call SDL_GetError() for more 1449 information. 1450 */ 1451 extern bool SDL_ReadSurfacePixel(SDL_Surface* surface, int x, int y, Uint8* r, Uint8* g, Uint8* b, Uint8* a); 1452 1453 /** 1454 Retrieves a single pixel from a surface. 1455 1456 This function prioritizes correctness over speed: it is suitable for unit 1457 tests, but is not intended for use in a game engine. 1458 1459 Params: 1460 surface the surface to read. 1461 x = the horizontal coordinate, 0 <= x < width. 1462 y = the vertical coordinate, 0 <= y < height. 1463 r = a pointer filled in with the red channel, normally in the range 1464 0-1, or NULL to ignore this channel. 1465 g = a pointer filled in with the green channel, normally in the range 1466 0-1, or NULL to ignore this channel. 1467 b = a pointer filled in with the blue channel, normally in the range 1468 0-1, or NULL to ignore this channel. 1469 a = a pointer filled in with the alpha channel, normally in the range 1470 0-1, or NULL to ignore this channel. 1471 1472 Returns: 1473 true on success or false on failure; call SDL_GetError() for more 1474 information. 1475 */ 1476 extern bool SDL_ReadSurfacePixelFloat(SDL_Surface* surface, int x, int y, float* r, float* g, float* b, float* a); 1477 1478 /** 1479 Writes a single pixel to a surface. 1480 1481 This function prioritizes correctness over speed: it is suitable for unit 1482 tests, but is not intended for use in a game engine. 1483 1484 Like SDL_MapRGBA, this uses the entire 0..255 range when converting color 1485 components from pixel formats with less than 8 bits per RGB component. 1486 1487 Params: 1488 surface = the surface to write. 1489 x = the horizontal coordinate, 0 <= x < width. 1490 y = the vertical coordinate, 0 <= y < height. 1491 r = the red channel value, 0-255. 1492 g = the green channel value, 0-255. 1493 b = the blue channel value, 0-255. 1494 a = the alpha channel value, 0-255. 1495 1496 Returns: 1497 true on success or false on failure; call SDL_GetError() for more 1498 information. 1499 */ 1500 extern bool SDL_WriteSurfacePixel(SDL_Surface* surface, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a); 1501 1502 /** 1503 Writes a single pixel to a surface. 1504 1505 This function prioritizes correctness over speed: it is suitable for unit 1506 tests, but is not intended for use in a game engine. 1507 1508 Params: 1509 surface = the surface to write. 1510 x = the horizontal coordinate, 0 <= x < width. 1511 y = the vertical coordinate, 0 <= y < height. 1512 r = the red channel value, normally in the range 0-1. 1513 g = the green channel value, normally in the range 0-1. 1514 b = the blue channel value, normally in the range 0-1. 1515 a = the alpha channel value, normally in the range 0-1. 1516 1517 Returns: 1518 true on success or false on failure; call SDL_GetError() for more 1519 information. 1520 */ 1521 extern bool SDL_WriteSurfacePixelFloat(SDL_Surface* surface, int x, int y, float r, float g, float b, float a);