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