Improve documentation of GdkGLPixelFormat

1 files changed, 171 insertions, 9 deletions

diff --git a/gdk/gdkglpixelformat.c b/gdk/gdkglpixelformat.c
index f2a937b9f7..ea40ee97a6 100644
--- a/gdk/gdkglpixelformat.c
+++ b/gdk/gdkglpixelformat.c
@@ -26,6 +26,62 @@
  * The #GdkGLPixelFormat class is used to specify the types and sizes of
  * buffers to be used by a #GdkGLContext, as well as other configuration
  * parameters.
+ *
+ * Once created, a #GdkGLPixelFormat is immutable, and can only be used
+ * to create a #GdkGLContext, or for validation.
+ *
+ * Once a #GdkGLPixelFormat has been validated, either directly through
+ * gdk_display_validate_gl_pixel_format() or indirectly through the
+ * creation of a #GdkGLContext, it is possible to query its properties
+ * for the values found during validation.
+ *
+ * ## Using GdkGLPixelFormat ##
+ *
+ * Typically, you will create a new #GdkGLPixelFormat using the given
+ * constructor and properties:
+ *
+ * |[<!-- language="C" -->
+ *   GdkGLPixelFormat *format;
+ *
+ *   // Ask for a pixel format with double buffering and
+ *   // a depth buffer with a size of 32 bits
+ *   format = gdk_gl_pixel_format_new ("double-buffer", TRUE,
+ *                                     "depth-size", 32,
+ *                                     NULL);
+ * ]|
+ *
+ * After creating a pixel format, you can validate it using a #GdkDisplay
+ * and use the result of gdk_display_validate_gl_pixel_format() to provide
+ * an alternative pixel format:
+ *
+ * |[<!-- language="C" -->
+ *   GError *error = NULL;
+ *
+ *   // The "display" variable is set elsewhere.
+ *   // The "format" variable is the one we set previously.
+ *   if (!gdk_display_validate_gl_pixel_format (display, format, &error))
+ *     {
+ *       // print "error" or create a new pixel format to validate
+ *     }
+ * ]|
+ *
+ * You can also create a #GdkGLContext for the given display and
+ * pixel format:
+ *
+ * |[<!-- language="C" -->
+ *   GdkGLContext *context;
+ *   GError *error = NULL;
+ *
+ *   context = gdk_display_get_gl_context (display, format, NULL, &error);
+ *   if (error != NULL)
+ *     {
+ *       // print error
+ *     }
+ * ]|
+ *
+ * Once a #GdkGLContext has been created with a #GdkGLPixelFormat, the
+ * context will acquire a reference on the pixel format, so it's safe to
+ * release the reference created at construction.
  */
 
 #include "config.h"
@@ -194,87 +250,186 @@ gdk_gl_pixel_format_class_init (GdkGLPixelFormatClass *klass)
   gobject_class->set_property = gdk_gl_pixel_format_set_property;
   gobject_class->get_property = gdk_gl_pixel_format_get_property;
 
+  /**
+   * GdkGLPixelFormat:double-buffer:
+   *
+   * Whether the pixel format should enable double buffering.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_DOUBLE_BUFFER] =
     g_param_spec_boolean ("double-buffer",
                           P_("Double Buffer"),
-                          P_(""),
+                          P_("Whether the pixel format should ask for double buffering"),
                           FALSE,
                           G_PARAM_READWRITE |
                           G_PARAM_CONSTRUCT_ONLY |
                           G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:multi-sample:
+   *
+   * Whether the pixel format should enable multi-sampling.
+   *
+   * See also the #GdkGLPixelFormat:sample-buffers and
+   * #GdkGLPixelFormat:samples properties.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_MULTI_SAMPLE] =
     g_param_spec_boolean ("multi-sample",
                           P_("Multi Sample"),
-                          P_(""),
+                          P_("Whether the pixel format should enable multi-sampling"),
                           FALSE,
                           G_PARAM_READWRITE |
                           G_PARAM_CONSTRUCT_ONLY |
                           G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:aux-buffers:
+   *
+   * A positive integer indicating the number of auxiliary buffers
+   * for the pixel format.
+   *
+   * If set to -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_AUX_BUFFERS] =
     g_param_spec_int ("aux-buffers",
                       P_("Auxiliary Buffers"),
-                      P_(""),
+                      P_("The number of auxiliary buffers"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:color-size:
+   *
+   * A positive integer indicating the size of each color buffer.
+   *
+   * If set to -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_COLOR_SIZE] =
     g_param_spec_int ("color-size",
                       P_("Color Size"),
-                      P_(""),
+                      P_("The size of each color buffer"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:alpha-size:
+   *
+   * A positive integer indicating the size of the alpha buffer.
+   *
+   * If set to 0, the alpha channel will be ignored.
+   *
+   * If set the -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_ALPHA_SIZE] =
     g_param_spec_int ("alpha-size",
                       P_("Alpha Size"),
-                      P_(""),
+                      P_("The size of the alpha buffer"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:depth-size:
+   *
+   * A positive integer indicating the size of the depth buffer.
+   *
+   * If set to -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_DEPTH_SIZE] =
     g_param_spec_int ("depth-size",
                       P_("Depth Size"),
-                      P_(""),
+                      P_("The size of the depth buffer"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:stencil-size:
+   *
+   * A positive integer indicating the size of the stencil buffer.
+   *
+   * If set to -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_STENCIL_SIZE] =
     g_param_spec_int ("stencil-size",
                       P_("Stencil Size"),
-                      P_(""),
+                      P_("The size of the stencil buffer"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:accum-size:
+   *
+   * A positive integer indicating the size of the accumulation buffer.
+   *
+   * If set to -1, the default will be used.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_ACCUM_SIZE] =
     g_param_spec_int ("accum-size",
                       P_("Accumulation Size"),
-                      P_(""),
+                      P_("The size of the accumulation buffer"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:sample-buffers:
+   *
+   * A positive integer indicating the number of multi-sample buffers.
+   *
+   * If set to -1, the default will be used.
+   *
+   * This property is only used if #GdkGLPixelFormat:multi-sample is set
+   * to %TRUE.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_SAMPLE_BUFFERS] =
     g_param_spec_int ("sample-buffers",
                       P_("Sample Buffers"),
-                      P_(""),
+                      P_("The number of multi-sample buffers"),
                       -1, G_MAXINT, -1,
                       G_PARAM_READWRITE |
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:samples:
+   *
+   * A positive integer indicating the number of samples for each
+   * multi-sample buffer.
+   *
+   * If set to -1, the default will be used.
+   *
+   * This property is only used if #GdkGLPixelFormat:multi-sample is set
+   * to %TRUE.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_SAMPLES] =
     g_param_spec_int ("samples",
                       P_("Samples"),
@@ -284,6 +439,13 @@ gdk_gl_pixel_format_class_init (GdkGLPixelFormatClass *klass)
                       G_PARAM_CONSTRUCT_ONLY |
                       G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLPixelFormat:profile:
+   *
+   * The GL profile to be used when creating a #GdkGLContext.
+   *
+   * Since: 3.14
+   */
   obj_props[PROP_PROFILE] =
     g_param_spec_enum ("profile",
                        P_("Profile"),