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