GNOME.org
 

[cogl] offscreen: rename _new_to_texture to _new_with_texture

commit ecc6d2f64481626992b2fe6cdfa7b999270b28f5
Author: Robert Bragg <robert linux intel com>
Date:   Fri Aug 16 23:02:35 2013 +0100

    offscreen: rename _new_to_texture to _new_with_texture
    
    This renames cogl_offscreen_new_to_texture to
    cogl_offscreen_new_with_texture. The intention is to then cherry-pick
    this back to the cogl-1.16 branch so we can maintain a parallel
    cogl_offscreen_new_to_texture() function which keeps the synchronous
    allocation semantics that some clutter applications are currently
    relying on.
    
    Reviewed-by: Neil Roberts <neil linux intel com>

 cogl/cogl-blit.c                          |    8 +++---
 cogl/cogl-framebuffer-private.h           |   12 +++++-----
 cogl/cogl-framebuffer.c                   |   10 ++++----
 cogl/cogl-framebuffer.h                   |    4 +-
 cogl/cogl-gles2-context.c                 |    2 +-
 cogl/cogl-offscreen.h                     |   35 +++++++++++++++++++---------
 cogl/cogl-texture.c                       |    2 +-
 cogl/cogl.symbols                         |    2 +-
 doc/reference/cogl2/cogl2-sections.txt    |    2 +-
 examples/cogl-gles2-context.c             |    2 +-
 examples/cogl-msaa.c                      |    2 +-
 test-fixtures/test-utils.c                |    2 +-
 tests/conform/test-backface-culling.c     |    2 +-
 tests/conform/test-color-mask.c           |    2 +-
 tests/conform/test-framebuffer-get-bits.c |    4 +-
 tests/conform/test-gles2-context.c        |    4 +-
 tests/conform/test-offscreen.c            |    4 +-
 tests/conform/test-readpixels.c           |    2 +-
 tests/conform/test-viewport.c             |    2 +-
 19 files changed, 58 insertions(+), 45 deletions(-)
---
diff --git a/cogl/cogl-blit.c b/cogl/cogl-blit.c
index 6aaaf7d..09338de 100644
--- a/cogl/cogl-blit.c
+++ b/cogl/cogl-blit.c
@@ -50,7 +50,7 @@ _cogl_blit_texture_render_begin (CoglBlitData *data)
   unsigned int dst_width, dst_height;
   CoglError *ignore_error = NULL;
 
-  offscreen = _cogl_offscreen_new_to_texture_full
+  offscreen = _cogl_offscreen_new_with_texture_full
     (data->dst_tex, COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL, 0 /* level */);
 
   fb = COGL_FRAMEBUFFER (offscreen);
@@ -155,7 +155,7 @@ _cogl_blit_framebuffer_begin (CoglBlitData *data)
       !(ctx->private_feature_flags & COGL_PRIVATE_FEATURE_OFFSCREEN_BLIT))
     return FALSE;
 
-  dst_offscreen = _cogl_offscreen_new_to_texture_full
+  dst_offscreen = _cogl_offscreen_new_with_texture_full
     (data->dst_tex, COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL, 0 /* level */);
 
   dst_fb = COGL_FRAMEBUFFER (dst_offscreen);
@@ -165,7 +165,7 @@ _cogl_blit_framebuffer_begin (CoglBlitData *data)
       goto error;
     }
 
-  src_offscreen= _cogl_offscreen_new_to_texture_full
+  src_offscreen= _cogl_offscreen_new_with_texture_full
     (data->src_tex,
      COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL,
      0 /* level */);
@@ -226,7 +226,7 @@ _cogl_blit_copy_tex_sub_image_begin (CoglBlitData *data)
   if (!cogl_is_texture_2d (data->dst_tex))
     return FALSE;
 
-  offscreen = _cogl_offscreen_new_to_texture_full
+  offscreen = _cogl_offscreen_new_with_texture_full
     (data->src_tex, COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL, 0 /* level */);
 
   fb = COGL_FRAMEBUFFER (offscreen);
diff --git a/cogl/cogl-framebuffer-private.h b/cogl/cogl-framebuffer-private.h
index d56a1b3..7513412 100644
--- a/cogl/cogl-framebuffer-private.h
+++ b/cogl/cogl-framebuffer-private.h
@@ -56,7 +56,7 @@ typedef struct
   CoglBool depth_texture_enabled;
 } CoglFramebufferConfig;
 
-/* Flags to pass to _cogl_offscreen_new_to_texture_full */
+/* Flags to pass to _cogl_offscreen_new_with_texture_full */
 typedef enum
 {
   COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL = 1
@@ -209,7 +209,7 @@ struct _CoglOffscreen
 
   CoglOffscreenAllocateFlags allocation_flags;
 
-  /* FIXME: _cogl_offscreen_new_to_texture_full should be made to use
+  /* FIXME: _cogl_offscreen_new_with_texture_full should be made to use
    * fb->config to configure if we want a depth or stencil buffer so
    * we can get rid of these flags */
   CoglOffscreenFlags create_flags;
@@ -293,7 +293,7 @@ _cogl_framebuffer_flush_state (CoglFramebuffer *draw_buffer,
                                CoglFramebufferState state);
 
 /*
- * _cogl_offscreen_new_to_texture_full:
+ * _cogl_offscreen_new_with_texture_full:
  * @texture: A #CoglTexture pointer
  * @create_flags: Flags specifying how to create the FBO
  * @level: The mipmap level within the texture to target
@@ -306,9 +306,9 @@ _cogl_framebuffer_flush_state (CoglFramebuffer *draw_buffer,
  * Return value: the new CoglOffscreen object.
  */
 CoglOffscreen *
-_cogl_offscreen_new_to_texture_full (CoglTexture *texture,
-                                     CoglOffscreenFlags create_flags,
-                                     int level);
+_cogl_offscreen_new_with_texture_full (CoglTexture *texture,
+                                       CoglOffscreenFlags create_flags,
+                                       int level);
 
 /*
  * _cogl_push_framebuffers:
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index 32e6278..b98719c 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -568,9 +568,9 @@ _cogl_framebuffer_flush_dependency_journals (CoglFramebuffer *framebuffer)
 }
 
 CoglOffscreen *
-_cogl_offscreen_new_to_texture_full (CoglTexture *texture,
-                                     CoglOffscreenFlags create_flags,
-                                     int level)
+_cogl_offscreen_new_with_texture_full (CoglTexture *texture,
+                                       CoglOffscreenFlags create_flags,
+                                       int level)
 {
   CoglContext *ctx = texture->context;
   CoglOffscreen *offscreen;
@@ -613,9 +613,9 @@ _cogl_offscreen_new_to_texture_full (CoglTexture *texture,
 }
 
 CoglOffscreen *
-cogl_offscreen_new_to_texture (CoglTexture *texture)
+cogl_offscreen_new_with_texture (CoglTexture *texture)
 {
-  return _cogl_offscreen_new_to_texture_full (texture, 0, 0);
+  return _cogl_offscreen_new_with_texture_full (texture, 0, 0);
 }
 
 static void
diff --git a/cogl/cogl-framebuffer.h b/cogl/cogl-framebuffer.h
index 508b2cf..2ad41f8 100644
--- a/cogl/cogl-framebuffer.h
+++ b/cogl/cogl-framebuffer.h
@@ -68,7 +68,7 @@ COGL_BEGIN_DECLS
  *
  * If you want to create a new framebuffer then you should start by
  * looking at the #CoglOnscreen and #CoglOffscreen constructor
- * functions, such as cogl_offscreen_new_to_texture() or
+ * functions, such as cogl_offscreen_new_with_texture() or
  * cogl_onscreen_new(). The #CoglFramebuffer interface deals with
  * all aspects that are common between those two types of framebuffer.
  *
@@ -787,7 +787,7 @@ cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
  *
  * Queries the common #CoglPixelFormat of all color buffers attached
  * to this framebuffer. For an offscreen framebuffer created with
- * cogl_offscreen_new_to_texture() this will correspond to the format
+ * cogl_offscreen_new_with_texture() this will correspond to the format
  * of the texture.
  *
  * Since: 1.8
diff --git a/cogl/cogl-gles2-context.c b/cogl/cogl-gles2-context.c
index d270f7c..82ae324 100644
--- a/cogl/cogl-gles2-context.c
+++ b/cogl/cogl-gles2-context.c
@@ -325,7 +325,7 @@ copy_flipped_texture (CoglGLES2Context *gles2_ctx,
       CoglPipeline *pipeline = cogl_pipeline_new (ctx);
       const CoglOffscreenFlags flags = COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL;
       CoglOffscreen *offscreen =
-        _cogl_offscreen_new_to_texture_full (COGL_TEXTURE (dst_texture),
+        _cogl_offscreen_new_with_texture_full (COGL_TEXTURE (dst_texture),
                                              flags, level);
       int src_width = cogl_texture_get_width (src_texture);
       int src_height = cogl_texture_get_height (src_texture);
diff --git a/cogl/cogl-offscreen.h b/cogl/cogl-offscreen.h
index 104358c..5bb8a2f 100644
--- a/cogl/cogl-offscreen.h
+++ b/cogl/cogl-offscreen.h
@@ -48,26 +48,39 @@ typedef struct _CoglOffscreen CoglOffscreen;
 /* Offscreen api */
 
 /**
- * cogl_offscreen_new_to_texture:
+ * cogl_offscreen_new_with_texture:
  * @texture: A #CoglTexture pointer
  *
- * This creates an offscreen buffer object using the given @texture as the
- * primary color buffer. It doesn't just initialize the contents of the
- * offscreen buffer with the @texture; they are tightly bound so that
- * drawing to the offscreen buffer effectivly updates the contents of the
- * given texture. You don't need to destroy the offscreen buffer before
- * you can use the @texture again.
+ * This creates an offscreen framebuffer object using the given
+ * @texture as the primary color buffer. It doesn't just initialize
+ * the contents of the offscreen buffer with the @texture; they are
+ * tightly bound so that drawing to the offscreen buffer effectively
+ * updates the contents of the given texture. You don't need to
+ * destroy the offscreen buffer before you can use the @texture again.
  *
- * <note>This only works with low-level #CoglTexture types such as
+ * <note>This api only works with low-level #CoglTexture types such as
  * #CoglTexture2D, #CoglTexture3D and #CoglTextureRectangle, and not
  * with meta-texture types such as #CoglTexture2DSliced.</note>
  *
+ * The storage for the framebuffer is actually allocated lazily
+ * so this function will never return %NULL to indicate a runtime
+ * error. This means it is still possible to configure the framebuffer
+ * before it is really allocated.
+ *
+ * Simple applications without full error handling can simply rely on
+ * Cogl to lazily allocate the storage of framebuffers but you should
+ * be aware that if Cogl encounters an error (such as running out of
+ * GPU memory) then your application will simply abort with an error
+ * message. If you need to be able to catch such exceptions at runtime
+ * then you can explicitly allocate your framebuffer when you have
+ * finished configuring it by calling cogl_framebuffer_allocate() and
+ * passing in a #CoglError argument to catch any exceptions.
+ *
  * Return value: (transfer full): a newly instantiated #CoglOffscreen
- *   framebuffer or %NULL if it wasn't possible to create the
- *   buffer.
+ *   framebuffer.
  */
 CoglOffscreen *
-cogl_offscreen_new_to_texture (CoglTexture *texture);
+cogl_offscreen_new_with_texture (CoglTexture *texture);
 
 /**
  * cogl_is_offscreen:
diff --git a/cogl/cogl-texture.c b/cogl/cogl-texture.c
index 64398f4..0b77a17 100644
--- a/cogl/cogl-texture.c
+++ b/cogl/cogl-texture.c
@@ -718,7 +718,7 @@ get_texture_bits_via_offscreen (CoglTexture    *texture,
   if (!cogl_has_feature (ctx, COGL_FEATURE_ID_OFFSCREEN))
     return FALSE;
 
-  offscreen = _cogl_offscreen_new_to_texture_full
+  offscreen = _cogl_offscreen_new_with_texture_full
                                       (texture,
                                        COGL_OFFSCREEN_DISABLE_DEPTH_AND_STENCIL,
                                        0);
diff --git a/cogl/cogl.symbols b/cogl/cogl.symbols
index 70b83c3..f4df15e 100644
--- a/cogl/cogl.symbols
+++ b/cogl/cogl.symbols
@@ -340,7 +340,7 @@ cogl_object_ref
 cogl_object_set_user_data
 cogl_object_unref
 
-cogl_offscreen_new_to_texture
+cogl_offscreen_new_with_texture
 
 cogl_onscreen_add_swap_buffers_callback
 #ifndef COGL_WINSYS_INTEGRATED
diff --git a/doc/reference/cogl2/cogl2-sections.txt b/doc/reference/cogl2/cogl2-sections.txt
index 4354d0b..b706c16 100644
--- a/doc/reference/cogl2/cogl2-sections.txt
+++ b/doc/reference/cogl2/cogl2-sections.txt
@@ -581,7 +581,7 @@ CoglOffscreen
 cogl_is_offscreen
 
 <SUBSECTION>
-cogl_offscreen_new_to_texture
+cogl_offscreen_new_with_texture
 </SECTION>
 
 <SECTION>
diff --git a/examples/cogl-gles2-context.c b/examples/cogl-gles2-context.c
index f696dca..4f4fbfa 100644
--- a/examples/cogl-gles2-context.c
+++ b/examples/cogl-gles2-context.c
@@ -100,7 +100,7 @@ main (int argc, char **argv)
                                      OFFSCREEN_WIDTH,
                                      OFFSCREEN_HEIGHT,
                                      COGL_PIXEL_FORMAT_ANY));
-    data.offscreen = cogl_offscreen_new_to_texture (data.offscreen_texture);
+    data.offscreen = cogl_offscreen_new_with_texture (data.offscreen_texture);
 
     data.gles2_ctx = cogl_gles2_context_new (data.ctx, &error);
     if (!data.gles2_ctx) {
diff --git a/examples/cogl-msaa.c b/examples/cogl-msaa.c
index 2c527b8..f1a0b96 100644
--- a/examples/cogl-msaa.c
+++ b/examples/cogl-msaa.c
@@ -65,7 +65,7 @@ main (int argc, char **argv)
     tex = COGL_TEXTURE (cogl_texture_2d_new_with_size (ctx,
                                                        320, 480,
                                                        COGL_PIXEL_FORMAT_ANY));
-    offscreen = cogl_offscreen_new_to_texture (tex);
+    offscreen = cogl_offscreen_new_with_texture (tex);
     offscreen_fb = COGL_FRAMEBUFFER (offscreen);
     cogl_framebuffer_set_samples_per_pixel (offscreen_fb, 4);
     if (!cogl_framebuffer_allocate (offscreen_fb, &error))
diff --git a/test-fixtures/test-utils.c b/test-fixtures/test-utils.c
index 8e2b00b..1948922 100644
--- a/test-fixtures/test-utils.c
+++ b/test-fixtures/test-utils.c
@@ -179,7 +179,7 @@ test_utils_init (TestFlags requirement_flags,
       CoglTexture2D *tex = cogl_texture_2d_new_with_size (test_ctx,
                                                           FB_WIDTH, FB_HEIGHT,
                                                           COGL_PIXEL_FORMAT_ANY);
-      offscreen = cogl_offscreen_new_to_texture (COGL_TEXTURE (tex));
+      offscreen = cogl_offscreen_new_with_texture (COGL_TEXTURE (tex));
       test_fb = COGL_FRAMEBUFFER (offscreen);
     }
 
diff --git a/tests/conform/test-backface-culling.c b/tests/conform/test-backface-culling.c
index 723ea12..15d45a4 100644
--- a/tests/conform/test-backface-culling.c
+++ b/tests/conform/test-backface-culling.c
@@ -242,7 +242,7 @@ test_backface_culling (void)
                                           TEST_UTILS_TEXTURE_NO_SLICING,
                                           COGL_PIXEL_FORMAT_ANY); /* internal
                                                                      format */
-  state.offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_to_texture (tex));
+  state.offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_with_texture (tex));
   state.offscreen_tex = tex;
 
   paint (&state);
diff --git a/tests/conform/test-color-mask.c b/tests/conform/test-color-mask.c
index a6689d1..62b89d8 100644
--- a/tests/conform/test-color-mask.c
+++ b/tests/conform/test-color-mask.c
@@ -87,7 +87,7 @@ test_color_mask (void)
 
 
       state.fbo[i] = COGL_FRAMEBUFFER (
-        cogl_offscreen_new_to_texture (state.tex[i]));
+        cogl_offscreen_new_with_texture (state.tex[i]));
 
       /* Clear the texture color bits */
       cogl_framebuffer_clear4f (state.fbo[i],
diff --git a/tests/conform/test-framebuffer-get-bits.c b/tests/conform/test-framebuffer-get-bits.c
index ac7ab52..f1a85b2 100644
--- a/tests/conform/test-framebuffer-get-bits.c
+++ b/tests/conform/test-framebuffer-get-bits.c
@@ -10,14 +10,14 @@ test_framebuffer_get_bits (void)
                                    16, 16, /* width/height */
                                    COGL_PIXEL_FORMAT_A_8);
   CoglOffscreen *offscreen_a =
-    cogl_offscreen_new_to_texture (COGL_TEXTURE (tex_a));
+    cogl_offscreen_new_with_texture (COGL_TEXTURE (tex_a));
   CoglFramebuffer *fb_a = COGL_FRAMEBUFFER (offscreen_a);
   CoglTexture2D *tex_rgba =
     cogl_texture_2d_new_with_size (test_ctx,
                                    16, 16, /* width/height */
                                    COGL_PIXEL_FORMAT_RGBA_8888);
   CoglOffscreen *offscreen_rgba =
-    cogl_offscreen_new_to_texture (COGL_TEXTURE (tex_rgba));
+    cogl_offscreen_new_with_texture (COGL_TEXTURE (tex_rgba));
   CoglFramebuffer *fb_rgba = COGL_FRAMEBUFFER (offscreen_rgba);
 
   cogl_framebuffer_allocate (fb_a, NULL);
diff --git a/tests/conform/test-gles2-context.c b/tests/conform/test-gles2-context.c
index 7b5f0fc..212b97c 100644
--- a/tests/conform/test-gles2-context.c
+++ b/tests/conform/test-gles2-context.c
@@ -28,7 +28,7 @@ test_push_pop_single_context (void)
                                    cogl_framebuffer_get_width (test_fb),
                                    cogl_framebuffer_get_height (test_fb),
                                    COGL_PIXEL_FORMAT_ANY));
-  offscreen = cogl_offscreen_new_to_texture (offscreen_texture);
+  offscreen = cogl_offscreen_new_with_texture (offscreen_texture);
 
   pipeline = cogl_pipeline_new (test_ctx);
   cogl_pipeline_set_layer_texture (pipeline, 0, offscreen_texture);
@@ -152,7 +152,7 @@ create_gles2_context (CoglTexture **offscreen_texture,
                                    cogl_framebuffer_get_width (test_fb),
                                    cogl_framebuffer_get_height (test_fb),
                                    COGL_PIXEL_FORMAT_ANY));
-  *offscreen = cogl_offscreen_new_to_texture (*offscreen_texture);
+  *offscreen = cogl_offscreen_new_with_texture (*offscreen_texture);
 
   *pipeline = cogl_pipeline_new (test_ctx);
   cogl_pipeline_set_layer_texture (*pipeline, 0, *offscreen_texture);
diff --git a/tests/conform/test-offscreen.c b/tests/conform/test-offscreen.c
index cde2464..faa08a7 100644
--- a/tests/conform/test-offscreen.c
+++ b/tests/conform/test-offscreen.c
@@ -50,7 +50,7 @@ test_paint (TestState *state)
                                           COGL_PIXEL_FORMAT_RGBA_8888_PRE);
   tex = COGL_TEXTURE (tex_2d);
 
-  offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_to_texture (tex));
+  offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_with_texture (tex));
 
   /* Set a scale and translate transform on the window framebuffer
    * before switching to the offscreen framebuffer so we can verify it
@@ -130,7 +130,7 @@ test_flush (TestState *state)
                                               COGL_PIXEL_FORMAT_RGBA_8888_PRE);
       tex = COGL_TEXTURE (tex_2d);
 
-      offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_to_texture (tex));
+      offscreen = COGL_FRAMEBUFFER (cogl_offscreen_new_with_texture (tex));
 
       cogl_framebuffer_clear4f (offscreen, COGL_BUFFER_BIT_COLOR,
                                 0, 0, 0, 1);
diff --git a/tests/conform/test-readpixels.c b/tests/conform/test-readpixels.c
index f543fb0..131b08b 100644
--- a/tests/conform/test-readpixels.c
+++ b/tests/conform/test-readpixels.c
@@ -51,7 +51,7 @@ on_paint (ClutterActor *actor, void *state)
                                     FRAMEBUFFER_WIDTH * 4, /* rowstride */
                                     data);
   g_free (data);
-  offscreen = cogl_offscreen_new_to_texture (tex);
+  offscreen = cogl_offscreen_new_with_texture (tex);
 
   cogl_push_framebuffer (offscreen);
 
diff --git a/tests/conform/test-viewport.c b/tests/conform/test-viewport.c
index c437ec7..a1937c4 100644
--- a/tests/conform/test-viewport.c
+++ b/tests/conform/test-viewport.c
@@ -217,7 +217,7 @@ on_paint (ClutterActor *actor, void *state)
                                     FRAMEBUFFER_WIDTH * 4, /* rowstride */
                                     data);
   g_free (data);
-  offscreen = cogl_offscreen_new_to_texture (tex);
+  offscreen = cogl_offscreen_new_with_texture (tex);
 
   cogl_push_framebuffer (offscreen);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]