SDL_surface.h 40 KB

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