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