cogl/cogl-framebuffer.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2011 Intel Corporation.
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see
  20  * <http://www.gnu.org/licenses/>.
  21  *
  22  *
  23  *
  24  * Authors:
  25  *   Robert Bragg <robert@linux.intel.com>
  26  */
  27
  28 #ifndef __COGL_FRAMEBUFFER_H
  29 #define __COGL_FRAMEBUFFER_H
  30
  31 #include <glib.h>
  32
  33 #ifdef COGL_HAS_WIN32_SUPPORT
  34 #include <windows.h>
  35 #endif /* COGL_HAS_WIN32_SUPPORT */
  36
  37 #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API
  38 #include <cogl/cogl2-path.h>
  39 #else
  40 #include <cogl/cogl-path.h>
  41 #endif
  42
  43 #include <cogl/cogl-pipeline.h>
  44 #include <cogl/cogl-indices.h>
  45 #include <cogl/cogl-bitmap.h>
  46
  47 G_BEGIN_DECLS
  48
  49 /**
  50  * SECTION:cogl-framebuffer
  51  * @short_description: A common interface for manipulating framebuffers
  52  *
  53  * Framebuffers are a collection of buffers that can be rendered too.
  54  * A framebuffer may be comprised of one or more color buffers, an
  55  * optional depth buffer and an optional stencil buffer. Other
  56  * configuration parameters are associated with framebuffers too such
  57  * as whether the framebuffer supports multi-sampling (an anti-aliasing
  58  * technique) or dithering.
  59  *
  60  * There are two kinds of framebuffer in Cogl, #CoglOnscreen
  61  * framebuffers and #CoglOffscreen framebuffers. As the names imply
  62  * offscreen framebuffers are for rendering something offscreen
  63  * (perhaps to a texture which is bound as one of the color buffers).
  64  * The exact semantics of onscreen framebuffers depends on the window
  65  * system backend that you are using, but typically you can expect
  66  * rendering to a #CoglOnscreen framebuffer will be immediately
  67  * visible to the user.
  68  *
  69  * If you want to create a new framebuffer then you should start by
  70  * looking at the #CoglOnscreen and #CoglOffscreen constructor
  71  * functions, such as cogl_offscreen_new_to_texture() or
  72  * cogl_onscreen_new(). The #CoglFramebuffer interface deals with
  73  * all aspects that are common between those two types of framebuffer.
  74  *
  75  * Setup of a new CoglFramebuffer happens in two stages. There is a
  76  * configuration stage where you specify all the options and ancillary
  77  * buffers you want associated with your framebuffer and then when you
  78  * are happy with the configuration you can "allocate" the framebuffer
  79  * using cogl_framebuffer_allocate(). Technically explicitly calling
  80  * cogl_framebuffer_allocate() is optional for convenience and the
  81  * framebuffer will automatically be allocated when you first try to
  82  * draw to it, but if you do the allocation manually then you can
  83  * also catch any possible errors that may arise from your
  84  * configuration.
  85  */
  86
  87 typedef struct _CoglFramebuffer CoglFramebuffer;
  88
  89 #ifdef COGL_ENABLE_EXPERIMENTAL_API
  90
  91 #define COGL_FRAMEBUFFER(X) ((CoglFramebuffer *)(X))
  92
  93 /**
  94  * cogl_framebuffer_allocate:
  95  * @framebuffer: A #CoglFramebuffer
  96  * @error: A pointer to a #GError for returning exceptions.
  97  *
  98  * Explicitly allocates a configured #CoglFramebuffer allowing developers to
  99  * check and handle any errors that might arise from an unsupported
 100  * configuration so that fallback configurations may be tried.
 101  *
 102  * <note>Many applications don't support any fallback options at least when
 103  * they are initially developed and in that case the don't need to use this API
 104  * since Cogl will automatically allocate a framebuffer when it first gets
 105  * used.  The disadvantage of relying on automatic allocation is that the
 106  * program will abort with an error message if there is an error during
 107  * automatic allocation.</note>
 108  *
 109  * Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE.
 110  * Since: 1.8
 111  * Stability: unstable
 112  */
 113 gboolean
 114 cogl_framebuffer_allocate (CoglFramebuffer *framebuffer,
 115                            GError **error);
 116
 117 /**
 118  * cogl_framebuffer_get_width:
 119  * @framebuffer: A #CoglFramebuffer
 120  *
 121  * Queries the current width of the given @framebuffer.
 122  *
 123  * Return value: The width of @framebuffer.
 124  * Since: 1.8
 125  * Stability: unstable
 126  */
 127 int
 128 cogl_framebuffer_get_width (CoglFramebuffer *framebuffer);
 129
 130 /**
 131  * cogl_framebuffer_get_height:
 132  * @framebuffer: A #CoglFramebuffer
 133  *
 134  * Queries the current height of the given @framebuffer.
 135  *
 136  * Return value: The height of @framebuffer.
 137  * Since: 1.8
 138  * Stability: unstable
 139  */
 140 int
 141 cogl_framebuffer_get_height (CoglFramebuffer *framebuffer);
 142
 143 /**
 144  * cogl_framebuffer_set_viewport:
 145  * @framebuffer: A #CoglFramebuffer
 146  * @x: The top-left x coordinate of the viewport origin (only integers
 147  *     supported currently)
 148  * @y: The top-left y coordinate of the viewport origin (only integers
 149  *     supported currently)
 150  * @width: The width of the viewport (only integers supported currently)
 151  * @height: The height of the viewport (only integers supported currently)
 152  *
 153  * Defines a scale and offset for everything rendered relative to the
 154  * top-left of the destination framebuffer.
 155  *
 156  * By default the viewport has an origin of (0,0) and width and height
 157  * that match the framebuffer's size. Assuming a default projection and
 158  * modelview matrix then you could translate the contents of a window
 159  * down and right by leaving the viewport size unchanged by moving the
 160  * offset to (10,10). The viewport coordinates are measured in pixels.
 161  * If you left the x and y origin as (0,0) you could scale the windows
 162  * contents down by specify and width and height that's half the real
 163  * size of the framebuffer.
 164  *
 165  * <note>Although the function takes floating point arguments, existing
 166  * drivers only allow the use of integer values. In the future floating
 167  * point values will be exposed via a checkable feature.</note>
 168  *
 169  * Since: 1.8
 170  * Stability: unstable
 171  */
 172 void
 173 cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer,
 174                                float x,
 175                                float y,
 176                                float width,
 177                                float height);
 178
 179 /**
 180  * cogl_framebuffer_get_viewport_x:
 181  * @framebuffer: A #CoglFramebuffer
 182  *
 183  * Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
 184  * or the default value which is %0.
 185  *
 186  * Return value: The x coordinate of the viewport origin.
 187  * Since: 1.8
 188  * Stability: unstable
 189  */
 190 float
 191 cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer);
 192
 193 /**
 194  * cogl_framebuffer_get_viewport_y:
 195  * @framebuffer: A #CoglFramebuffer
 196  *
 197  * Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport()
 198  * or the default value which is %0.
 199  *
 200  * Return value: The y coordinate of the viewport origin.
 201  * Since: 1.8
 202  * Stability: unstable
 203  */
 204 float
 205 cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer);
 206
 207 /**
 208  * cogl_framebuffer_get_viewport_width:
 209  * @framebuffer: A #CoglFramebuffer
 210  *
 211  * Queries the width of the viewport as set using cogl_framebuffer_set_viewport()
 212  * or the default value which is the width of the framebuffer.
 213  *
 214  * Return value: The width of the viewport.
 215  * Since: 1.8
 216  * Stability: unstable
 217  */
 218 float
 219 cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer);
 220
 221 /**
 222  * cogl_framebuffer_get_viewport_height:
 223  * @framebuffer: A #CoglFramebuffer
 224  *
 225  * Queries the height of the viewport as set using cogl_framebuffer_set_viewport()
 226  * or the default value which is the height of the framebuffer.
 227  *
 228  * Return value: The height of the viewport.
 229  * Since: 1.8
 230  * Stability: unstable
 231  */
 232 float
 233 cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer);
 234
 235 /**
 236  * cogl_framebuffer_get_viewport4fv:
 237  * @framebuffer: A #CoglFramebuffer
 238  * @viewport: A pointer to an array of 4 floats to receive the (x, y, width, height)
 239  *            components of the current viewport.
 240  *
 241  * Queries the x, y, width and height components of the current viewport as set
 242  * using cogl_framebuffer_set_viewport() or the default values which are 0, 0,
 243  * framebuffer_width and framebuffer_height.  The values are written into the
 244  * given @viewport array.
 245  *
 246  * Since: 1.8
 247  * Stability: unstable
 248  */
 249 void
 250 cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer,
 251                                   float *viewport);
 252
 253 /**
 254  * cogl_framebuffer_push_matrix:
 255  * @framebuffer: A #CoglFramebuffer pointer
 256  *
 257  * Copies the current model-view matrix onto the matrix stack. The matrix
 258  * can later be restored with cogl_framebuffer_pop_matrix().
 259  *
 260  * Since: 1.10
 261  */
 262 void
 263 cogl_framebuffer_push_matrix (CoglFramebuffer *framebuffer);
 264
 265 /**
 266  * cogl_framebuffer_pop_matrix:
 267  * @framebuffer: A #CoglFramebuffer pointer
 268  *
 269  * Restores the model-view matrix on the top of the matrix stack.
 270  *
 271  * Since: 1.10
 272  */
 273 void
 274 cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer);
 275
 276 /**
 277  * cogl_framebuffer_identity_matrix:
 278  * @framebuffer: A #CoglFramebuffer pointer
 279  *
 280  * Resets the current model-view matrix to the identity matrix.
 281  *
 282  * Since: 1.10
 283  * Stability: unstable
 284  */
 285 void
 286 cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer);
 287
 288 /**
 289  * cogl_framebuffer_scale:
 290  * @framebuffer: A #CoglFramebuffer pointer
 291  * @x: Amount to scale along the x-axis
 292  * @y: Amount to scale along the y-axis
 293  * @z: Amount to scale along the z-axis
 294  *
 295  * Multiplies the current model-view matrix by one that scales the x,
 296  * y and z axes by the given values.
 297  *
 298  * Since: 1.10
 299  * Stability: unstable
 300  */
 301 void
 302 cogl_framebuffer_scale (CoglFramebuffer *framebuffer,
 303                         float x,
 304                         float y,
 305                         float z);
 306
 307 /**
 308  * cogl_framebuffer_translate:
 309  * @framebuffer: A #CoglFramebuffer pointer
 310  * @x: Distance to translate along the x-axis
 311  * @y: Distance to translate along the y-axis
 312  * @z: Distance to translate along the z-axis
 313  *
 314  * Multiplies the current model-view matrix by one that translates the
 315  * model along all three axes according to the given values.
 316  *
 317  * Since: 1.10
 318  * Stability: unstable
 319  */
 320 void
 321 cogl_framebuffer_translate (CoglFramebuffer *framebuffer,
 322                             float x,
 323                             float y,
 324                             float z);
 325
 326 /**
 327  * cogl_framebuffer_rotate:
 328  * @framebuffer: A #CoglFramebuffer pointer
 329  * @angle: Angle in degrees to rotate.
 330  * @x: X-component of vertex to rotate around.
 331  * @y: Y-component of vertex to rotate around.
 332  * @z: Z-component of vertex to rotate around.
 333  *
 334  * Multiplies the current model-view matrix by one that rotates the
 335  * model around the vertex specified by @x, @y and @z. The rotation
 336  * follows the right-hand thumb rule so for example rotating by 10
 337  * degrees about the vertex (0, 0, 1) causes a small counter-clockwise
 338  * rotation.
 339  *
 340  * Since: 1.10
 341  * Stability: unstable
 342  */
 343 void
 344 cogl_framebuffer_rotate (CoglFramebuffer *framebuffer,
 345                          float angle,
 346                          float x,
 347                          float y,
 348                          float z);
 349
 350 /**
 351  * cogl_framebuffer_transform:
 352  * @framebuffer: A #CoglFramebuffer pointer
 353  * @matrix: the matrix to multiply with the current model-view
 354  *
 355  * Multiplies the current model-view matrix by the given matrix.
 356  *
 357  * Since: 1.10
 358  * Stability: unstable
 359  */
 360 void
 361 cogl_framebuffer_transform (CoglFramebuffer *framebuffer,
 362                             const CoglMatrix *matrix);
 363
 364 /**
 365  * cogl_framebuffer_get_modelview_matrix:
 366  * @framebuffer: A #CoglFramebuffer pointer
 367  * @matrix: (out): return location for the model-view matrix
 368  *
 369  * Stores the current model-view matrix in @matrix.
 370  *
 371  * Since: 1.10
 372  * Stability: unstable
 373  */
 374 void
 375 cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer,
 376                                        CoglMatrix *matrix);
 377
 378 /**
 379  * cogl_framebuffer_set_modelview_matrix:
 380  * @framebuffer: A #CoglFramebuffer pointer
 381  * @matrix: the new model-view matrix
 382  *
 383  * Sets @matrix as the new model-view matrix.
 384  *
 385  * Since: 1.10
 386  * Stability: unstable
 387  */
 388 void
 389 cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer,
 390                                        CoglMatrix *matrix);
 391
 392 /**
 393  * cogl_framebuffer_perspective:
 394  * @framebuffer: A #CoglFramebuffer pointer
 395  * @fov_y: Vertical field of view angle in degrees.
 396  * @aspect: The (width over height) aspect ratio for display
 397  * @z_near: The distance to the near clipping plane (Must be positive,
 398  *   and must not be 0)
 399  * @z_far: The distance to the far clipping plane (Must be positive)
 400  *
 401  * Replaces the current projection matrix with a perspective matrix
 402  * based on the provided values.
 403  *
 404  * <note>You should be careful not to have to great a @z_far / @z_near
 405  * ratio since that will reduce the effectiveness of depth testing
 406  * since there wont be enough precision to identify the depth of
 407  * objects near to each other.</note>
 408  *
 409  * Since: 1.10
 410  * Stability: unstable
 411  */
 412 void
 413 cogl_framebuffer_perspective (CoglFramebuffer *framebuffer,
 414                               float fov_y,
 415                               float aspect,
 416                               float z_near,
 417                               float z_far);
 418
 419 /**
 420  * cogl_framebuffer_frustum:
 421  * @framebuffer: A #CoglFramebuffer pointer
 422  * @left: X position of the left clipping plane where it
 423  *   intersects the near clipping plane
 424  * @right: X position of the right clipping plane where it
 425  *   intersects the near clipping plane
 426  * @bottom: Y position of the bottom clipping plane where it
 427  *   intersects the near clipping plane
 428  * @top: Y position of the top clipping plane where it intersects
 429  *   the near clipping plane
 430  * @z_near: The distance to the near clipping plane (Must be positive)
 431  * @z_far: The distance to the far clipping plane (Must be positive)
 432  *
 433  * Replaces the current projection matrix with a perspective matrix
 434  * for a given viewing frustum defined by 4 side clip planes that
 435  * all cross through the origin and 2 near and far clip planes.
 436  *
 437  * Since: 1.10
 438  * Stability: unstable
 439  */
 440 void
 441 cogl_framebuffer_frustum (CoglFramebuffer *framebuffer,
 442                           float left,
 443                           float right,
 444                           float bottom,
 445                           float top,
 446                           float z_near,
 447                           float z_far);
 448
 449 /**
 450  * cogl_framebuffer_orthographic:
 451  * @framebuffer: A #CoglFramebuffer pointer
 452  * @x_1: The x coordinate for the first vertical clipping plane
 453  * @y_1: The y coordinate for the first horizontal clipping plane
 454  * @x_2: The x coordinate for the second vertical clipping plane
 455  * @y_2: The y coordinate for the second horizontal clipping plane
 456  * @near: The <emphasis>distance</emphasis> to the near clipping
 457  *   plane (will be <emphasis>negative</emphasis> if the plane is
 458  *   behind the viewer)
 459  * @far: The <emphasis>distance</emphasis> to the far clipping
 460  *   plane (will be <emphasis>negative</emphasis> if the plane is
 461  *   behind the viewer)
 462  *
 463  * Replaces the current projection matrix with an orthographic projection
 464  * matrix.
 465  *
 466  * Since: 1.10
 467  * Stability: unstable
 468  */
 469 void
 470 cogl_framebuffer_orthographic (CoglFramebuffer *framebuffer,
 471                                float x_1,
 472                                float y_1,
 473                                float x_2,
 474                                float y_2,
 475                                float near,
 476                                float far);
 477
 478 /**
 479  * cogl_framebuffer_get_projection_matrix:
 480  * @framebuffer: A #CoglFramebuffer pointer
 481  * @matrix: (out): return location for the projection matrix
 482  *
 483  * Stores the current projection matrix in @matrix.
 484  *
 485  * Since: 1.10
 486  * Stability: unstable
 487  */
 488 void
 489 cogl_framebuffer_get_projection_matrix (CoglFramebuffer *framebuffer,
 490                                         CoglMatrix *matrix);
 491
 492 /**
 493  * cogl_framebuffer_set_projection_matrix:
 494  * @framebuffer: A #CoglFramebuffer pointer
 495  * @matrix: the new projection matrix
 496  *
 497  * Sets @matrix as the new projection matrix.
 498  *
 499  * Since: 1.10
 500  * Stability: unstable
 501  */
 502 void
 503 cogl_framebuffer_set_projection_matrix (CoglFramebuffer *framebuffer,
 504                                         CoglMatrix *matrix);
 505
 506 /**
 507  * cogl_framebuffer_push_scissor_clip:
 508  * @framebuffer: A #CoglFramebuffer pointer
 509  * @x: left edge of the clip rectangle in window coordinates
 510  * @y: top edge of the clip rectangle in window coordinates
 511  * @width: width of the clip rectangle
 512  * @height: height of the clip rectangle
 513  *
 514  * Specifies a rectangular clipping area for all subsequent drawing
 515  * operations. Any drawing commands that extend outside the rectangle
 516  * will be clipped so that only the portion inside the rectangle will
 517  * be displayed. The rectangle dimensions are not transformed by the
 518  * current model-view matrix.
 519  *
 520  * The rectangle is intersected with the current clip region. To undo
 521  * the effect of this function, call cogl_framebuffer_pop_clip().
 522  *
 523  * Since: 1.10
 524  * Stability: unstable
 525  */
 526 void
 527 cogl_framebuffer_push_scissor_clip (CoglFramebuffer *framebuffer,
 528                                     int x,
 529                                     int y,
 530                                     int width,
 531                                     int height);
 532
 533 /**
 534  * cogl_framebuffer_push_rectangle_clip:
 535  * @framebuffer: A #CoglFramebuffer pointer
 536  * @x_1: x coordinate for top left corner of the clip rectangle
 537  * @y_1: y coordinate for top left corner of the clip rectangle
 538  * @x_2: x coordinate for bottom right corner of the clip rectangle
 539  * @y_2: y coordinate for bottom right corner of the clip rectangle
 540  *
 541  * Specifies a modelview transformed rectangular clipping area for all
 542  * subsequent drawing operations. Any drawing commands that extend
 543  * outside the rectangle will be clipped so that only the portion
 544  * inside the rectangle will be displayed. The rectangle dimensions
 545  * are transformed by the current model-view matrix.
 546  *
 547  * The rectangle is intersected with the current clip region. To undo
 548  * the effect of this function, call cogl_framebuffer_pop_clip().
 549  *
 550  * Since: 1.10
 551  * Stability: unstable
 552  */
 553 void
 554 cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer,
 555                                       float x_1,
 556                                       float y_1,
 557                                       float x_2,
 558                                       float y_2);
 559
 560 /**
 561  * cogl_framebuffer_push_path_clip:
 562  * @framebuffer: A #CoglFramebuffer pointer
 563  * @path: The path to clip with.
 564  *
 565  * Sets a new clipping area using the silhouette of the specified,
 566  * filled @path.  The clipping area is intersected with the previous
 567  * clipping area. To restore the previous clipping area, call
 568  * cogl_framebuffer_pop_clip().
 569  *
 570  * Since: 1.0
 571  * Stability: unstable
 572  */
 573 void
 574 cogl_framebuffer_push_path_clip (CoglFramebuffer *framebuffer,
 575                                  CoglPath *path);
 576
 577 /**
 578  * cogl_framebuffer_push_primitive_clip:
 579  * @framebuffer: A #CoglFramebuffer pointer
 580  * @primitive: A #CoglPrimitive describing a flat 2D shape
 581  * @bounds_x1: x coordinate for the top-left corner of the primitives
 582  *             bounds
 583  * @bounds_y1: y coordinate for the top-left corner of the primitives
 584  *             bounds
 585  * @bounds_x2: x coordinate for the top-left corner of the primitives
 586  *             bounds
 587  * @bounds_y2: x coordinate for the bottom-right corner of the
 588  *             primitives bounds.
 589  * @bounds_x1: y coordinate for the bottom-right corner of the
 590  *             primitives bounds.
 591  *
 592  * Sets a new clipping area using a 2D shaped described with a
 593  * #CoglPrimitive. The shape must not contain self overlapping
 594  * geometry and must lie on a single 2D plane. A bounding box of the
 595  * 2D shape in local coordinates (the same coordinates used to
 596  * describe the shape) must be given. It is acceptable for the bounds
 597  * to be larger than the true bounds but behaviour is undefined if the
 598  * bounds are smaller than the true bounds.
 599  *
 600  * The primitive is transformed by the current model-view matrix and
 601  * the silhouette is intersected with the previous clipping area.  To
 602  * restore the previous clipping area, call
 603  * cogl_framebuffer_pop_clip().
 604  *
 605  * Since: 1.10
 606  * Stability: unstable
 607  */
 608 void
 609 cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer,
 610                                       CoglPrimitive *primitive,
 611                                       float bounds_x1,
 612                                       float bounds_y1,
 613                                       float bounds_x2,
 614                                       float bounds_y2);
 615
 616 /**
 617  * cogl_framebuffer_pop_clip:
 618  * @framebuffer: A #CoglFramebuffer pointer
 619  *
 620  * Reverts the clipping region to the state before the last call to
 621  * cogl_framebuffer_push_clip().
 622  *
 623  * Since: 1.10
 624  * Stability: unstable
 625  */
 626 void
 627 cogl_framebuffer_pop_clip (CoglFramebuffer *framebuffer);
 628
 629 /**
 630  * cogl_framebuffer_get_red_bits:
 631  * @framebuffer: a pointer to a #CoglFramebuffer
 632  *
 633  * Retrieves the number of red bits of @framebuffer
 634  *
 635  * Return value: the number of bits
 636  *
 637  * Since: 1.8
 638  * Stability: unstable
 639  */
 640 int
 641 cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer);
 642
 643 /**
 644  * cogl_framebuffer_get_green_bits:
 645  * @framebuffer: a pointer to a #CoglFramebuffer
 646  *
 647  * Retrieves the number of green bits of @framebuffer
 648  *
 649  * Return value: the number of bits
 650  *
 651  * Since: 1.8
 652  * Stability: unstable
 653  */
 654 int
 655 cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer);
 656
 657 /**
 658  * cogl_framebuffer_get_blue_bits:
 659  * @framebuffer: a pointer to a #CoglFramebuffer
 660  *
 661  * Retrieves the number of blue bits of @framebuffer
 662  *
 663  * Return value: the number of bits
 664  *
 665  * Since: 1.8
 666  * Stability: unstable
 667  */
 668 int
 669 cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer);
 670
 671 /**
 672  * cogl_framebuffer_get_alpha_bits:
 673  * @framebuffer: a pointer to a #CoglFramebuffer
 674  *
 675  * Retrieves the number of alpha bits of @framebuffer
 676  *
 677  * Return value: the number of bits
 678  *
 679  * Since: 1.8
 680  * Stability: unstable
 681  */
 682 int
 683 cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer);
 684
 685 /**
 686  * cogl_framebuffer_get_dither_enabled:
 687  * @framebuffer: a pointer to a #CoglFramebuffer
 688  *
 689  * Returns whether dithering has been requested for the given @framebuffer.
 690  * See cogl_framebuffer_set_dither_enabled() for more details about dithering.
 691  *
 692  * <note>This may return %TRUE even when the underlying @framebuffer
 693  * display pipeline does not support dithering. This value only represents
 694  * the user's request for dithering.</note>
 695  *
 696  * Return value: %TRUE if dithering has been requested or %FALSE if not.
 697  * Since: 1.8
 698  * Stability: unstable
 699  */
 700 gboolean
 701 cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer);
 702
 703 /**
 704  * cogl_framebuffer_set_dither_enabled:
 705  * @framebuffer: a pointer to a #CoglFramebuffer
 706  * @dither_enabled: %TRUE to enable dithering or %FALSE to disable
 707  *
 708  * Enables or disabled dithering if supported by the hardware.
 709  *
 710  * Dithering is a hardware dependent technique to increase the visible
 711  * color resolution beyond what the underlying hardware supports by playing
 712  * tricks with the colors placed into the framebuffer to give the illusion
 713  * of other colors. (For example this can be compared to half-toning used
 714  * by some news papers to show varying levels of grey even though their may
 715  * only be black and white are available).
 716  *
 717  * If the current display pipeline for @framebuffer does not support dithering
 718  * then this has no affect.
 719  *
 720  * Dithering is enabled by default.
 721  *
 722  * Since: 1.8
 723  * Stability: unstable
 724  */
 725 void
 726 cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer,
 727                                      gboolean dither_enabled);
 728
 729 /**
 730  * cogl_framebuffer_get_color_mask:
 731  * @framebuffer: a pointer to a #CoglFramebuffer
 732  *
 733  * Gets the current #CoglColorMask of which channels would be written to the
 734  * current framebuffer. Each bit set in the mask means that the
 735  * corresponding color would be written.
 736  *
 737  * Returns: A #CoglColorMask
 738  * Since: 1.8
 739  * Stability: unstable
 740  */
 741 CoglColorMask
 742 cogl_framebuffer_get_color_mask (CoglFramebuffer *framebuffer);
 743
 744 /**
 745  * cogl_framebuffer_set_color_mask:
 746  * @framebuffer: a pointer to a #CoglFramebuffer
 747  * @color_mask: A #CoglColorMask of which color channels to write to
 748  *              the current framebuffer.
 749  *
 750  * Defines a bit mask of which color channels should be written to the
 751  * given @framebuffer. If a bit is set in @color_mask that means that
 752  * color will be written.
 753  *
 754  * Since: 1.8
 755  * Stability: unstable
 756  */
 757 void
 758 cogl_framebuffer_set_color_mask (CoglFramebuffer *framebuffer,
 759                                  CoglColorMask color_mask);
 760
 761 /**
 762  * cogl_framebuffer_get_color_format:
 763  * @framebuffer: A #CoglFramebuffer framebuffer
 764  *
 765  * Queries the common #CoglPixelFormat of all color buffers attached
 766  * to this framebuffer. For an offscreen framebuffer created with
 767  * cogl_offscreen_new_to_texture() this will correspond to the format
 768  * of the texture.
 769  *
 770  * Since: 1.8
 771  * Stability: unstable
 772  */
 773 CoglPixelFormat
 774 cogl_framebuffer_get_color_format (CoglFramebuffer *framebuffer);
 775
 776 /**
 777  * cogl_framebuffer_set_samples_per_pixel:
 778  * @framebuffer: A #CoglFramebuffer framebuffer
 779  * @samples_per_pixel: The minimum number of samples per pixel
 780  *
 781  * Requires that when rendering to @framebuffer then @n point samples
 782  * should be made per pixel which will all contribute to the final
 783  * resolved color for that pixel. The idea is that the hardware aims
 784  * to get quality similar to what you would get if you rendered
 785  * everything twice as big (for 4 samples per pixel) and then scaled
 786  * that image back down with filtering. It can effectively remove the
 787  * jagged edges of polygons and should be more efficient than if you
 788  * were to manually render at a higher resolution and downscale
 789  * because the hardware is often able to take some shortcuts. For
 790  * example the GPU may only calculate a single texture sample for all
 791  * points of a single pixel, and for tile based architectures all the
 792  * extra sample data (such as depth and stencil samples) may be
 793  * handled on-chip and so avoid increased demand on system memory
 794  * bandwidth.
 795  *
 796  * By default this value is usually set to 0 and that is referred to
 797  * as "single-sample" rendering. A value of 1 or greater is referred
 798  * to as "multisample" rendering.
 799  *
 800  * <note>There are some semantic differences between single-sample
 801  * rendering and multisampling with just 1 point sample such as it
 802  * being redundant to use the cogl_framebuffer_resolve_samples() and
 803  * cogl_framebuffer_resolve_samples_region() apis with single-sample
 804  * rendering.</note>
 805  *
 806  * <note>It's recommended that
 807  * cogl_framebuffer_resolve_samples_region() be explicitly used at the
 808  * end of rendering to a point sample buffer to minimize the number of
 809  * samples that get resolved. By default Cogl will implicitly resolve
 810  * all framebuffer samples but if only a small region of a
 811  * framebuffer has changed this can lead to redundant work being
 812  * done.</note>
 813  *
 814  * Since: 1.8
 815  * Stability: unstable
 816  */
 817 void
 818 cogl_framebuffer_set_samples_per_pixel (CoglFramebuffer *framebuffer,
 819                                         int samples_per_pixel);
 820
 821 /**
 822  * cogl_framebuffer_get_samples_per_pixel:
 823  * @framebuffer: A #CoglFramebuffer framebuffer
 824  *
 825  * Gets the number of points that are sampled per-pixel when
 826  * rasterizing geometry. Usually by default this will return 0 which
 827  * means that single-sample not multisample rendering has been chosen.
 828  * When using a GPU supporting multisample rendering it's possible to
 829  * increase the number of samples per pixel using
 830  * cogl_framebuffer_set_samples_per_pixel().
 831  *
 832  * Calling cogl_framebuffer_get_samples_per_pixel() before the
 833  * framebuffer has been allocated will simply return the value set
 834  * using cogl_framebuffer_set_samples_per_pixel(). After the
 835  * framebuffer has been allocated the value will reflect the actual
 836  * number of samples that will be made by the GPU.
 837  *
 838  * Returns: The number of point samples made per pixel when
 839  *          rasterizing geometry or 0 if single-sample rendering
 840  *          has been chosen.
 841  *
 842  * Since: 1.10
 843  * Stability: unstable
 844  */
 845 int
 846 cogl_framebuffer_get_samples_per_pixel (CoglFramebuffer *framebuffer);
 847
 848
 849 /**
 850  * cogl_framebuffer_resolve_samples:
 851  * @framebuffer: A #CoglFramebuffer framebuffer
 852  *
 853  * When point sample rendering (also known as multisample rendering)
 854  * has been enabled via cogl_framebuffer_set_samples_per_pixel()
 855  * then you can optionally call this function (or
 856  * cogl_framebuffer_resolve_samples_region()) to explicitly resolve
 857  * the point samples into values for the final color buffer.
 858  *
 859  * Some GPUs will implicitly resolve the point samples during
 860  * rendering and so this function is effectively a nop, but with other
 861  * architectures it is desirable to defer the resolve step until the
 862  * end of the frame.
 863  *
 864  * Since Cogl will automatically ensure samples are resolved if the
 865  * target color buffer is used as a source this API only needs to be
 866  * used if explicit control is desired - perhaps because you want to
 867  * ensure that the resolve is completed in advance to avoid later
 868  * having to wait for the resolve to complete.
 869  *
 870  * If you are performing incremental updates to a framebuffer you
 871  * should consider using cogl_framebuffer_resolve_samples_region()
 872  * instead to avoid resolving redundant pixels.
 873  *
 874  * Since: 1.8
 875  * Stability: unstable
 876  */
 877 void
 878 cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer);
 879
 880 /**
 881  * cogl_framebuffer_resolve_samples_region:
 882  * @framebuffer: A #CoglFramebuffer framebuffer
 883  * @x: top-left x coordinate of region to resolve
 884  * @y: top-left y coordinate of region to resolve
 885  * @width: width of region to resolve
 886  * @height: height of region to resolve
 887  *
 888  * When point sample rendering (also known as multisample rendering)
 889  * has been enabled via cogl_framebuffer_set_samples_per_pixel()
 890  * then you can optionally call this function (or
 891  * cogl_framebuffer_resolve_samples()) to explicitly resolve the point
 892  * samples into values for the final color buffer.
 893  *
 894  * Some GPUs will implicitly resolve the point samples during
 895  * rendering and so this function is effectively a nop, but with other
 896  * architectures it is desirable to defer the resolve step until the
 897  * end of the frame.
 898  *
 899  * Use of this API is recommended if incremental, small updates to
 900  * a framebuffer are being made because by default Cogl will
 901  * implicitly resolve all the point samples of the framebuffer which
 902  * can result in redundant work if only a small number of samples have
 903  * changed.
 904  *
 905  * Because some GPUs implicitly resolve point samples this function
 906  * only guarantees that at-least the region specified will be resolved
 907  * and if you have rendered to a larger region then it's possible that
 908  * other samples may be implicitly resolved.
 909  *
 910  * Since: 1.8
 911  * Stability: unstable
 912  */
 913 void
 914 cogl_framebuffer_resolve_samples_region (CoglFramebuffer *framebuffer,
 915                                          int x,
 916                                          int y,
 917                                          int width,
 918                                          int height);
 919
 920 /**
 921  * @framebuffer: A #CoglFramebuffer
 922  *
 923  * Can be used to query the #CoglContext a given @framebuffer was
 924  * instantiated within. This is the #CoglContext that was passed to
 925  * cogl_onscreen_new() for example.
 926  *
 927  * Return value: The #CoglContext that the given @framebuffer was
 928  *               instantiated within.
 929  * Since: 1.8
 930  * Stability: unstable
 931  */
 932 CoglContext *
 933 cogl_framebuffer_get_context (CoglFramebuffer *framebuffer);
 934
 935 /**
 936  * cogl_framebuffer_clear:
 937  * @framebuffer: A #CoglFramebuffer
 938  * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
 939  *   buffers to clear
 940  * @color: The color to clear the color buffer too if specified in
 941  *         @buffers.
 942  *
 943  * Clears all the auxiliary buffers identified in the @buffers mask, and if
 944  * that includes the color buffer then the specified @color is used.
 945  *
 946  * Since: 1.8
 947  * Stability: unstable
 948  */
 949 void
 950 cogl_framebuffer_clear (CoglFramebuffer *framebuffer,
 951                         unsigned long buffers,
 952                         const CoglColor *color);
 953
 954 /**
 955  * cogl_framebuffer_clear4f:
 956  * @framebuffer: A #CoglFramebuffer
 957  * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
 958  *   buffers to clear
 959  * @red: The red component of color to clear the color buffer too if
 960  *       specified in @buffers.
 961  * @green: The green component of color to clear the color buffer too if
 962  *         specified in @buffers.
 963  * @blue: The blue component of color to clear the color buffer too if
 964  *        specified in @buffers.
 965  * @alpha: The alpha component of color to clear the color buffer too if
 966  *         specified in @buffers.
 967  *
 968  * Clears all the auxiliary buffers identified in the @buffers mask, and if
 969  * that includes the color buffer then the specified @color is used.
 970  *
 971  * Since: 1.8
 972  * Stability: unstable
 973  */
 974 void
 975 cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer,
 976                           unsigned long buffers,
 977                           float red,
 978                           float green,
 979                           float blue,
 980                           float alpha);
 981
 982 /**
 983  * cogl_framebuffer_draw_primitive:
 984  * @framebuffer: A destination #CoglFramebuffer
 985  * @pipeline: A #CoglPipeline state object
 986  * @primitive: A #CoglPrimitive geometry object
 987  *
 988  * Draws the given @primitive geometry to the specified destination
 989  * @framebuffer using the graphics processing state described by @pipeline.
 990  *
 991  * This drawing api doesn't support high-level meta texture types such
 992  * as #CoglTexture2DSliced so it is the user's responsibility to
 993  * ensure that only low-level textures that can be directly sampled by
 994  * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
 995  * are associated with layers of the given @pipeline.
 996  *
 997  * <note>This api doesn't support any of the legacy global state options such
 998  * as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or
 999  * cogl_program_use()</note>
1000  *
1001  * Stability: unstable
1002  * Since: 1.10
1003  */
1004 void
1005 cogl_framebuffer_draw_primitive (CoglFramebuffer *framebuffer,
1006                                  CoglPipeline *pipeline,
1007                                  CoglPrimitive *primitive);
1008
1009 /**
1010  * cogl_framebuffer_vdraw_attributes:
1011  * @framebuffer: A destination #CoglFramebuffer
1012  * @pipeline: A #CoglPipeline state object
1013  * @mode: The #CoglVerticesMode defining the topology of vertices
1014  * @first_vertex: The vertex offset within the given attributes to draw from
1015  * @n_vertices: The number of vertices to draw from the given attributes
1016  * @...: A set of vertex #CoglAttribute<!-- -->s defining vertex geometry
1017  *
1018  * First defines a geometry primitive by grouping a set of vertex attributes;
1019  * specifying a @first_vertex; a number of vertices (@n_vertices) and
1020  * specifying  what kind of topology the vertices have via @mode.
1021  *
1022  * Then the function draws the given @primitive geometry to the specified
1023  * destination @framebuffer using the graphics processing pipeline described by
1024  * @pipeline.
1025  *
1026  * The list of #CoglAttribute<!-- -->s define the attributes of the vertices to
1027  * be drawn, such as positions, colors and normals and should be %NULL
1028  * terminated.
1029  *
1030  * This drawing api doesn't support high-level meta texture types such
1031  * as #CoglTexture2DSliced so it is the user's responsibility to
1032  * ensure that only low-level textures that can be directly sampled by
1033  * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
1034  * are associated with layers of the given @pipeline.
1035  *
1036  * Stability: unstable
1037  * Since: 1.10
1038  */
1039 void
1040 cogl_framebuffer_vdraw_attributes (CoglFramebuffer *framebuffer,
1041                                    CoglPipeline *pipeline,
1042                                    CoglVerticesMode mode,
1043                                    int first_vertex,
1044                                    int n_vertices,
1045                                    ...) G_GNUC_NULL_TERMINATED;
1046
1047 /**
1048  * cogl_framebuffer_draw_attributes:
1049  * @framebuffer: A destination #CoglFramebuffer
1050  * @pipeline: A #CoglPipeline state object
1051  * @mode: The #CoglVerticesMode defining the topology of vertices
1052  * @first_vertex: The vertex offset within the given attributes to draw from
1053  * @n_vertices: The number of vertices to draw from the given attributes
1054  * @attributes: An array of pointers to #CoglAttribute<-- -->s defining vertex
1055  *              geometry
1056  * @n_attributes: The number of attributes in the @attributes array.
1057  *
1058  * First defines a geometry primitive by grouping a set of vertex @attributes;
1059  * specifying a @first_vertex; a number of vertices (@n_vertices) and
1060  * specifying  what kind of topology the vertices have via @mode.
1061  *
1062  * Then the function draws the given @primitive geometry to the specified
1063  * destination @framebuffer using the graphics processing pipeline described by
1064  * @pipeline.
1065  *
1066  * The list of #CoglAttribute<!-- -->s define the attributes of the vertices to
1067  * be drawn, such as positions, colors and normals and the number of attributes
1068  * is given as @n_attributes.
1069  *
1070  * This drawing api doesn't support high-level meta texture types such
1071  * as #CoglTexture2DSliced so it is the user's responsibility to
1072  * ensure that only low-level textures that can be directly sampled by
1073  * a GPU such as #CoglTexture2D, #CoglTextureRectangle or #CoglTexture3D
1074  * are associated with layers of the given @pipeline.
1075  *
1076  * <note>This api doesn't support any of the legacy global state options such
1077  * as cogl_set_depth_test_enabled(), cogl_set_backface_culling_enabled() or
1078  * cogl_program_use()</note>
1079  *
1080  * Stability: unstable
1081  * Since: 1.10
1082  */
1083 void
1084 cogl_framebuffer_draw_attributes (CoglFramebuffer *framebuffer,
1085                                   CoglPipeline *pipeline,
1086                                   CoglVerticesMode mode,
1087                                   int first_vertex,
1088                                   int n_vertices,
1089                                   CoglAttribute **attributes,
1090                                   int n_attributes);
1091
1092 /**
1093  * cogl_framebuffer_vdraw_indexed_attributes:
1094  * @framebuffer: A destination #CoglFramebuffer
1095  * @pipeline: A #CoglPipeline state object
1096  * @mode: The #CoglVerticesMode defining the topology of vertices
1097  * @first_vertex: The vertex offset within the given attributes to draw from
1098  * @n_vertices: The number of vertices to draw from the given attributes
1099  * @indices: The array of indices used by the GPU to lookup attribute
1100  *           data for each vertex.
1101  * @...: A set of vertex #CoglAttribute<!-- -->s defining vertex geometry
1102  *
1103  * Behaves the same as cogl_framebuffer_vdraw_attributes() except that
1104  * instead of reading vertex data sequentially from the specified
1105  * attributes the @indices provide an indirection for how the data
1106  * should be indexed allowing a random access order to be
1107  * specified.
1108  *
1109  * For example an indices array of [0, 1, 2, 0, 2, 3] could be used
1110  * used to draw two triangles (@mode = %COGL_VERTICES_MODE_TRIANGLES +
1111  * @n_vertices = 6) but only provide attribute data for the 4 corners
1112  * of a rectangle. When the GPU needs to read in each of the 6
1113  * vertices it will read the @indices array for each vertex in
1114  * sequence and use the index to look up the vertex attribute data. So
1115  * here you can see that first and fourth vertex will point to the
1116  * same data and third and fifth vertex will also point to shared
1117  * data.
1118  *
1119  * Drawing with indices can be a good way of minimizing the size of a
1120  * mesh by allowing you to avoid data for duplicate vertices because
1121  * multiple entries in the index array can refer back to a single
1122  * shared vertex.
1123  *
1124  * <note>The @indices array must be at least as long as @first_vertex
1125  * + @n_vertices otherwise the GPU will overrun the indices array when
1126  * looking up vertex data.</note>
1127  *
1128  * Since it's very common to want to draw a run of rectangles using
1129  * indices to avoid duplicating vertex data you can use
1130  * cogl_get_rectangle_indices() to get a set of indices that can be
1131  * shared.
1132  *
1133  * This drawing api doesn't support high-level meta texture types such
1134  * as #CoglTexture2DSliced so it is the user's responsibility to
1135  * ensure that only low-level textures that can be directly sampled by
1136  * a GPU such as #CoglTexture2D, #CoglTextureRectangle or
1137  * #CoglTexture3D are associated with layers of the given @pipeline.
1138  *
1139  * <note>This api doesn't support any of the legacy global state
1140  * options such as cogl_set_depth_test_enabled(),
1141  * cogl_set_backface_culling_enabled() or cogl_program_use()</note>
1142  *
1143  * Stability: unstable
1144  * Since: 1.10
1145  */
1146 void
1147 cogl_framebuffer_vdraw_indexed_attributes (CoglFramebuffer *framebuffer,
1148                                            CoglPipeline *pipeline,
1149                                            CoglVerticesMode mode,
1150                                            int first_vertex,
1151                                            int n_vertices,
1152                                            CoglIndices *indices,
1153                                            ...) G_GNUC_NULL_TERMINATED;
1154
1155 /**
1156  * cogl_framebuffer_draw_indexed_attributes:
1157  * @framebuffer: A destination #CoglFramebuffer
1158  * @pipeline: A #CoglPipeline state object
1159  * @mode: The #CoglVerticesMode defining the topology of vertices
1160  * @first_vertex: The vertex offset within the given attributes to draw from
1161  * @n_vertices: The number of vertices to draw from the given attributes
1162  * @indices: The array of indices used by the GPU to lookup attribute
1163  *           data for each vertex.
1164  * @attributes: An array of pointers to #CoglAttribute<-- -->s defining vertex
1165  *              geometry
1166  * @n_attributes: The number of attributes in the @attributes array.
1167  *
1168  * Behaves the same as cogl_framebuffer_draw_attributes() except that
1169  * instead of reading vertex data sequentially from the specified
1170  * @attributes the @indices provide an indirection for how the data
1171  * should be indexed allowing a random access order to be
1172  * specified.
1173  *
1174  * For example an indices array of [0, 1, 2, 0, 2, 3] could be used
1175  * used to draw two triangles (@mode = %COGL_VERTICES_MODE_TRIANGLES +
1176  * @n_vertices = 6) but only provide attribute data for the 4 corners
1177  * of a rectangle. When the GPU needs to read in each of the 6
1178  * vertices it will read the @indices array for each vertex in
1179  * sequence and use the index to look up the vertex attribute data. So
1180  * here you can see that first and fourth vertex will point to the
1181  * same data and third and fifth vertex will also point to shared
1182  * data.
1183  *
1184  * Drawing with indices can be a good way of minimizing the size of a
1185  * mesh by allowing you to avoid data for duplicate vertices because
1186  * multiple entries in the index array can refer back to a single
1187  * shared vertex.
1188  *
1189  * <note>The @indices array must be at least as long as @first_vertex
1190  * + @n_vertices otherwise the GPU will overrun the indices array when
1191  * looking up vertex data.</note>
1192  *
1193  * Since it's very common to want to draw a run of rectangles using
1194  * indices to avoid duplicating vertex data you can use
1195  * cogl_get_rectangle_indices() to get a set of indices that can be
1196  * shared.
1197  *
1198  * This drawing api doesn't support high-level meta texture types such
1199  * as #CoglTexture2DSliced so it is the user's responsibility to
1200  * ensure that only low-level textures that can be directly sampled by
1201  * a GPU such as #CoglTexture2D, #CoglTextureRectangle or
1202  * #CoglTexture3D are associated with layers of the given @pipeline.
1203  *
1204  * <note>This api doesn't support any of the legacy global state
1205  * options such as cogl_set_depth_test_enabled(),
1206  * cogl_set_backface_culling_enabled() or cogl_program_use()</note>
1207  *
1208  * Stability: unstable
1209  * Since: 1.10
1210  */
1211 void
1212 cogl_framebuffer_draw_indexed_attributes (CoglFramebuffer *framebuffer,
1213                                           CoglPipeline *pipeline,
1214                                           CoglVerticesMode mode,
1215                                           int first_vertex,
1216                                           int n_vertices,
1217                                           CoglIndices *indices,
1218                                           CoglAttribute **attributes,
1219                                           int n_attributes);
1220
1221 /**
1222  * cogl_framebuffer_draw_rectangle:
1223  * @framebuffer: A destination #CoglFramebuffer
1224  * @pipeline: A #CoglPipeline state object
1225  * @x_1: X coordinate of the top-left corner
1226  * @y_1: Y coordinate of the top-left corner
1227  * @x_2: X coordinate of the bottom-right corner
1228  * @y_2: Y coordinate of the bottom-right corner
1229  *
1230  * Draws a rectangle to @framebuffer with the given @pipeline state
1231  * and with the top left corner positioned at (@x_1, @y_1) and the
1232  * bottom right corner positioned at (@x_2, @y_2).
1233  *
1234  * <note>The position is the position before the rectangle has been
1235  * transformed by the model-view matrix and the projection
1236  * matrix.</note>
1237  *
1238  * <note>If you want to describe a rectangle with a texture mapped on
1239  * it then you can use
1240  * cogl_framebuffer_draw_textured_rectangle().</note>
1241  *
1242  * Since: 1.10
1243  * Stability: unstable
1244  */
1245 void
1246 cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer,
1247                                  CoglPipeline *pipeline,
1248                                  float x_1,
1249                                  float y_1,
1250                                  float x_2,
1251                                  float y_2);
1252
1253 /**
1254  * cogl_framebuffer_draw_textured_rectangle:
1255  * @framebuffer: A destination #CoglFramebuffer
1256  * @pipeline: A #CoglPipeline state object
1257  * @x_1: x coordinate upper left on screen.
1258  * @y_1: y coordinate upper left on screen.
1259  * @x_2: x coordinate lower right on screen.
1260  * @y_2: y coordinate lower right on screen.
1261  * @s_1: S texture coordinate of the top-left coorner
1262  * @t_1: T texture coordinate of the top-left coorner
1263  * @s_2: S texture coordinate of the bottom-right coorner
1264  * @t_2: T texture coordinate of the bottom-right coorner
1265  *
1266  * Draws a textured rectangle to @framebuffer using the given
1267  * @pipeline state with the top left corner positioned at (@x_1, @y_1)
1268  * and the bottom right corner positioned at (@x_2, @y_2). The top
1269  * left corner will have texture coordinates of (@s_1, @t_1) and the
1270  * bottom right corner will have texture coordinates of (@s_2, @t_2).
1271  *
1272  * <note>The position is the position before the rectangle has been
1273  * transformed by the model-view matrix and the projection
1274  * matrix.</note>
1275  *
1276  * This is a high level drawing api that can handle any kind of
1277  * #CoglMetaTexture texture such as #CoglTexture2DSliced textures
1278  * which may internally be comprised of multiple low-level textures.
1279  * This is unlike low-level drawing apis such as
1280  * cogl_framebuffer_draw_primitive() or
1281  * cogl_framebuffer_draw_attributes() which only support low level
1282  * texture types that are directly supported by GPUs such as
1283  * #CoglTexture2D.
1284  *
1285  * <note>The given texture coordinates will only be used for the first
1286  * texture layer of the pipeline and if your pipeline has more than
1287  * one layer then all other layers will have default texture
1288  * coordinates of @s_1=0.0 @t_1=0.0 @s_2=1.0 @t_2=1.0 </note>
1289  *
1290  * The given texture coordinates should always be normalized such that
1291  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
1292  * bottom right. To map an entire texture across the rectangle pass
1293  * in @s_1=%0, @t_1=%0, @s_2=%1, @t_2=%1.
1294  *
1295  * <note>Even if you have associated a #CoglTextureRectangle texture
1296  * with one of your @pipeline layers which normally implies working
1297  * with non-normalized texture coordinates this api should still be
1298  * passed normalized texture coordinates.</note>
1299  *
1300  * Since: 1.10
1301  * Stability: unstable
1302  */
1303 void
1304 cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer,
1305                                           CoglPipeline *pipeline,
1306                                           float x_1,
1307                                           float y_1,
1308                                           float x_2,
1309                                           float y_2,
1310                                           float s_1,
1311                                           float t_1,
1312                                           float s_2,
1313                                           float t_2);
1314
1315 /**
1316  * cogl_framebuffer_draw_multitextured_rectangle:
1317  * @framebuffer: A destination #CoglFramebuffer
1318  * @pipeline: A #CoglPipeline state object
1319  * @x_1: x coordinate upper left on screen.
1320  * @y_1: y coordinate upper left on screen.
1321  * @x_2: x coordinate lower right on screen.
1322  * @y_2: y coordinate lower right on screen.
1323  * @tex_coords: (in) (array) (transfer none): An array containing groups of
1324  *   4 float values: [s_1, t_1, s_2, t_2] that are interpreted as two texture
1325  *   coordinates; one for the top left texel, and one for the bottom right
1326  *   texel. Each value should be between 0.0 and 1.0, where the coordinate
1327  *   (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the
1328  *   bottom right.
1329  * @tex_coords_len: The length of the @tex_coords array. (For one layer
1330  *   and one group of texture coordinates, this would be 4)
1331  *
1332  * Draws a textured rectangle to @framebuffer with the given @pipeline
1333  * state with the top left corner positioned at (@x_1, @y_1) and the
1334  * bottom right corner positioned at (@x_2, @y_2). As a pipeline may
1335  * contain multiple texture layers this interface lets you supply
1336  * texture coordinates for each layer of the pipeline.
1337  *
1338  * <note>The position is the position before the rectangle has been
1339  * transformed by the model-view matrix and the projection
1340  * matrix.</note>
1341  *
1342  * This is a high level drawing api that can handle any kind of
1343  * #CoglMetaTexture texture for the first layer such as
1344  * #CoglTexture2DSliced textures which may internally be comprised of
1345  * multiple low-level textures.  This is unlike low-level drawing apis
1346  * such as cogl_framebuffer_draw_primitive() or
1347  * cogl_framebuffer_draw_attributes() which only support low level
1348  * texture types that are directly supported by GPUs such as
1349  * #CoglTexture2D.
1350  *
1351  * <note>This api can not currently handle multiple high-level meta
1352  * texture layers. The first layer may be a high level meta texture
1353  * such as #CoglTexture2DSliced but all other layers much be low
1354  * level textures such as #CoglTexture2D and additionally they
1355  * should be textures that can be sampled using normalized coordinates
1356  * (so not #CoglTextureRectangle textures).</note>
1357  *
1358  * The top left texture coordinate for layer 0 of any pipeline will be
1359  * (tex_coords[0], tex_coords[1]) and the bottom right coordinate will
1360  * be (tex_coords[2], tex_coords[3]). The coordinates for layer 1
1361  * would be (tex_coords[4], tex_coords[5]) (tex_coords[6],
1362  * tex_coords[7]) and so on...
1363  *
1364  * The given texture coordinates should always be normalized such that
1365  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
1366  * bottom right. To map an entire texture across the rectangle pass
1367  * in tex_coords[0]=%0, tex_coords[1]=%0, tex_coords[2]=%1,
1368  * tex_coords[3]=%1.
1369  *
1370  * <note>Even if you have associated a #CoglTextureRectangle texture
1371  * which normally implies working with non-normalized texture
1372  * coordinates this api should still be passed normalized texture
1373  * coordinates.</note>
1374  *
1375  * The first pair of coordinates are for the first layer (with the
1376  * smallest layer index) and if you supply less texture coordinates
1377  * than there are layers in the current source material then default
1378  * texture coordinates (0.0, 0.0, 1.0, 1.0) are generated.
1379  *
1380  * Since: 1.10
1381  * Stability: unstable
1382  */
1383 void
1384 cogl_framebuffer_draw_multitextured_rectangle (CoglFramebuffer *framebuffer,
1385                                                CoglPipeline *pipeline,
1386                                                float x_1,
1387                                                float y_1,
1388                                                float x_2,
1389                                                float y_2,
1390                                                const float *tex_coords,
1391                                                int tex_coords_len);
1392
1393 /**
1394  * cogl_framebuffer_draw_rectangles:
1395  * @framebuffer: A destination #CoglFramebuffer
1396  * @pipeline: A #CoglPipeline state object
1397  * @coordinates: (in) (array) (transfer none): an array of coordinates
1398  *   containing groups of 4 float values: [x_1, y_1, x_2, y_2] that are
1399  *   interpreted as two position coordinates; one for the top left of
1400  *   the rectangle (x1, y1), and one for the bottom right of the
1401  *   rectangle (x2, y2).
1402  * @n_rectangles: number of rectangles defined in @coordinates.
1403  *
1404  * Draws a series of rectangles to @framebuffer with the given
1405  * @pipeline state in the same way that
1406  * cogl_framebuffer_draw_rectangle() does.
1407  *
1408  * The top left corner of the first rectangle is positioned at
1409  * (coordinates[0], coordinates[1]) and the bottom right corner is
1410  * positioned at (coordinates[2], coordinates[3]). The positions for
1411  * the second rectangle are (coordinates[4], coordinates[5]) and
1412  * (coordinates[6], coordinates[7]) and so on...
1413  *
1414  * <note>The position is the position before the rectangle has been
1415  * transformed by the model-view matrix and the projection
1416  * matrix.</note>
1417  *
1418  * As a general rule for better performance its recommended to use
1419  * this this API instead of calling
1420  * cogl_framebuffer_draw_textured_rectangle() separately for multiple
1421  * rectangles if all of the rectangles will be drawn together with the
1422  * same @pipeline state.
1423  *
1424  * Since: 1.10
1425  * Stability: unstable
1426  */
1427 void
1428 cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer,
1429                                   CoglPipeline *pipeline,
1430                                   const float *verts,
1431                                   unsigned int n_rects);
1432
1433 /**
1434  * cogl_framebuffer_draw_textured_rectangles:
1435  * @framebuffer: A destination #CoglFramebuffer
1436  * @pipeline: A #CoglPipeline state object
1437  * @coordinates: (in) (array) (transfer none): an array containing
1438  *   groups of 8 float values: [x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2]
1439  *   that have the same meaning as the arguments for
1440  *   cogl_framebuffer_draw_textured_rectangle().
1441  * @n_rectangles: number of rectangles to @coordinates to draw
1442  *
1443  * Draws a series of rectangles to @framebuffer with the given
1444  * @pipeline state in the same way that
1445  * cogl_framebuffer_draw_textured_rectangle() does.
1446  *
1447  * <note>The position is the position before the rectangle has been
1448  * transformed by the model-view matrix and the projection
1449  * matrix.</note>
1450  *
1451  * This is a high level drawing api that can handle any kind of
1452  * #CoglMetaTexture texture such as #CoglTexture2DSliced textures
1453  * which may internally be comprised of multiple low-level textures.
1454  * This is unlike low-level drawing apis such as
1455  * cogl_framebuffer_draw_primitive() or
1456  * cogl_framebuffer_draw_attributes() which only support low level
1457  * texture types that are directly supported by GPUs such as
1458  * #CoglTexture2D.
1459  *
1460  * The top left corner of the first rectangle is positioned at
1461  * (coordinates[0], coordinates[1]) and the bottom right corner is
1462  * positioned at (coordinates[2], coordinates[3]). The top left
1463  * texture coordinate is (coordinates[4], coordinates[5]) and the
1464  * bottom right texture coordinate is (coordinates[6],
1465  * coordinates[7]). The coordinates for subsequent rectangles
1466  * are defined similarly by the subsequent coordinates.
1467  *
1468  * As a general rule for better performance its recommended to use
1469  * this this API instead of calling
1470  * cogl_framebuffer_draw_textured_rectangle() separately for multiple
1471  * rectangles if all of the rectangles will be drawn together with the
1472  * same @pipeline state.
1473  *
1474  * The given texture coordinates should always be normalized such that
1475  * (0, 0) corresponds to the top left and (1, 1) corresponds to the
1476  * bottom right. To map an entire texture across the rectangle pass
1477  * in tex_coords[0]=%0, tex_coords[1]=%0, tex_coords[2]=%1,
1478  * tex_coords[3]=%1.
1479  *
1480  * <note>Even if you have associated a #CoglTextureRectangle texture
1481  * which normally implies working with non-normalized texture
1482  * coordinates this api should still be passed normalized texture
1483  * coordinates.</note>
1484  *
1485  * Since: 1.10
1486  * Stability: unstable
1487  */
1488 void
1489 cogl_framebuffer_draw_textured_rectangles (CoglFramebuffer *framebuffer,
1490                                            CoglPipeline *pipeline,
1491                                            const float *coordinates,
1492                                            unsigned int n_rectangles);
1493
1494 /* XXX: Should we take an n_buffers + buffer id array instead of using
1495  * the CoglBufferBits type which doesn't seem future proof? */
1496 /**
1497  * cogl_framebuffer_discard_buffers:
1498  * @framebuffer: A #CoglFramebuffer
1499  * @buffers: A #CoglBufferBit mask of which ancillary buffers you want
1500  *           to discard.
1501  *
1502  * Declares that the specified @buffers no longer need to be referenced
1503  * by any further rendering commands. This can be an important
1504  * optimization to avoid subsequent frames of rendering depending on
1505  * the results of a previous frame.
1506  *
1507  * For example; some tile-based rendering GPUs are able to avoid allocating and
1508  * accessing system memory for the depth and stencil buffer so long as these
1509  * buffers are not required as input for subsequent frames and that can save a
1510  * significant amount of memory bandwidth used to save and restore their
1511  * contents to system memory between frames.
1512  *
1513  * It is currently considered an error to try and explicitly discard the color
1514  * buffer by passing %COGL_BUFFER_BIT_COLOR. This is because the color buffer is
1515  * already implicitly discard when you finish rendering to a #CoglOnscreen
1516  * framebuffer, and it's not meaningful to try and discard the color buffer of
1517  * a #CoglOffscreen framebuffer since they are single-buffered.
1518  *
1519  *
1520  * Since: 1.8
1521  * Stability: unstable
1522  */
1523 void
1524 cogl_framebuffer_discard_buffers (CoglFramebuffer *framebuffer,
1525                                   unsigned long buffers);
1526
1527 /**
1528  * cogl_framebuffer_finish:
1529  * @framebuffer: A #CoglFramebuffer pointer
1530  *
1531  * This blocks the CPU until all pending rendering associated with the
1532  * specified framebuffer has completed. It's very rare that developers should
1533  * ever need this level of synchronization with the GPU and should never be
1534  * used unless you clearly understand why you need to explicitly force
1535  * synchronization.
1536  *
1537  * One example might be for benchmarking purposes to be sure timing
1538  * measurements reflect the time that the GPU is busy for not just the time it
1539  * takes to queue rendering commands.
1540  *
1541  * Stability: unstable
1542  * Since: 1.10
1543  */
1544 void
1545 cogl_framebuffer_finish (CoglFramebuffer *framebuffer);
1546
1547 /**
1548  * cogl_framebuffer_read_pixels_into_bitmap:
1549  * @framebuffer: A #CoglFramebuffer
1550  * @x: The x position to read from
1551  * @y: The y position to read from
1552  * @source: Identifies which auxillary buffer you want to read
1553  *          (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
1554  * @bitmap: The bitmap to store the results in.
1555  *
1556  * This reads a rectangle of pixels from the given framebuffer where
1557  * position (0, 0) is the top left. The pixel at (x, y) is the first
1558  * read, and a rectangle of pixels with the same size as the bitmap is
1559  * read right and downwards from that point.
1560  *
1561  * Currently Cogl assumes that the framebuffer is in a premultiplied
1562  * format so if the format of @bitmap is non-premultiplied it will
1563  * convert it. To read the pixel values without any conversion you
1564  * should either specify a format that doesn't use an alpha channel or
1565  * use one of the formats ending in PRE.
1566  *
1567  * Return value: %TRUE if the read succeeded or %FALSE otherwise. The
1568  *  function is only likely to fail if the bitmap points to a pixel
1569  *  buffer and it could not be mapped.
1570  * Since: 1.10
1571  * Stability: unstable
1572  */
1573 gboolean
1574 cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer,
1575                                           int x,
1576                                           int y,
1577                                           CoglReadPixelsFlags source,
1578                                           CoglBitmap *bitmap);
1579
1580 /**
1581  * cogl_framebuffer_read_pixels:
1582  * @framebuffer: A #CoglFramebuffer
1583  * @x: The x position to read from
1584  * @y: The y position to read from
1585  * @width: The width of the region of rectangles to read
1586  * @height: The height of the region of rectangles to read
1587  * @format: The pixel format to store the data in
1588  * @pixels: The address of the buffer to store the data in
1589  *
1590  * This is a convenience wrapper around
1591  * cogl_framebuffer_read_pixels_into_bitmap() which allocates a
1592  * temporary #CoglBitmap to read pixel data directly into the given
1593  * buffer. The rowstride of the buffer is assumed to be the width of
1594  * the region times the bytes per pixel of the format. The source for
1595  * the data is always taken from the color buffer. If you want to use
1596  * any other rowstride or source, please use the
1597  * cogl_framebuffer_read_pixels_into_bitmap() function directly.
1598  *
1599  * The implementation of the function looks like this:
1600  *
1601  * |[
1602  * bitmap = cogl_bitmap_new_for_data (context,
1603  *                                    width, height,
1604  *                                    format,
1605  *                                    /<!-- -->* rowstride *<!-- -->/
1606  *                                    bpp * width,
1607  *                                    pixels);
1608  * cogl_framebuffer_read_pixels_into_bitmap (framebuffer,
1609  *                                           x, y,
1610  *                                           COGL_READ_PIXELS_COLOR_BUFFER,
1611  *                                           bitmap);
1612  * cogl_object_unref (bitmap);
1613  * ]|
1614  *
1615  * Return value: %TRUE if the read succeeded or %FALSE otherwise.
1616  * Since: 1.10
1617  * Stability: unstable
1618  */
1619 gboolean
1620 cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer,
1621                               int x,
1622                               int y,
1623                               int width,
1624                               int height,
1625                               CoglPixelFormat format,
1626                               guint8 *pixels);
1627
1628 /**
1629  * cogl_get_draw_framebuffer:
1630  *
1631  * Gets the current #CoglFramebuffer as set using
1632  * cogl_push_framebuffer()
1633  *
1634  * Return value: The current #CoglFramebuffer
1635  * Stability: unstable
1636  * Since: 1.8
1637  */
1638 CoglFramebuffer *
1639 cogl_get_draw_framebuffer (void);
1640
1641 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
1642
1643 /* XXX: Note these are defined outside the COGL_ENABLE_EXPERIMENTAL_API guard since
1644  * otherwise the glib-mkenums stuff will get upset. */
1645
1646 GQuark
1647 cogl_framebuffer_error_quark (void);
1648
1649 /**
1650  * COGL_FRAMEBUFFER_ERROR:
1651  *
1652  * An error domain for reporting #CoglFramebuffer exceptions
1653  */
1654 #define COGL_FRAMEBUFFER_ERROR (cogl_framebuffer_error_quark ())
1655
1656 typedef enum { /*< prefix=COGL_FRAMEBUFFER_ERROR >*/
1657   COGL_FRAMEBUFFER_ERROR_ALLOCATE
1658 } CoglFramebufferError;
1659
1660 /**
1661  * cogl_is_framebuffer:
1662  * @object: A #CoglObject pointer
1663  *
1664  * Gets whether the given object references a #CoglFramebuffer.
1665  *
1666  * Return value: %TRUE if the object references a #CoglFramebuffer
1667  *   and %FALSE otherwise.
1668  * Since: 1.10
1669  * Stability: unstable
1670  */
1671 gboolean
1672 cogl_is_framebuffer (void *object);
1673
1674 G_END_DECLS
1675
1676 #endif /* __COGL_FRAMEBUFFER_H */
1677