SDL 3.0
SDL_surface.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
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 * \file SDL_surface.h
24 *
25 * Header file for ::SDL_Surface definition and management functions.
26 */
27
28#ifndef SDL_surface_h_
29#define SDL_surface_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_blendmode.h>
33#include <SDL3/SDL_pixels.h>
34#include <SDL3/SDL_properties.h>
35#include <SDL3/SDL_rect.h>
36#include <SDL3/SDL_rwops.h>
37
38#include <SDL3/SDL_begin_code.h>
39/* Set up for C function definitions, even when using C++ */
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/**
45 * \name Surface flags
46 *
47 * These are the currently supported flags for the ::SDL_Surface.
48 *
49 * \internal
50 * Used internally (read-only).
51 */
52/* @{ */
53#define SDL_SWSURFACE 0 /**< Just here for compatibility */
54#define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */
55#define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */
56#define SDL_DONTFREE 0x00000004 /**< Surface is referenced internally */
57#define SDL_SIMD_ALIGNED 0x00000008 /**< Surface uses aligned memory */
58#define SDL_SURFACE_USES_PROPERTIES 0x00000010 /**< Surface uses properties */
59/* @} *//* Surface flags */
60
61/**
62 * Evaluates to true if the surface needs to be locked before access.
63 */
64#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
65
66typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */
67
68/**
69 * The scaling mode
70 */
71typedef enum
72{
73 SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */
74 SDL_SCALEMODE_LINEAR, /**< linear filtering */
75 SDL_SCALEMODE_BEST /**< anisotropic filtering */
77
78/**
79 * The flip mode
80 */
81typedef enum
82{
83 SDL_FLIP_NONE, /**< Do not flip */
84 SDL_FLIP_HORIZONTAL, /**< flip horizontally */
85 SDL_FLIP_VERTICAL /**< flip vertically */
87
88/**
89 * A collection of pixels used in software blitting.
90 *
91 * Pixels are arranged in memory in rows, with the top row first.
92 * Each row occupies an amount of memory given by the pitch (sometimes
93 * known as the row stride in non-SDL APIs).
94 *
95 * Within each row, pixels are arranged from left to right until the
96 * width is reached.
97 * Each pixel occupies a number of bits appropriate for its format, with
98 * most formats representing each pixel as one or more whole bytes
99 * (in some indexed formats, instead multiple pixels are packed into
100 * each byte), and a byte order given by the format.
101 * After encoding all pixels, any remaining bytes to reach the pitch are
102 * used as padding to reach a desired alignment, and have undefined contents.
103 *
104 * \note This structure should be treated as read-only, except for \c pixels,
105 * which, if not NULL, contains the raw pixel data for the surface.
106 * \sa SDL_CreateSurfaceFrom
107 */
108typedef struct SDL_Surface
109{
110 Uint32 flags; /**< Read-only */
111 SDL_PixelFormat *format; /**< Read-only */
112 int w, h; /**< Read-only */
113 int pitch; /**< Read-only */
114 void *pixels; /**< Read-write */
115
116 void *reserved; /**< Private */
117
118 /** information needed for surfaces requiring locks */
119 int locked; /**< Read-only */
120
121 /** list of BlitMap that hold a reference to this surface */
122 void *list_blitmap; /**< Private */
123
124 /** clipping information */
125 SDL_Rect clip_rect; /**< Read-only */
126
127 /** info for fast blit mapping to other surfaces */
128 SDL_BlitMap *map; /**< Private */
129
130 /** Reference count -- used when freeing surface */
131 int refcount; /**< Read-mostly */
133
134/**
135 * The type of function used for surface blitting functions.
136 */
137typedef int (SDLCALL *SDL_blit) (struct SDL_Surface *src, const SDL_Rect *srcrect,
138 struct SDL_Surface *dst, const SDL_Rect *dstrect);
139
140/**
141 * The formula used for converting between YUV and RGB
142 */
143typedef enum
144{
145 SDL_YUV_CONVERSION_JPEG, /**< Full range JPEG */
146 SDL_YUV_CONVERSION_BT601, /**< BT.601 (the default) */
148 SDL_YUV_CONVERSION_AUTOMATIC /**< BT.601 for SD content, BT.709 for HD content */
150
151/**
152 * Allocate a new RGB surface with a specific pixel format.
153 *
154 * \param width the width of the surface
155 * \param height the height of the surface
156 * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
157 * \returns the new SDL_Surface structure that is created or NULL if it fails;
158 * call SDL_GetError() for more information.
159 *
160 * \since This function is available since SDL 3.0.0.
161 *
162 * \sa SDL_CreateSurfaceFrom
163 * \sa SDL_DestroySurface
164 */
165extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface
166 (int width, int height, Uint32 format);
167
168/**
169 * Allocate a new RGB surface with a specific pixel format and existing pixel
170 * data.
171 *
172 * No copy is made of the pixel data. Pixel data is not managed automatically;
173 * you must free the surface before you free the pixel data.
174 *
175 * Pitch is the offset in bytes from one row of pixels to the next, e.g.
176 * `width*4` for `SDL_PIXELFORMAT_RGBA8888`.
177 *
178 * You may pass NULL for pixels and 0 for pitch to create a surface that you
179 * will fill in with valid values later.
180 *
181 * \param pixels a pointer to existing pixel data
182 * \param width the width of the surface
183 * \param height the height of the surface
184 * \param pitch the pitch of the surface in bytes
185 * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
186 * \returns the new SDL_Surface structure that is created or NULL if it fails;
187 * call SDL_GetError() for more information.
188 *
189 * \since This function is available since SDL 3.0.0.
190 *
191 * \sa SDL_CreateSurface
192 * \sa SDL_DestroySurface
193 */
194extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom
195 (void *pixels, int width, int height, int pitch, Uint32 format);
196
197/**
198 * Free an RGB surface.
199 *
200 * It is safe to pass NULL to this function.
201 *
202 * \param surface the SDL_Surface to free.
203 *
204 * \since This function is available since SDL 3.0.0.
205 *
206 * \sa SDL_CreateSurface
207 * \sa SDL_CreateSurfaceFrom
208 * \sa SDL_LoadBMP
209 * \sa SDL_LoadBMP_RW
210 */
211extern DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface);
212
213/**
214 * Get the properties associated with a surface.
215 *
216 * \param surface the SDL_Surface structure to query
217 * \returns a valid property ID on success or 0 on failure; call
218 * SDL_GetError() for more information.
219 *
220 * \since This function is available since SDL 3.0.0.
221 *
222 * \sa SDL_GetProperty
223 * \sa SDL_SetProperty
224 */
225extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface);
226
227/**
228 * Set the palette used by a surface.
229 *
230 * A single palette can be shared with many surfaces.
231 *
232 * \param surface the SDL_Surface structure to update
233 * \param palette the SDL_Palette structure to use
234 * \returns 0 on success or a negative error code on failure; call
235 * SDL_GetError() for more information.
236 *
237 * \since This function is available since SDL 3.0.0.
238 */
239extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface,
240 SDL_Palette *palette);
241
242/**
243 * Set up a surface for directly accessing the pixels.
244 *
245 * Between calls to SDL_LockSurface() / SDL_UnlockSurface(), you can write to
246 * and read from `surface->pixels`, using the pixel format stored in
247 * `surface->format`. Once you are done accessing the surface, you should use
248 * SDL_UnlockSurface() to release it.
249 *
250 * Not all surfaces require locking. If `SDL_MUSTLOCK(surface)` evaluates to
251 * 0, then you can read and write to the surface at any time, and the pixel
252 * format of the surface will not change.
253 *
254 * \param surface the SDL_Surface structure to be locked
255 * \returns 0 on success or a negative error code on failure; call
256 * SDL_GetError() for more information.
257 *
258 * \since This function is available since SDL 3.0.0.
259 *
260 * \sa SDL_MUSTLOCK
261 * \sa SDL_UnlockSurface
262 */
263extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
264
265/**
266 * Release a surface after directly accessing the pixels.
267 *
268 * \param surface the SDL_Surface structure to be unlocked
269 *
270 * \since This function is available since SDL 3.0.0.
271 *
272 * \sa SDL_LockSurface
273 */
274extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
275
276/**
277 * Load a BMP image from a seekable SDL data stream.
278 *
279 * The new surface should be freed with SDL_DestroySurface(). Not doing so
280 * will result in a memory leak.
281 *
282 * \param src the data stream for the surface
283 * \param freesrc if SDL_TRUE, calls SDL_RWclose() on `src` before returning,
284 * even in the case of an error
285 * \returns a pointer to a new SDL_Surface structure or NULL if there was an
286 * error; call SDL_GetError() for more information.
287 *
288 * \since This function is available since SDL 3.0.0.
289 *
290 * \sa SDL_DestroySurface
291 * \sa SDL_LoadBMP
292 * \sa SDL_SaveBMP_RW
293 */
294extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, SDL_bool freesrc);
295
296/**
297 * Load a BMP image from a file.
298 *
299 * The new surface should be freed with SDL_DestroySurface(). Not doing so
300 * will result in a memory leak.
301 *
302 * \param file the BMP file to load
303 * \returns a pointer to a new SDL_Surface structure or NULL if there was an
304 * error; call SDL_GetError() for more information.
305 *
306 * \since This function is available since SDL 3.0.0.
307 *
308 * \sa SDL_DestroySurface
309 * \sa SDL_LoadBMP_RW
310 * \sa SDL_SaveBMP
311 */
312extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP(const char *file);
313
314/**
315 * Save a surface to a seekable SDL data stream in BMP format.
316 *
317 * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
318 * BMP directly. Other RGB formats with 8-bit or higher get converted to a
319 * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
320 * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
321 * not supported.
322 *
323 * \param surface the SDL_Surface structure containing the image to be saved
324 * \param dst a data stream to save to
325 * \param freedst if SDL_TRUE, calls SDL_RWclose() on `dst` before returning,
326 * even in the case of an error
327 * \returns 0 on success or a negative error code on failure; call
328 * SDL_GetError() for more information.
329 *
330 * \since This function is available since SDL 3.0.0.
331 *
332 * \sa SDL_LoadBMP_RW
333 * \sa SDL_SaveBMP
334 */
335extern DECLSPEC int SDLCALL SDL_SaveBMP_RW(SDL_Surface *surface, SDL_RWops *dst, SDL_bool freedst);
336
337/**
338 * Save a surface to a file.
339 *
340 * Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
341 * BMP directly. Other RGB formats with 8-bit or higher get converted to a
342 * 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
343 * surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
344 * not supported.
345 *
346 * \param surface the SDL_Surface structure containing the image to be saved
347 * \param file a file to save to
348 * \returns 0 on success or a negative error code on failure; call
349 * SDL_GetError() for more information.
350 *
351 * \since This function is available since SDL 3.0.0.
352 *
353 * \sa SDL_LoadBMP
354 * \sa SDL_SaveBMP_RW
355 */
356extern DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file);
357
358/**
359 * Set the RLE acceleration hint for a surface.
360 *
361 * If RLE is enabled, color key and alpha blending blits are much faster, but
362 * the surface must be locked before directly accessing the pixels.
363 *
364 * \param surface the SDL_Surface structure to optimize
365 * \param flag 0 to disable, non-zero to enable RLE acceleration
366 * \returns 0 on success or a negative error code on failure; call
367 * SDL_GetError() for more information.
368 *
369 * \since This function is available since SDL 3.0.0.
370 *
371 * \sa SDL_BlitSurface
372 * \sa SDL_LockSurface
373 * \sa SDL_UnlockSurface
374 */
375extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface,
376 int flag);
377
378/**
379 * Returns whether the surface is RLE enabled
380 *
381 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
382 *
383 * \param surface the SDL_Surface structure to query
384 * \returns SDL_TRUE if the surface is RLE enabled, SDL_FALSE otherwise.
385 *
386 * \since This function is available since SDL 3.0.0.
387 *
388 * \sa SDL_SetSurfaceRLE
389 */
390extern DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
391
392/**
393 * Set the color key (transparent pixel) in a surface.
394 *
395 * The color key defines a pixel value that will be treated as transparent in
396 * a blit. For example, one can use this to specify that cyan pixels should be
397 * considered transparent, and therefore not rendered.
398 *
399 * It is a pixel of the format used by the surface, as generated by
400 * SDL_MapRGB().
401 *
402 * RLE acceleration can substantially speed up blitting of images with large
403 * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
404 *
405 * \param surface the SDL_Surface structure to update
406 * \param flag SDL_TRUE to enable color key, SDL_FALSE to disable color key
407 * \param key the transparent pixel
408 * \returns 0 on success or a negative error code on failure; call
409 * SDL_GetError() for more information.
410 *
411 * \since This function is available since SDL 3.0.0.
412 *
413 * \sa SDL_BlitSurface
414 * \sa SDL_GetSurfaceColorKey
415 */
416extern DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface,
417 int flag, Uint32 key);
418
419/**
420 * Returns whether the surface has a color key
421 *
422 * It is safe to pass a NULL `surface` here; it will return SDL_FALSE.
423 *
424 * \param surface the SDL_Surface structure to query
425 * \returns SDL_TRUE if the surface has a color key, SDL_FALSE otherwise.
426 *
427 * \since This function is available since SDL 3.0.0.
428 *
429 * \sa SDL_SetSurfaceColorKey
430 * \sa SDL_GetSurfaceColorKey
431 */
432extern DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface);
433
434/**
435 * Get the color key (transparent pixel) for a surface.
436 *
437 * The color key is a pixel of the format used by the surface, as generated by
438 * SDL_MapRGB().
439 *
440 * If the surface doesn't have color key enabled this function returns -1.
441 *
442 * \param surface the SDL_Surface structure to query
443 * \param key a pointer filled in with the transparent pixel
444 * \returns 0 on success or a negative error code on failure; call
445 * SDL_GetError() for more information.
446 *
447 * \since This function is available since SDL 3.0.0.
448 *
449 * \sa SDL_BlitSurface
450 * \sa SDL_SetSurfaceColorKey
451 */
452extern DECLSPEC int SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface,
453 Uint32 *key);
454
455/**
456 * Set an additional color value multiplied into blit operations.
457 *
458 * When this surface is blitted, during the blit operation each source color
459 * channel is modulated by the appropriate color value according to the
460 * following formula:
461 *
462 * `srcC = srcC * (color / 255)`
463 *
464 * \param surface the SDL_Surface structure to update
465 * \param r the red color value multiplied into blit operations
466 * \param g the green color value multiplied into blit operations
467 * \param b the blue color value multiplied into blit operations
468 * \returns 0 on success or a negative error code on failure; call
469 * SDL_GetError() for more information.
470 *
471 * \since This function is available since SDL 3.0.0.
472 *
473 * \sa SDL_GetSurfaceColorMod
474 * \sa SDL_SetSurfaceAlphaMod
475 */
476extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface,
477 Uint8 r, Uint8 g, Uint8 b);
478
479
480/**
481 * Get the additional color value multiplied into blit operations.
482 *
483 * \param surface the SDL_Surface structure to query
484 * \param r a pointer filled in with the current red color value
485 * \param g a pointer filled in with the current green color value
486 * \param b a pointer filled in with the current blue color value
487 * \returns 0 on success or a negative error code on failure; call
488 * SDL_GetError() for more information.
489 *
490 * \since This function is available since SDL 3.0.0.
491 *
492 * \sa SDL_GetSurfaceAlphaMod
493 * \sa SDL_SetSurfaceColorMod
494 */
495extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface,
496 Uint8 *r, Uint8 *g,
497 Uint8 *b);
498
499/**
500 * Set an additional alpha value used in blit operations.
501 *
502 * When this surface is blitted, during the blit operation the source alpha
503 * value is modulated by this alpha value according to the following formula:
504 *
505 * `srcA = srcA * (alpha / 255)`
506 *
507 * \param surface the SDL_Surface structure to update
508 * \param alpha the alpha value multiplied into blit operations
509 * \returns 0 on success or a negative error code on failure; call
510 * SDL_GetError() for more information.
511 *
512 * \since This function is available since SDL 3.0.0.
513 *
514 * \sa SDL_GetSurfaceAlphaMod
515 * \sa SDL_SetSurfaceColorMod
516 */
517extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface *surface,
518 Uint8 alpha);
519
520/**
521 * Get the additional alpha value used in blit operations.
522 *
523 * \param surface the SDL_Surface structure to query
524 * \param alpha a pointer filled in with the current alpha value
525 * \returns 0 on success or a negative error code on failure; call
526 * SDL_GetError() for more information.
527 *
528 * \since This function is available since SDL 3.0.0.
529 *
530 * \sa SDL_GetSurfaceColorMod
531 * \sa SDL_SetSurfaceAlphaMod
532 */
533extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface,
534 Uint8 *alpha);
535
536/**
537 * Set the blend mode used for blit operations.
538 *
539 * To copy a surface to another surface (or texture) without blending with the
540 * existing data, the blendmode of the SOURCE surface should be set to
541 * `SDL_BLENDMODE_NONE`.
542 *
543 * \param surface the SDL_Surface structure to update
544 * \param blendMode the SDL_BlendMode to use for blit blending
545 * \returns 0 on success or a negative error code on failure; call
546 * SDL_GetError() for more information.
547 *
548 * \since This function is available since SDL 3.0.0.
549 *
550 * \sa SDL_GetSurfaceBlendMode
551 */
552extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface *surface,
553 SDL_BlendMode blendMode);
554
555/**
556 * Get the blend mode used for blit operations.
557 *
558 * \param surface the SDL_Surface structure to query
559 * \param blendMode a pointer filled in with the current SDL_BlendMode
560 * \returns 0 on success or a negative error code on failure; call
561 * SDL_GetError() for more information.
562 *
563 * \since This function is available since SDL 3.0.0.
564 *
565 * \sa SDL_SetSurfaceBlendMode
566 */
567extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface,
568 SDL_BlendMode *blendMode);
569
570/**
571 * Set the clipping rectangle for a surface.
572 *
573 * When `surface` is the destination of a blit, only the area within the clip
574 * rectangle is drawn into.
575 *
576 * Note that blits are automatically clipped to the edges of the source and
577 * destination surfaces.
578 *
579 * \param surface the SDL_Surface structure to be clipped
580 * \param rect the SDL_Rect structure representing the clipping rectangle, or
581 * NULL to disable clipping
582 * \returns SDL_TRUE if the rectangle intersects the surface, otherwise
583 * SDL_FALSE and blits will be completely clipped.
584 *
585 * \since This function is available since SDL 3.0.0.
586 *
587 * \sa SDL_BlitSurface
588 * \sa SDL_GetSurfaceClipRect
589 */
590extern DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface,
591 const SDL_Rect *rect);
592
593/**
594 * Get the clipping rectangle for a surface.
595 *
596 * When `surface` is the destination of a blit, only the area within the clip
597 * rectangle is drawn into.
598 *
599 * \param surface the SDL_Surface structure representing the surface to be
600 * clipped
601 * \param rect an SDL_Rect structure filled in with the clipping rectangle for
602 * the surface
603 * \returns 0 on success or a negative error code on failure; call
604 * SDL_GetError() for more information.
605 *
606 * \since This function is available since SDL 3.0.0.
607 *
608 * \sa SDL_BlitSurface
609 * \sa SDL_SetSurfaceClipRect
610 */
611extern DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface,
612 SDL_Rect *rect);
613
614/*
615 * Flip a surface vertically or horizontally.
616 *
617 * \param surface the surface to flip
618 * \param flip the direction to flip
619 * \returns 0 on success or a negative error code on failure; call
620 * SDL_GetError() for more information.
621 *
622 * \since This function is available since SDL 3.0.0.
623 */
624extern DECLSPEC int SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip);
625
626/*
627 * Creates a new surface identical to the existing surface.
628 *
629 * The returned surface should be freed with SDL_DestroySurface().
630 *
631 * \param surface the surface to duplicate.
632 * \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
633 * more information.
634 *
635 * \since This function is available since SDL 3.0.0.
636 */
637extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surface);
638
639/**
640 * Copy an existing surface to a new surface of the specified format.
641 *
642 * This function is used to optimize images for faster *repeat* blitting. This
643 * is accomplished by converting the original and storing the result as a new
644 * surface. The new, optimized surface can then be used as the source for
645 * future blits, making them faster.
646 *
647 * \param surface the existing SDL_Surface structure to convert
648 * \param format the SDL_PixelFormat structure that the new surface is
649 * optimized for
650 * \returns the new SDL_Surface structure that is created or NULL if it fails;
651 * call SDL_GetError() for more information.
652 *
653 * \since This function is available since SDL 3.0.0.
654 *
655 * \sa SDL_CreatePixelFormat
656 * \sa SDL_ConvertSurfaceFormat
657 * \sa SDL_CreateSurface
658 */
659extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface,
660 const SDL_PixelFormat *format);
661
662/**
663 * Copy an existing surface to a new surface of the specified format enum.
664 *
665 * This function operates just like SDL_ConvertSurface(), but accepts an
666 * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
667 * it might be easier to call but it doesn't have access to palette
668 * information for the destination surface, in case that would be important.
669 *
670 * \param surface the existing SDL_Surface structure to convert
671 * \param pixel_format the SDL_PixelFormatEnum that the new surface is
672 * optimized for
673 * \returns the new SDL_Surface structure that is created or NULL if it fails;
674 * call SDL_GetError() for more information.
675 *
676 * \since This function is available since SDL 3.0.0.
677 *
678 * \sa SDL_CreatePixelFormat
679 * \sa SDL_ConvertSurface
680 * \sa SDL_CreateSurface
681 */
682extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *surface,
683 Uint32 pixel_format);
684
685/**
686 * Copy a block of pixels of one format to another format.
687 *
688 * \param width the width of the block to copy, in pixels
689 * \param height the height of the block to copy, in pixels
690 * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
691 * \param src a pointer to the source pixels
692 * \param src_pitch the pitch of the source pixels, in bytes
693 * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
694 * \param dst a pointer to be filled in with new pixel data
695 * \param dst_pitch the pitch of the destination pixels, in bytes
696 * \returns 0 on success or a negative error code on failure; call
697 * SDL_GetError() for more information.
698 *
699 * \since This function is available since SDL 3.0.0.
700 */
701extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height,
702 Uint32 src_format,
703 const void *src, int src_pitch,
704 Uint32 dst_format,
705 void *dst, int dst_pitch);
706
707/**
708 * Premultiply the alpha on a block of pixels.
709 *
710 * This is safe to use with src == dst, but not for other overlapping areas.
711 *
712 * This function is currently only implemented for SDL_PIXELFORMAT_ARGB8888.
713 *
714 * \param width the width of the block to convert, in pixels
715 * \param height the height of the block to convert, in pixels
716 * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format
717 * \param src a pointer to the source pixels
718 * \param src_pitch the pitch of the source pixels, in bytes
719 * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format
720 * \param dst a pointer to be filled in with premultiplied pixel data
721 * \param dst_pitch the pitch of the destination pixels, in bytes
722 * \returns 0 on success or a negative error code on failure; call
723 * SDL_GetError() for more information.
724 *
725 * \since This function is available since SDL 3.0.0.
726 */
727extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height,
728 Uint32 src_format,
729 const void *src, int src_pitch,
730 Uint32 dst_format,
731 void *dst, int dst_pitch);
732
733/**
734 * Perform a fast fill of a rectangle with a specific color.
735 *
736 * `color` should be a pixel of the format used by the surface, and can be
737 * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
738 * alpha component then the destination is simply filled with that alpha
739 * information, no blending takes place.
740 *
741 * If there is a clip rectangle set on the destination (set via
742 * SDL_SetSurfaceClipRect()), then this function will fill based on the
743 * intersection of the clip rectangle and `rect`.
744 *
745 * \param dst the SDL_Surface structure that is the drawing target
746 * \param rect the SDL_Rect structure representing the rectangle to fill, or
747 * NULL to fill the entire surface
748 * \param color the color to fill with
749 * \returns 0 on success or a negative error code on failure; call
750 * SDL_GetError() for more information.
751 *
752 * \since This function is available since SDL 3.0.0.
753 *
754 * \sa SDL_FillSurfaceRects
755 */
756extern DECLSPEC int SDLCALL SDL_FillSurfaceRect
757 (SDL_Surface *dst, const SDL_Rect *rect, Uint32 color);
758
759/**
760 * Perform a fast fill of a set of rectangles with a specific color.
761 *
762 * `color` should be a pixel of the format used by the surface, and can be
763 * generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an
764 * alpha component then the destination is simply filled with that alpha
765 * information, no blending takes place.
766 *
767 * If there is a clip rectangle set on the destination (set via
768 * SDL_SetSurfaceClipRect()), then this function will fill based on the
769 * intersection of the clip rectangle and `rect`.
770 *
771 * \param dst the SDL_Surface structure that is the drawing target
772 * \param rects an array of SDL_Rects representing the rectangles to fill.
773 * \param count the number of rectangles in the array
774 * \param color the color to fill with
775 * \returns 0 on success or a negative error code on failure; call
776 * SDL_GetError() for more information.
777 *
778 * \since This function is available since SDL 3.0.0.
779 *
780 * \sa SDL_FillSurfaceRect
781 */
782extern DECLSPEC int SDLCALL SDL_FillSurfaceRects
783 (SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color);
784
785/**
786 * Performs a fast blit from the source surface to the destination surface.
787 *
788 * This assumes that the source and destination rectangles are the same size.
789 * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
790 * `dst`) is copied. The final blit rectangles are saved in `srcrect` and
791 * `dstrect` after all clipping is performed.
792 *
793 * The blit function should not be called on a locked surface.
794 *
795 * The blit semantics for surfaces with and without blending and colorkey are
796 * defined as follows:
797 *
798 * ```c
799 * RGBA->RGB:
800 * Source surface blend mode set to SDL_BLENDMODE_BLEND:
801 * alpha-blend (using the source alpha-channel and per-surface alpha)
802 * SDL_SRCCOLORKEY ignored.
803 * Source surface blend mode set to SDL_BLENDMODE_NONE:
804 * copy RGB.
805 * if SDL_SRCCOLORKEY set, only copy the pixels matching the
806 * RGB values of the source color key, ignoring alpha in the
807 * comparison.
808 *
809 * RGB->RGBA:
810 * Source surface blend mode set to SDL_BLENDMODE_BLEND:
811 * alpha-blend (using the source per-surface alpha)
812 * Source surface blend mode set to SDL_BLENDMODE_NONE:
813 * copy RGB, set destination alpha to source per-surface alpha value.
814 * both:
815 * if SDL_SRCCOLORKEY set, only copy the pixels matching the
816 * source color key.
817 *
818 * RGBA->RGBA:
819 * Source surface blend mode set to SDL_BLENDMODE_BLEND:
820 * alpha-blend (using the source alpha-channel and per-surface alpha)
821 * SDL_SRCCOLORKEY ignored.
822 * Source surface blend mode set to SDL_BLENDMODE_NONE:
823 * copy all of RGBA to the destination.
824 * if SDL_SRCCOLORKEY set, only copy the pixels matching the
825 * RGB values of the source color key, ignoring alpha in the
826 * comparison.
827 *
828 * RGB->RGB:
829 * Source surface blend mode set to SDL_BLENDMODE_BLEND:
830 * alpha-blend (using the source per-surface alpha)
831 * Source surface blend mode set to SDL_BLENDMODE_NONE:
832 * copy RGB.
833 * both:
834 * if SDL_SRCCOLORKEY set, only copy the pixels matching the
835 * source color key.
836 * ```
837 *
838 * \param src the SDL_Surface structure to be copied from
839 * \param srcrect the SDL_Rect structure representing the rectangle to be
840 * copied, or NULL to copy the entire surface
841 * \param dst the SDL_Surface structure that is the blit target
842 * \param dstrect the SDL_Rect structure representing the x and y position in
843 * the destination surface. On input the width and height are
844 * ignored (taken from srcrect), and on output this is filled
845 * in with the actual rectangle used after clipping.
846 * \returns 0 on success or a negative error code on failure; call
847 * SDL_GetError() for more information.
848 *
849 * \since This function is available since SDL 3.0.0.
850 *
851 * \sa SDL_BlitSurfaceScaled
852 */
853extern DECLSPEC int SDLCALL SDL_BlitSurface
854 (SDL_Surface *src, const SDL_Rect *srcrect,
855 SDL_Surface *dst, SDL_Rect *dstrect);
856
857/**
858 * Perform low-level surface blitting only.
859 *
860 * This is a semi-private blit function and it performs low-level surface
861 * blitting, assuming the input rectangles have already been clipped.
862 *
863 * \param src the SDL_Surface structure to be copied from
864 * \param srcrect the SDL_Rect structure representing the rectangle to be
865 * copied, or NULL to copy the entire surface
866 * \param dst the SDL_Surface structure that is the blit target
867 * \param dstrect the SDL_Rect structure representing the target rectangle in
868 * the destination surface
869 * \returns 0 on success or a negative error code on failure; call
870 * SDL_GetError() for more information.
871 *
872 * \since This function is available since SDL 3.0.0.
873 *
874 * \sa SDL_BlitSurface
875 */
876extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
877 (SDL_Surface *src, const SDL_Rect *srcrect,
878 SDL_Surface *dst, const SDL_Rect *dstrect);
879
880/**
881 * Perform stretch blit between two surfaces of the same format.
882 *
883 * Using SDL_SCALEMODE_NEAREST: fast, low quality. Using SDL_SCALEMODE_LINEAR:
884 * bilinear scaling, slower, better quality, only 32BPP.
885 *
886 * \param src the SDL_Surface structure to be copied from
887 * \param srcrect the SDL_Rect structure representing the rectangle to be
888 * copied
889 * \param dst the SDL_Surface structure that is the blit target
890 * \param dstrect the SDL_Rect structure representing the target rectangle in
891 * the destination surface
892 * \param scaleMode scale algorithm to be used
893 * \returns 0 on success or a negative error code on failure; call
894 * SDL_GetError() for more information.
895 *
896 * \since This function is available since SDL 3.0.0.
897 *
898 * \sa SDL_BlitSurfaceScaled
899 */
900extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
901 const SDL_Rect *srcrect,
902 SDL_Surface *dst,
903 const SDL_Rect *dstrect,
904 SDL_ScaleMode scaleMode);
905
906/**
907 * Perform a scaled surface copy to a destination surface.
908 *
909 * \param src the SDL_Surface structure to be copied from
910 * \param srcrect the SDL_Rect structure representing the rectangle to be
911 * copied
912 * \param dst the SDL_Surface structure that is the blit target
913 * \param dstrect the SDL_Rect structure representing the target rectangle in
914 * the destination surface, filled with the actual rectangle
915 * used after clipping
916 * \param scaleMode scale algorithm to be used
917 * \returns 0 on success or a negative error code on failure; call
918 * SDL_GetError() for more information.
919 *
920 * \since This function is available since SDL 3.0.0.
921 *
922 * \sa SDL_BlitSurface
923 */
924extern DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src,
925 const SDL_Rect *srcrect,
926 SDL_Surface *dst,
927 SDL_Rect *dstrect,
928 SDL_ScaleMode scaleMode);
929
930/**
931 * Perform low-level surface scaled blitting only.
932 *
933 * This is a semi-private function and it performs low-level surface blitting,
934 * assuming the input rectangles have already been clipped.
935 *
936 * \param src the SDL_Surface structure to be copied from
937 * \param srcrect the SDL_Rect structure representing the rectangle to be
938 * copied
939 * \param dst the SDL_Surface structure that is the blit target
940 * \param dstrect the SDL_Rect structure representing the target rectangle in
941 * the destination surface
942 * \param scaleMode scale algorithm to be used
943 * \returns 0 on success or a negative error code on failure; call
944 * SDL_GetError() for more information.
945 *
946 * \since This function is available since SDL 3.0.0.
947 *
948 * \sa SDL_BlitSurfaceScaled
949 */
950extern DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src,
951 const SDL_Rect *srcrect,
952 SDL_Surface *dst,
953 const SDL_Rect *dstrect,
954 SDL_ScaleMode scaleMode);
955
956/**
957 * Retrieves a single pixel from a surface.
958 *
959 * This function prioritizes correctness over speed: it is suitable for unit
960 * tests, but is not intended for use in a game engine.
961 *
962 * Like SDL_GetRGBA, this uses the entire 0..255 range when converting color
963 * components from pixel formats with less than 8 bits per RGB component.
964 *
965 * \param surface the surface to read
966 * \param x the horizontal coordinate, 0 <= x < width
967 * \param y the vertical coordinate, 0 <= y < height
968 * \param r a pointer filled in with the red channel, 0-255, or NULL to ignore
969 * this channel
970 * \param g a pointer filled in with the green channel, 0-255, or NULL to
971 * ignore this channel
972 * \param b a pointer filled in with the blue channel, 0-255, or NULL to
973 * ignore this channel
974 * \param a a pointer filled in with the alpha channel, 0-255, or NULL to
975 * ignore this channel
976 * \returns 0 on success or a negative error code on failure; call
977 * SDL_GetError() for more information.
978 *
979 * \since This function is available since SDL 3.0.0.
980 */
981extern DECLSPEC int SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
982
983
984/**
985 * Set the YUV conversion mode
986 *
987 * \param mode YUV conversion mode
988 *
989 * \since This function is available since SDL 3.0.0.
990 */
991extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
992
993/**
994 * Get the YUV conversion mode
995 *
996 * \returns YUV conversion mode
997 *
998 * \since This function is available since SDL 3.0.0.
999 */
1001
1002/**
1003 * Get the YUV conversion mode, returning the correct mode for the resolution
1004 * when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
1005 *
1006 * \param width width
1007 * \param height height
1008 * \returns YUV conversion mode
1009 *
1010 * \since This function is available since SDL 3.0.0.
1011 */
1012extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionModeForResolution(int width, int height);
1013
1014/* Ends C function definitions when using C++ */
1015#ifdef __cplusplus
1016}
1017#endif
1018#include <SDL3/SDL_close_code.h>
1019
1020#endif /* SDL_surface_h_ */
SDL_BlendMode
Uint32 SDL_PropertiesID
uint8_t Uint8
Definition SDL_stdinc.h:150
int SDL_bool
Definition SDL_stdinc.h:137
uint32_t Uint32
Definition SDL_stdinc.h:174
SDL_YUV_CONVERSION_MODE
@ SDL_YUV_CONVERSION_BT601
@ SDL_YUV_CONVERSION_JPEG
@ SDL_YUV_CONVERSION_BT709
@ SDL_YUV_CONVERSION_AUTOMATIC
int SDL_FillSurfaceRect(SDL_Surface *dst, const SDL_Rect *rect, Uint32 color)
int SDL_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
SDL_PropertiesID SDL_GetSurfaceProperties(SDL_Surface *surface)
int(* SDL_blit)(struct SDL_Surface *src, const SDL_Rect *srcrect, struct SDL_Surface *dst, const SDL_Rect *dstrect)
int SDL_GetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode *blendMode)
void SDL_DestroySurface(SDL_Surface *surface)
SDL_Surface * SDL_ConvertSurfaceFormat(SDL_Surface *surface, Uint32 pixel_format)
SDL_Surface * SDL_CreateSurfaceFrom(void *pixels, int width, int height, int pitch, Uint32 format)
int SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect)
int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette)
int SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode)
SDL_Surface * SDL_DuplicateSurface(SDL_Surface *surface)
int SDL_FillSurfaceRects(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color)
int SDL_SetSurfaceRLE(SDL_Surface *surface, int flag)
int SDL_LockSurface(SDL_Surface *surface)
int SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect)
int SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Uint8 *alpha)
int SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect, SDL_ScaleMode scaleMode)
SDL_ScaleMode
Definition SDL_surface.h:72
@ SDL_SCALEMODE_LINEAR
Definition SDL_surface.h:74
@ SDL_SCALEMODE_NEAREST
Definition SDL_surface.h:73
@ SDL_SCALEMODE_BEST
Definition SDL_surface.h:75
int SDL_PremultiplyAlpha(int width, int height, Uint32 src_format, const void *src, int src_pitch, Uint32 dst_format, void *dst, int dst_pitch)
SDL_Surface * SDL_ConvertSurface(SDL_Surface *surface, const SDL_PixelFormat *format)
int SDL_SoftStretch(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode)
struct SDL_BlitMap SDL_BlitMap
Definition SDL_surface.h:66
int SDL_SetSurfaceColorMod(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b)
int SDL_SetSurfaceColorKey(SDL_Surface *surface, int flag, Uint32 key)
SDL_Surface * SDL_CreateSurface(int width, int height, Uint32 format)
SDL_FlipMode
Definition SDL_surface.h:82
@ SDL_FLIP_VERTICAL
Definition SDL_surface.h:85
@ SDL_FLIP_NONE
Definition SDL_surface.h:83
@ SDL_FLIP_HORIZONTAL
Definition SDL_surface.h:84
int SDL_SaveBMP(SDL_Surface *surface, const char *file)
void SDL_UnlockSurface(SDL_Surface *surface)
int SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect)
SDL_bool SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect)
int SDL_GetSurfaceColorMod(SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b)
SDL_Surface * SDL_LoadBMP_RW(SDL_RWops *src, SDL_bool freesrc)
int SDL_SetSurfaceAlphaMod(SDL_Surface *surface, Uint8 alpha)
SDL_bool SDL_SurfaceHasColorKey(SDL_Surface *surface)
int SDL_ConvertPixels(int width, int height, Uint32 src_format, const void *src, int src_pitch, Uint32 dst_format, void *dst, int dst_pitch)
int SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMode flip)
int SDL_SaveBMP_RW(SDL_Surface *surface, SDL_RWops *dst, SDL_bool freedst)
SDL_YUV_CONVERSION_MODE SDL_GetYUVConversionMode(void)
int SDL_GetSurfaceColorKey(SDL_Surface *surface, Uint32 *key)
SDL_bool SDL_SurfaceHasRLE(SDL_Surface *surface)
SDL_Surface * SDL_LoadBMP(const char *file)
int SDL_SetSurfaceBlendMode(SDL_Surface *surface, SDL_BlendMode blendMode)
void SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode)
SDL_YUV_CONVERSION_MODE SDL_GetYUVConversionModeForResolution(int width, int height)
SDL_PixelFormat * format
void * list_blitmap
void * reserved
SDL_Rect clip_rect
void * pixels
SDL_BlitMap * map