From 155c3bb0a33a842d23f3dafc9bf541f0973cd686 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 12 Aug 2024 01:22:25 -0400
Subject: [PATCH] SDL_GLattr: formatted wiki documentation to be
wikiheaders-friendly.
Reference https://github.com/libsdl-org/sdlwiki/issues/544
---
include/SDL_video.h | 82 +++++++++++++++++++++++++++++++--------------
1 file changed, 56 insertions(+), 26 deletions(-)
diff --git a/include/SDL_video.h b/include/SDL_video.h
index 6afc63e65afd6..e2bc12be33da3 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -221,35 +221,65 @@ typedef enum SDL_FlashOperation
typedef void *SDL_GLContext;
/**
- * OpenGL configuration attributes
+ * OpenGL configuration attributes.
+ *
+ * While you can set most OpenGL attributes normally, the attributes listed
+ * above must be known before SDL creates the window that will be used with
+ * the OpenGL context. These attributes are set and read with
+ * SDL_GL_SetAttribute and SDL_GL_GetAttribute.
+ *
+ * In some cases, these attributes are minimum requests; the GL does not
+ * promise to give you exactly what you asked for. It's possible to ask for a
+ * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask
+ * for no stencil buffer and still have one available. Context creation should
+ * fail if the GL can't provide your requested attributes at a minimum, but
+ * you should check to see exactly what you got.
+ *
+ *
+ * [Multisample anti-aliasing](http://en.wikipedia.org/wiki/Multisample_anti-aliasing)
+ * is a type of full screen anti-aliasing. Multipsampling defaults to off but
+ * can be turned on by setting SDL_GL_MULTISAMPLEBUFFERS to 1 and
+ * SDL_GL_MULTISAMPLESAMPLES to a value greater than 0. Typical values are 2
+ * and 4.
+ *
+ * SDL_GL_CONTEXT_PROFILE_MASK determines the type of context created, while
+ * both SDL_GL_CONTEXT_MAJOR_VERSION and SDL_GL_CONTEXT_MINOR_VERSION
+ * determine which version. All three attributes must be set prior to creating
+ * the first window, and in general you can't change the value of
+ * SDL_GL_CONTEXT_PROFILE_MASK without first destroying all windows created
+ * with the previous setting.
+ *
+ * SDL_GL_CONTEXT_RELEASE_BEHAVIOR can be set to
+ * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE or
+ * SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH.
*/
typedef enum SDL_GLattr
{
- SDL_GL_RED_SIZE,
- SDL_GL_GREEN_SIZE,
- SDL_GL_BLUE_SIZE,
- SDL_GL_ALPHA_SIZE,
- SDL_GL_BUFFER_SIZE,
- SDL_GL_DOUBLEBUFFER,
- SDL_GL_DEPTH_SIZE,
- SDL_GL_STENCIL_SIZE,
- SDL_GL_ACCUM_RED_SIZE,
- SDL_GL_ACCUM_GREEN_SIZE,
- SDL_GL_ACCUM_BLUE_SIZE,
- SDL_GL_ACCUM_ALPHA_SIZE,
- SDL_GL_STEREO,
- SDL_GL_MULTISAMPLEBUFFERS,
- SDL_GL_MULTISAMPLESAMPLES,
- SDL_GL_ACCELERATED_VISUAL,
- SDL_GL_RETAINED_BACKING,
- SDL_GL_CONTEXT_MAJOR_VERSION,
- SDL_GL_CONTEXT_MINOR_VERSION,
- SDL_GL_CONTEXT_EGL,
- SDL_GL_CONTEXT_FLAGS,
- SDL_GL_CONTEXT_PROFILE_MASK,
- SDL_GL_SHARE_WITH_CURRENT_CONTEXT,
- SDL_GL_FRAMEBUFFER_SRGB_CAPABLE,
- SDL_GL_CONTEXT_RELEASE_BEHAVIOR,
+ SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 3. */
+ SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 3. */
+ SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 2. */
+ SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. */
+ SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */
+ SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */
+ SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */
+ SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */
+ SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */
+ SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */
+ SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */
+ SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */
+ SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */
+ SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */
+ SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */
+ SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */
+ SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */
+ SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */
+ SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */
+ SDL_GL_CONTEXT_EGL, /**< deprecated: set SDL_GL_CONTEXT_PROFILE_MASK to SDL_GL_CONTEXT_PROFILE_ES to enable instead. */
+ SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLcontextFlag enumeration; defaults to 0. */
+ SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLprofile; default value depends on platform. */
+ SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */
+ SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB capable visual; defaults to 0. (>= SDL 2.0.1) */
+ SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior; defaults to 1. (>= SDL 2.0.4) */
SDL_GL_CONTEXT_RESET_NOTIFICATION,
SDL_GL_CONTEXT_NO_ERROR,
SDL_GL_FLOATBUFFERS