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