framebuffer: Add dither_enabled getter/setters

This adds a getter and setter for requesting dithering to be enabled.

Dithering is a hardware dependent technique to increase the visible
color resolution beyond what the underlying hardware supports by playing
tricks with the colors placed into the framebuffer to give the illusion
of other colors. (For example this can be compared to half-toning used
by some news papers to show varying levels of grey even though their may
only be black and white are available).

The results of enabling dithering are platform dependent and may have no
effect.

Signed-off-by: Neil Roberts <neil@linux.intel.com>

5 files changed, 75 insertions, 0 deletions

diff --git a/cogl/cogl-context-private.h b/cogl/cogl-context-private.h
index b4adebd6..4ce999b3 100644
--- a/cogl/cogl-context-private.h
+++ b/cogl/cogl-context-private.h
@@ -203,6 +203,8 @@ struct _CoglContext
   CoglPipelineProgramType current_vertex_program_type;
   GLuint                  current_gl_program;
 
+  gboolean current_gl_dither_enabled;
+
   /* List of types that will be considered a subclass of CoglTexture in
      cogl_is_texture */
   GSList           *texture_types;
diff --git a/cogl/cogl-context.c b/cogl/cogl-context.c
index 4ab37e25..2674b235 100644
--- a/cogl/cogl-context.c
+++ b/cogl/cogl-context.c
@@ -276,6 +276,8 @@ cogl_context_new (CoglDisplay *display,
   context->current_vertex_program_type = COGL_PIPELINE_PROGRAM_TYPE_FIXED;
   context->current_gl_program = 0;
 
+  context->current_gl_dither_enabled = TRUE;
+
   context->gl_blend_enable_cache = FALSE;
 
   context->depth_test_enabled_cache = FALSE;
diff --git a/cogl/cogl-framebuffer-private.h b/cogl/cogl-framebuffer-private.h
index 509dc19b..1b0ee444 100644
--- a/cogl/cogl-framebuffer-private.h
+++ b/cogl/cogl-framebuffer-private.h
@@ -74,6 +74,8 @@ struct _CoglFramebuffer
   int                 green_bits;
   int                 alpha_bits;
 
+  gboolean            dither_enabled;
+
   /* We journal the textured rectangles we want to submit to OpenGL so
    * we have an oppertunity to batch them together into less draw
    * calls. */
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index 0d718832..af8cc9a2 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -148,6 +148,7 @@ _cogl_framebuffer_init (CoglFramebuffer *framebuffer,
   framebuffer->viewport_y       = 0;
   framebuffer->viewport_width   = width;
   framebuffer->viewport_height  = height;
+  framebuffer->dither_enabled   = TRUE;
 
   framebuffer->modelview_stack  = _cogl_matrix_stack_new ();
   framebuffer->projection_stack = _cogl_matrix_stack_new ();
@@ -1436,6 +1437,15 @@ _cogl_framebuffer_flush_state (CoglFramebuffer *draw_buffer,
   _cogl_framebuffer_init_bits (draw_buffer);
   _cogl_framebuffer_init_bits (read_buffer);
 
+  if (ctx->current_gl_dither_enabled != draw_buffer->dither_enabled)
+    {
+      if (draw_buffer->dither_enabled)
+        GE (ctx, glEnable (GL_DITHER));
+      else
+        GE (ctx, glDisable (GL_DITHER));
+      ctx->current_gl_dither_enabled = draw_buffer->dither_enabled;
+    }
+
   /* XXX: Flushing clip state may trash the modelview and projection
    * matrices so we must do it before flushing the matrices...
    */
@@ -1483,6 +1493,23 @@ cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer)
 }
 
 gboolean
+cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer)
+{
+  return framebuffer->dither_enabled;
+}
+
+void
+cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
+                                     gboolean dither_enabled)
+{
+  if (framebuffer->dither_enabled == dither_enabled)
+    return;
+
+  cogl_flush (); /* Currently dithering changes aren't tracked in the journal */
+  framebuffer->dither_enabled = dither_enabled;
+}
+
+gboolean
 _cogl_framebuffer_try_fast_read_pixel (CoglFramebuffer *framebuffer,
                                        int x,
                                        int y,
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index 77df4344..df8f8307 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -185,6 +185,48 @@ cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer);
 int
 cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer);
 
+/**
+ * cogl_framebuffer_get_dither_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ *
+ * Returns whether dithering has been requested for the given @framebuffer.
+ * See cogl_framebuffer_set_dither_enabled() for more details about dithering.
+ *
+ * <note>This may return %TRUE even when the underlying @framebuffer
+ * display pipeline does not support dithering. This value only represents
+ * the user's request for dithering.</note>
+ *
+ * Return value: %TRUE if dithering has been requested or %FALSE if not.
+ */
+gboolean
+cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer);
+
+/**
+ * cogl_framebuffer_set_dither_enabled:
+ * @framebuffer: a pointer to a #CoglFramebuffer
+ * @dither_enabled: %TRUE to enable dithering or %FALSE to disable
+ *
+ * Enables or disabled dithering if supported by the hardware.
+ *
+ * Dithering is a hardware dependent technique to increase the visible
+ * color resolution beyond what the underlying hardware supports by playing
+ * tricks with the colors placed into the framebuffer to give the illusion
+ * of other colors. (For example this can be compared to half-toning used
+ * by some news papers to show varying levels of grey even though their may
+ * only be black and white are available).
+ *
+ * If the current display pipeline for @framebuffer does not support dithering
+ * then this has no affect.
+ *
+ * Dithering is enabled by default.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
+void
+cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
+                                     gboolean dither_enabled);
+
 #define cogl_framebuffer_swap_buffers cogl_framebuffer_swap_buffers_EXP
 void
 cogl_framebuffer_swap_buffers (CoglFramebuffer *framebuffer);