From e957840d3471abee575380cb3af4e519ae9f0750 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 18 Dec 2024 01:18:23 -0500
Subject: [PATCH] include: Filling in some more documentation gaps.
---
.wikiheaders-options | 2 +-
include/SDL3/SDL_pixels.h | 78 ++++++++++++++++++++++++++-------------
include/SDL3/SDL_sensor.h | 5 +++
include/SDL3/SDL_stdinc.h | 51 ++++++++++++++++++++++++-
4 files changed, 108 insertions(+), 28 deletions(-)
diff --git a/.wikiheaders-options b/.wikiheaders-options
index d72f9178de590..99c19dee9524a 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -27,4 +27,4 @@ quickrefcategoryorder = Init,Hints,Error,Version,Properties,Log,Video,Events,Key
quickreftitle = SDL3 API Quick Reference
quickrefurl = https://libsdl.org/
quickrefdesc = The latest version of this document can be found at https://wiki.libsdl.org/SDL3/QuickReference
-quickrefmacroregex = \A(SDL_PLATFORM_.*|SDL_.*_INTRINSICS|SDL_Atomic...Ref|SDL_assert.*?|SDL_arraysize|SDL_Swap[BL]E\d\d|SDL_[a-z]+_cast)\Z
+quickrefmacroregex = \A(SDL_PLATFORM_.*|SDL_.*_INTRINSICS|SDL_Atomic...Ref|SDL_assert.*?|SDL_COMPILE_TIME_ASSERT|SDL_arraysize|SDL_Swap[BL]E\d\d|SDL_[a-z]+_cast)\Z
diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h
index eb6ff50181cc4..7d3debb185d16 100644
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@@ -22,7 +22,59 @@
/**
* # CategoryPixels
*
- * Pixel management.
+ * SDL offers facilities for pixel management.
+ *
+ * Largely these facilities deal with pixel _format_: what does this set of
+ * bits represent?
+ *
+ * If you mostly want to think of a pixel as some combination of red, green,
+ * blue, and maybe alpha intensities, this is all pretty straightforward, and
+ * in many cases, is enough information to build a perfectly fine game.
+ *
+ * However, the actual definition of a pixel is more complex than that:
+ *
+ * Pixels are a representation of a color in a particular color space.
+ *
+ * The first characteristic of a color space is the color type. SDL
+ * understands two different color types, RGB and YCbCr, or in SDL also
+ * referred to as YUV.
+ *
+ * RGB colors consist of red, green, and blue channels of color that are
+ * added together to represent the colors we see on the screen.
+ *
+ * https://en.wikipedia.org/wiki/RGB_color_model
+ *
+ * YCbCr colors represent colors as a Y luma brightness component and red and
+ * blue chroma color offsets. This color representation takes advantage of
+ * the fact that the human eye is more sensitive to brightness than the color
+ * in an image. The Cb and Cr components are often compressed and have lower
+ * resolution than the luma component.
+ *
+ * https://en.wikipedia.org/wiki/YCbCr
+ *
+ * When the color information in YCbCr is compressed, the Y pixels are left
+ * at full resolution and each Cr and Cb pixel represents an average of the
+ * color information in a block of Y pixels. The chroma location determines
+ * where in that block of pixels the color information is coming from.
+ *
+ * The color range defines how much of the pixel to use when converting a
+ * pixel into a color on the display. When the full color range is used, the
+ * entire numeric range of the pixel bits is significant. When narrow color
+ * range is used, for historical reasons, the pixel uses only a portion of
+ * the numeric range to represent colors.
+ *
+ * The color primaries and white point are a definition of the colors in the
+ * color space relative to the standard XYZ color space.
+ *
+ * https://en.wikipedia.org/wiki/CIE_1931_color_space
+ *
+ * The transfer characteristic, or opto-electrical transfer function (OETF),
+ * is the way a color is converted from mathematically linear space into a
+ * non-linear output signals.
+ *
+ * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics
+ *
+ * The matrix coefficients are used to convert between YCbCr and RGB colors.
*/
#ifndef SDL_pixels_h_
@@ -419,30 +471,6 @@ typedef enum SDL_PixelFormat
#endif
} SDL_PixelFormat;
-/**
- * Pixels are a representation of a color in a particular color space.
- *
- * The first characteristic of a color space is the color type. SDL understands two different color types, RGB and YCbCr, or in SDL also referred to as YUV.
- *
- * RGB colors consist of red, green, and blue channels of color that are added together to represent the colors we see on the screen.
- * https://en.wikipedia.org/wiki/RGB_color_model
- *
- * YCbCr colors represent colors as a Y luma brightness component and red and blue chroma color offsets. This color representation takes advantage of the fact that the human eye is more sensitive to brightness than the color in an image. The Cb and Cr components are often compressed and have lower resolution than the luma component.
- * https://en.wikipedia.org/wiki/YCbCr
- *
- * When the color information in YCbCr is compressed, the Y pixels are left at full resolution and each Cr and Cb pixel represents an average of the color information in a block of Y pixels. The chroma location determines where in that block of pixels the color information is coming from.
- *
- * The color range defines how much of the pixel to use when converting a pixel into a color on the display. When the full color range is used, the entire numeric range of the pixel bits is significant. When narrow color range is used, for historical reasons, the pixel uses only a portion of the numeric range to represent colors.
- *
- * The color primaries and white point are a definition of the colors in the color space relative to the standard XYZ color space.
- * https://en.wikipedia.org/wiki/CIE_1931_color_space
- *
- * The transfer characteristic, or opto-electrical transfer function (OETF), is the way a color is converted from mathematically linear space into a non-linear output signals.
- * https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics
- *
- * The matrix coefficients are used to convert between YCbCr and RGB colors.
- */
-
/**
* Colorspace color type.
*
diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h
index 13862913019da..008c8d6877ec5 100644
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -44,6 +44,11 @@ extern "C" {
/* *INDENT-ON* */
#endif
+/**
+ * The opaque structure used to identify an opened SDL sensor.
+ *
+ * \since This struct is available since SDL 3.1.3.
+ */
typedef struct SDL_Sensor SDL_Sensor;
/**
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 8c029962a74f7..e2423f8824518 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -95,7 +95,40 @@ void *alloca(size_t);
#endif
#ifndef SDL_COMPILE_TIME_ASSERT
-#if defined(__cplusplus)
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+/**
+ * A compile-time assertion.
+ *
+ * This can check constant values _known to the compiler at build time_ for
+ * correctness, and end the compile with the error if they fail.
+ *
+ * Often times these are used to verify basic truths, like the size of a
+ * datatype is what is expected:
+ *
+ * ```c
+ * SDL_COMPILE_TIME_ASSERT(uint32_size, sizeof(Uint32) == 4);
+ * ```
+ *
+ * The `name` parameter must be a valid C symbol, and must be unique across
+ * all compile-time asserts in the same compilation unit (one run of the
+ * compiler), or the build might fail with cryptic errors on some targets.
+ * This is used with a C language trick that works on older compilers that
+ * don't support better assertion techniques.
+ *
+ * If you need an assertion that operates at runtime, on variable data,
+ * you should try SDL_assert instead.
+ *
+ * \param name a unique identifier for this assertion.
+ * \param x the value to test. Must be a boolean value.
+ *
+ * \threadsafety This macro doesn't generate any code to run.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_assert
+ */
+#define SDL_COMPILE_TIME_ASSERT(name, x) FailToCompileIf_x_IsFalse(x)
+#elif defined(__cplusplus)
/* Keep C++ case alone: Some versions of gcc will define __STDC_VERSION__ even when compiling in C++ mode. */
#if (__cplusplus >= 201103L)
#define SDL_COMPILE_TIME_ASSERT(name, x) static_assert(x, #x)
@@ -2852,11 +2885,25 @@ extern SDL_DECLSPEC float SDLCALL SDL_randf_r(Uint64 *state);
*/
extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits_r(Uint64 *state);
-
#ifndef SDL_PI_D
+/**
+ * The value of Pi, as a double-precision floating point literal.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_PI_F
+ */
#define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */
#endif
+
#ifndef SDL_PI_F
+/**
+ * The value of Pi, as a single-precision floating point literal.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ *
+ * \sa SDL_PI_D
+ */
#define SDL_PI_F 3.141592653589793238462643383279502884F /**< pi (float) */
#endif