cogl/cogl1-context.h

   1 /*
   2  * Cogl
   3  *
   4  * An object oriented GL/GLES Abstraction/Utility Layer
   5  *
   6  * Copyright (C) 2010 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  * Authors:
  23  *  Robert Bragg <robert@linux.intel.com>
  24  *
  25  */
  26
  27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
  28 #error "Only <cogl/cogl.h> can be included directly."
  29 #endif
  30
  31 #ifndef __COGL_1_CONTEXT_H__
  32 #define __COGL_1_CONTEXT_H__
  33
  34 #include <glib.h>
  35
  36 #include <cogl/cogl-types.h>
  37 #include <cogl/cogl-texture.h>
  38 #include <cogl/cogl-framebuffer.h>
  39
  40 G_BEGIN_DECLS
  41
  42 /**
  43  * cogl_get_option_group:
  44  *
  45  * Retrieves the #GOptionGroup used by Cogl to parse the command
  46  * line options. Clutter uses this to handle the Cogl command line
  47  * options during its initialization process.
  48  *
  49  * Return value: a #GOptionGroup
  50  *
  51  * Since: 1.0
  52  */
  53 GOptionGroup *
  54 cogl_get_option_group (void);
  55
  56 /* Misc */
  57 /**
  58  * cogl_get_features:
  59  *
  60  * Returns all of the features supported by COGL.
  61  *
  62  * Return value: A logical OR of all the supported COGL features.
  63  *
  64  * Since: 0.8
  65  */
  66 CoglFeatureFlags
  67 cogl_get_features (void);
  68
  69 /**
  70  * cogl_features_available:
  71  * @features: A bitmask of features to check for
  72  *
  73  * Checks whether the given COGL features are available. Multiple
  74  * features can be checked for by or-ing them together with the '|'
  75  * operator. %TRUE is only returned if all of the requested features
  76  * are available.
  77  *
  78  * Return value: %TRUE if the features are available, %FALSE otherwise.
  79  */
  80 gboolean
  81 cogl_features_available (CoglFeatureFlags features);
  82
  83 /**
  84  * cogl_get_proc_address:
  85  * @name: the name of the function.
  86  *
  87  * Gets a pointer to a given GL or GL ES extension function. This acts
  88  * as a wrapper around glXGetProcAddress() or whatever is the
  89  * appropriate function for the current backend.
  90  *
  91  * Return value: a pointer to the requested function or %NULL if the
  92  *   function is not available.
  93  */
  94 CoglFuncPtr
  95 cogl_get_proc_address (const char *name);
  96
  97 #ifndef COGL_DISABLE_DEPRECATED
  98
  99 /**
 100  * cogl_check_extension:
 101  * @name: extension to check for
 102  * @ext: list of extensions
 103  *
 104  * Check whether @name occurs in list of extensions in @ext.
 105  *
 106  * Return value: %TRUE if the extension occurs in the list, %FALSE otherwise.
 107  *
 108  * Deprecated: 1.2: OpenGL is an implementation detail for Cogl and so it's
 109  *   not appropriate to expose OpenGL extensions through the Cogl API. This
 110  *   function can be replaced by the following equivalent code:
 111  * |[
 112  *   gboolean retval = (strstr (ext, name) != NULL) ? TRUE : FALSE;
 113  * ]|
 114  */
 115 gboolean
 116 cogl_check_extension (const char *name,
 117                       const char *ext) G_GNUC_DEPRECATED;
 118
 119 #endif /* COGL_DISABLE_DEPRECATED */
 120
 121 /**
 122  * cogl_get_bitmasks:
 123  * @red: (out): Return location for the number of red bits or %NULL
 124  * @green: (out): Return location for the number of green bits or %NULL
 125  * @blue: (out): Return location for the number of blue bits or %NULL
 126  * @alpha: (out): Return location for the number of alpha bits or %NULL
 127  *
 128  * Gets the number of bitplanes used for each of the color components
 129  * in the color buffer. Pass %NULL for any of the arguments if the
 130  * value is not required.
 131  */
 132 void
 133 cogl_get_bitmasks (int *red,
 134                    int *green,
 135                    int *blue,
 136                    int *alpha);
 137
 138 /**
 139  * cogl_perspective:
 140  * @fovy: Vertical field of view angle in degrees.
 141  * @aspect: The (width over height) aspect ratio for display
 142  * @z_near: The distance to the near clipping plane (Must be positive)
 143  * @z_far: The distance to the far clipping plane (Must be positive)
 144  *
 145  * Replaces the current projection matrix with a perspective matrix
 146  * based on the provided values.
 147  *
 148  * <note>You should be careful not to have to great a @z_far / @z_near
 149  * ratio since that will reduce the effectiveness of depth testing
 150  * since there wont be enough precision to identify the depth of
 151  * objects near to each other.</note>
 152  */
 153 void
 154 cogl_perspective (float fovy,
 155                   float aspect,
 156                   float z_near,
 157                   float z_far);
 158
 159 /**
 160  * cogl_frustum:
 161  * @left: X position of the left clipping plane where it
 162  *   intersects the near clipping plane
 163  * @right: X position of the right clipping plane where it
 164  *   intersects the near clipping plane
 165  * @bottom: Y position of the bottom clipping plane where it
 166  *   intersects the near clipping plane
 167  * @top: Y position of the top clipping plane where it intersects
 168  *   the near clipping plane
 169  * @z_near: The distance to the near clipping plane (Must be positive)
 170  * @z_far: The distance to the far clipping plane (Must be positive)
 171  *
 172  * Replaces the current projection matrix with a perspective matrix
 173  * for a given viewing frustum defined by 4 side clip planes that
 174  * all cross through the origin and 2 near and far clip planes.
 175  *
 176  * Since: 0.8.2
 177  */
 178 void
 179 cogl_frustum (float left,
 180               float right,
 181               float bottom,
 182               float top,
 183               float z_near,
 184               float z_far);
 185
 186 /**
 187  * cogl_ortho:
 188  * @left: The coordinate for the left clipping plane
 189  * @right: The coordinate for the right clipping plane
 190  * @bottom: The coordinate for the bottom clipping plane
 191  * @top: The coordinate for the top clipping plane
 192  * @near: The <emphasis>distance</emphasis> to the near clipping
 193  *   plane (negative if the plane is behind the viewer)
 194  * @far: The <emphasis>distance</emphasis> for the far clipping
 195  *   plane (negative if the plane is behind the viewer)
 196  *
 197  * Replaces the current projection matrix with an orthographic projection
 198  * matrix. See <xref linkend="cogl-ortho-matrix"/> to see how the matrix is
 199  * calculated.
 200  *
 201  * <figure id="cogl-ortho-matrix">
 202  *   <title></title>
 203  *   <graphic fileref="cogl_ortho.png" format="PNG"/>
 204  * </figure>
 205  *
 206  * <note>This function copies the arguments from OpenGL's glOrtho() even
 207  * though they are unnecessarily confusing due to the z near and z far
 208  * arguments actually being a "distance" from the origin, where
 209  * negative values are behind the viewer, instead of coordinates for
 210  * the z clipping planes which would have been consistent with the
 211  * left, right bottom and top arguments.</note>
 212  *
 213  * Since: 1.0
 214  */
 215 void
 216 cogl_ortho (float left,
 217             float right,
 218             float bottom,
 219             float top,
 220             float near,
 221             float far);
 222
 223 #ifndef COGL_DISABLE_DEPRECATED
 224
 225 /**
 226  * cogl_viewport:
 227  * @width: Width of the viewport
 228  * @height: Height of the viewport
 229  *
 230  * Replace the current viewport with the given values.
 231  *
 232  * Since: 0.8.2
 233  *
 234  * Deprecated: 1.2: Use cogl_set_viewport() instead
 235  */
 236 void
 237 cogl_viewport (unsigned int width,
 238                unsigned int height) G_GNUC_DEPRECATED;
 239
 240 #endif /* COGL_DISABLE_DEPRECATED */
 241
 242 /**
 243  * cogl_set_viewport:
 244  * @x: X offset of the viewport
 245  * @y: Y offset of the viewport
 246  * @width: Width of the viewport
 247  * @height: Height of the viewport
 248  *
 249  * Replaces the current viewport with the given values.
 250  *
 251  * Since: 1.2
 252  */
 253 void
 254 cogl_set_viewport (int x,
 255                    int y,
 256                    int width,
 257                    int height);
 258
 259 /**
 260  * cogl_push_matrix:
 261  *
 262  * Stores the current model-view matrix on the matrix stack. The matrix
 263  * can later be restored with cogl_pop_matrix().
 264  */
 265 void
 266 cogl_push_matrix (void);
 267
 268 /**
 269  * cogl_pop_matrix:
 270  *
 271  * Restores the current model-view matrix from the matrix stack.
 272  */
 273 void
 274 cogl_pop_matrix (void);
 275
 276 /**
 277  * cogl_scale:
 278  * @x: Amount to scale along the x-axis
 279  * @y: Amount to scale along the y-axis
 280  * @z: Amount to scale along the z-axis
 281  *
 282  * Multiplies the current model-view matrix by one that scales the x,
 283  * y and z axes by the given values.
 284  */
 285 void
 286 cogl_scale (float x,
 287             float y,
 288             float z);
 289
 290 /**
 291  * cogl_translate:
 292  * @x: Distance to translate along the x-axis
 293  * @y: Distance to translate along the y-axis
 294  * @z: Distance to translate along the z-axis
 295  *
 296  * Multiplies the current model-view matrix by one that translates the
 297  * model along all three axes according to the given values.
 298  */
 299 void
 300 cogl_translate (float x,
 301                 float y,
 302                 float z);
 303
 304 /**
 305  * cogl_rotate:
 306  * @angle: Angle in degrees to rotate.
 307  * @x: X-component of vertex to rotate around.
 308  * @y: Y-component of vertex to rotate around.
 309  * @z: Z-component of vertex to rotate around.
 310  *
 311  * Multiplies the current model-view matrix by one that rotates the
 312  * model around the vertex specified by @x, @y and @z. The rotation
 313  * follows the right-hand thumb rule so for example rotating by 10
 314  * degrees about the vertex (0, 0, 1) causes a small counter-clockwise
 315  * rotation.
 316  */
 317 void
 318 cogl_rotate (float angle,
 319              float x,
 320              float y,
 321              float z);
 322
 323 /**
 324  * cogl_transform:
 325  * @matrix: the matrix to multiply with the current model-view
 326  *
 327  * Multiplies the current model-view matrix by the given matrix.
 328  *
 329  * Since: 1.4
 330  */
 331 void
 332 cogl_transform (const CoglMatrix *matrix);
 333
 334 /**
 335  * cogl_get_modelview_matrix:
 336  * @matrix: (out): return location for the model-view matrix
 337  *
 338  * Stores the current model-view matrix in @matrix.
 339  */
 340 void
 341 cogl_get_modelview_matrix (CoglMatrix *matrix);
 342
 343 /**
 344  * cogl_set_modelview_matrix:
 345  * @matrix: the new model-view matrix
 346  *
 347  * Loads @matrix as the new model-view matrix.
 348  */
 349 void
 350 cogl_set_modelview_matrix (CoglMatrix *matrix);
 351
 352 /**
 353  * cogl_get_projection_matrix:
 354  * @matrix: (out): return location for the projection matrix
 355  *
 356  * Stores the current projection matrix in @matrix.
 357  */
 358 void
 359 cogl_get_projection_matrix (CoglMatrix *matrix);
 360
 361 /**
 362  * cogl_set_projection_matrix:
 363  * @matrix: the new projection matrix
 364  *
 365  * Loads matrix as the new projection matrix.
 366  */
 367 void
 368 cogl_set_projection_matrix (CoglMatrix *matrix);
 369
 370 /**
 371  * cogl_get_viewport:
 372  * @v: (out) (array fixed-size=4): pointer to a 4 element array
 373  *   of #float<!-- -->s to receive the viewport dimensions.
 374  *
 375  * Stores the current viewport in @v. @v[0] and @v[1] get the x and y
 376  * position of the viewport and @v[2] and @v[3] get the width and
 377  * height.
 378  */
 379 void
 380 cogl_get_viewport (float v[4]);
 381
 382 /**
 383  * cogl_set_depth_test_enabled:
 384  * @setting: %TRUE to enable depth testing or %FALSE to disable.
 385  *
 386  * Sets whether depth testing is enabled. If it is disabled then the
 387  * order that actors are layered on the screen depends solely on the
 388  * order specified using clutter_actor_raise() and
 389  * clutter_actor_lower(), otherwise it will also take into account the
 390  * actor's depth. Depth testing is disabled by default.
 391  *
 392  * Deprecated: 1.4: Use cogl_material_set_depth_test_enabled()
 393  * instead.
 394  */
 395 void
 396 cogl_set_depth_test_enabled (gboolean setting);
 397
 398 /**
 399  * cogl_get_depth_test_enabled:
 400  *
 401  * Queries if depth testing has been enabled via cogl_set_depth_test_enable()
 402  *
 403  * Return value: %TRUE if depth testing is enabled, and %FALSE otherwise
 404  *
 405  * Deprecated: 1.4: Use cogl_material_get_depth_test_enabled()
 406  * instead.
 407  */
 408 gboolean
 409 cogl_get_depth_test_enabled (void);
 410
 411 /**
 412  * cogl_set_backface_culling_enabled:
 413  * @setting: %TRUE to enable backface culling or %FALSE to disable.
 414  *
 415  * Sets whether textures positioned so that their backface is showing
 416  * should be hidden. This can be used to efficiently draw two-sided
 417  * textures or fully closed cubes without enabling depth testing. This
 418  * only affects calls to the cogl_rectangle* family of functions and
 419  * cogl_vertex_buffer_draw*. Backface culling is disabled by default.
 420  */
 421 void
 422 cogl_set_backface_culling_enabled (gboolean setting);
 423
 424 /**
 425  * cogl_get_backface_culling_enabled:
 426  *
 427  * Queries if backface culling has been enabled via
 428  * cogl_set_backface_culling_enabled()
 429  *
 430  * Return value: %TRUE if backface culling is enabled, and %FALSE otherwise
 431  */
 432 gboolean
 433 cogl_get_backface_culling_enabled (void);
 434
 435 /**
 436  * cogl_set_fog:
 437  * @fog_color: The color of the fog
 438  * @mode: A #CoglFogMode that determines the equation used to calculate the
 439  *   fogging blend factor.
 440  * @density: Used by %COGL_FOG_MODE_EXPONENTIAL and by
 441  *   %COGL_FOG_MODE_EXPONENTIAL_SQUARED equations.
 442  * @z_near: Position along Z axis where no fogging should be applied
 443  * @z_far: Position along Z axis where full fogging should be applied
 444  *
 445  * Enables fogging. Fogging causes vertices that are further away from the eye
 446  * to be rendered with a different color. The color is determined according to
 447  * the chosen fog mode; at it's simplest the color is linearly interpolated so
 448  * that vertices at @z_near are drawn fully with their original color and
 449  * vertices at @z_far are drawn fully with @fog_color. Fogging will remain
 450  * enabled until you call cogl_disable_fog().
 451  *
 452  * <note>The fogging functions only work correctly when primitives use
 453  * unmultiplied alpha colors. By default Cogl will premultiply textures
 454  * and cogl_set_source_color() will premultiply colors, so unless you
 455  * explicitly load your textures requesting an unmultiplied internal format
 456  * and use cogl_material_set_color() you can only use fogging with fully
 457  * opaque primitives. This might improve in the future when we can depend
 458  * on fragment shaders.</note>
 459  */
 460 void
 461 cogl_set_fog (const CoglColor *fog_color,
 462               CoglFogMode mode,
 463               float density,
 464               float z_near,
 465               float z_far);
 466
 467 /**
 468  * cogl_disable_fog:
 469  *
 470  * This function disables fogging, so primitives drawn afterwards will not be
 471  * blended with any previously set fog color.
 472  */
 473 void
 474 cogl_disable_fog (void);
 475
 476 /**
 477  * cogl_clear:
 478  * @color: Background color to clear to
 479  * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
 480  *   buffers to clear
 481  *
 482  * Clears all the auxiliary buffers identified in the @buffers mask, and if
 483  * that includes the color buffer then the specified @color is used.
 484  */
 485 void
 486 cogl_clear (const CoglColor *color,
 487             unsigned long buffers);
 488
 489 /**
 490  * cogl_set_source:
 491  * @material: A #CoglMaterial
 492  *
 493  * This function changes the material at the top of the source stack.
 494  * The material at the top of this stack defines the GPU state used to
 495  * process subsequent primitives, such as rectangles drawn with
 496  * cogl_rectangle() or vertices drawn using cogl_vertex_buffer_draw().
 497  *
 498  * Since: 1.0
 499  */
 500 void
 501 cogl_set_source (void *material);
 502
 503 /**
 504  * cogl_get_source:
 505  *
 506  * Returns the current source material as previously set using
 507  * cogl_set_source().
 508  *
 509  * <note>You should typically consider the returned material immutable
 510  * and not try to change any of its properties unless you own a
 511  * reference to that material. At times you may be able to get a
 512  * reference to an internally managed materials and the result of
 513  * modifying such materials is undefined.</note>
 514  *
 515  * Return value: The current source material.
 516  *
 517  * Since: 1.6
 518  */
 519 void *
 520 cogl_get_source (void);
 521
 522 /**
 523  * cogl_push_source:
 524  * @material: A #CoglMaterial
 525  *
 526  * Pushes the given @material to the top of the source stack. The
 527  * material at the top of this stack defines the GPU state used to
 528  * process later primitives as defined by cogl_set_source().
 529  *
 530  * Since: 1.6
 531  */
 532 void
 533 cogl_push_source (void *material);
 534
 535 /**
 536  * cogl_pop_source:
 537  *
 538  * Removes the material at the top of the source stack. The material
 539  * at the top of this stack defines the GPU state used to process
 540  * later primitives as defined by cogl_set_source().
 541  *
 542  * Since: 1.6
 543  */
 544 void
 545 cogl_pop_source (void);
 546
 547 /**
 548  * cogl_set_source_color:
 549  * @color: a #CoglColor
 550  *
 551  * This is a convenience function for creating a solid fill source material
 552  * from the given color. This color will be used for any subsequent drawing
 553  * operation.
 554  *
 555  * The color will be premultiplied by Cogl, so the color should be
 556  * non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for
 557  * semi-transparent red.
 558  *
 559  * See also cogl_set_source_color4ub() and cogl_set_source_color4f()
 560  * if you already have the color components.
 561  *
 562  * Since: 1.0
 563  */
 564 void
 565 cogl_set_source_color (const CoglColor *color);
 566
 567 /**
 568  * cogl_set_source_color4ub:
 569  * @red: value of the red channel, between 0 and 255
 570  * @green: value of the green channel, between 0 and 255
 571  * @blue: value of the blue channel, between 0 and 255
 572  * @alpha: value of the alpha channel, between 0 and 255
 573  *
 574  * This is a convenience function for creating a solid fill source material
 575  * from the given color using unsigned bytes for each component. This
 576  * color will be used for any subsequent drawing operation.
 577  *
 578  * The value for each component is an unsigned byte in the range
 579  * between 0 and 255.
 580  *
 581  * Since: 1.0
 582  */
 583 void
 584 cogl_set_source_color4ub (guint8 red,
 585                           guint8 green,
 586                           guint8 blue,
 587                           guint8 alpha);
 588
 589 /**
 590  * cogl_set_source_color4f:
 591  * @red: value of the red channel, between 0 and %1.0
 592  * @green: value of the green channel, between 0 and %1.0
 593  * @blue: value of the blue channel, between 0 and %1.0
 594  * @alpha: value of the alpha channel, between 0 and %1.0
 595  *
 596  * This is a convenience function for creating a solid fill source material
 597  * from the given color using normalized values for each component. This color
 598  * will be used for any subsequent drawing operation.
 599  *
 600  * The value for each component is a fixed point number in the range
 601  * between 0 and %1.0. If the values passed in are outside that
 602  * range, they will be clamped.
 603  *
 604  * Since: 1.0
 605  */
 606 void
 607 cogl_set_source_color4f (float red,
 608                          float green,
 609                          float blue,
 610                          float alpha);
 611
 612 /**
 613  * cogl_set_source_texture:
 614  * @texture: The #CoglTexture you want as your source
 615  *
 616  * This is a convenience function for creating a material with the first
 617  * layer set to @texture and setting that material as the source with
 618  * cogl_set_source.
 619  *
 620  * Note: There is no interaction between calls to cogl_set_source_color
 621  * and cogl_set_source_texture. If you need to blend a texture with a color then
 622  * you can create a simple material like this:
 623  * <programlisting>
 624  * material = cogl_material_new ();
 625  * cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80);
 626  * cogl_material_set_layer (material, 0, tex_handle);
 627  * cogl_set_source (material);
 628  * </programlisting>
 629  *
 630  * Since: 1.0
 631  */
 632 void
 633 cogl_set_source_texture (CoglTexture *texture);
 634
 635
 636 /**
 637  * SECTION:cogl-clipping
 638  * @short_description: Fuctions for manipulating a stack of clipping regions
 639  *
 640  * To support clipping your geometry to rectangles or paths Cogl exposes a
 641  * stack based API whereby each clip region you push onto the stack is
 642  * intersected with the previous region.
 643  */
 644
 645 #ifndef COGL_DISABLE_DEPRECATED
 646
 647 /**
 648  * cogl_clip_push_window_rect:
 649  * @x_offset: left edge of the clip rectangle in window coordinates
 650  * @y_offset: top edge of the clip rectangle in window coordinates
 651  * @width: width of the clip rectangle
 652  * @height: height of the clip rectangle
 653  *
 654  * Specifies a rectangular clipping area for all subsequent drawing
 655  * operations. Any drawing commands that extend outside the rectangle
 656  * will be clipped so that only the portion inside the rectangle will
 657  * be displayed. The rectangle dimensions are not transformed by the
 658  * current model-view matrix.
 659  *
 660  * The rectangle is intersected with the current clip region. To undo
 661  * the effect of this function, call cogl_clip_pop().
 662  *
 663  * Deprecated: 1.2: Use cogl_clip_push_window_rectangle() instead
 664  */
 665 void
 666 cogl_clip_push_window_rect (float x_offset,
 667                             float y_offset,
 668                             float width,
 669                             float height) G_GNUC_DEPRECATED;
 670
 671 #endif /* COGL_DISABLE_DEPRECATED */
 672
 673 /**
 674  * cogl_clip_push_window_rectangle:
 675  * @x_offset: left edge of the clip rectangle in window coordinates
 676  * @y_offset: top edge of the clip rectangle in window coordinates
 677  * @width: width of the clip rectangle
 678  * @height: height of the clip rectangle
 679  *
 680  * Specifies a rectangular clipping area for all subsequent drawing
 681  * operations. Any drawing commands that extend outside the rectangle
 682  * will be clipped so that only the portion inside the rectangle will
 683  * be displayed. The rectangle dimensions are not transformed by the
 684  * current model-view matrix.
 685  *
 686  * The rectangle is intersected with the current clip region. To undo
 687  * the effect of this function, call cogl_clip_pop().
 688  *
 689  * Since: 1.2
 690  */
 691 void
 692 cogl_clip_push_window_rectangle (int x_offset,
 693                                  int y_offset,
 694                                  int width,
 695                                  int height);
 696
 697 #ifndef COGL_DISABLE_DEPRECATED
 698
 699 /**
 700  * cogl_clip_push:
 701  * @x_offset: left edge of the clip rectangle
 702  * @y_offset: top edge of the clip rectangle
 703  * @width: width of the clip rectangle
 704  * @height: height of the clip rectangle
 705  *
 706  * Specifies a rectangular clipping area for all subsequent drawing
 707  * operations. Any drawing commands that extend outside the rectangle
 708  * will be clipped so that only the portion inside the rectangle will
 709  * be displayed. The rectangle dimensions are transformed by the
 710  * current model-view matrix.
 711  *
 712  * The rectangle is intersected with the current clip region. To undo
 713  * the effect of this function, call cogl_clip_pop().
 714  *
 715  * Deprecated: 1.2: The x, y, width, height arguments are inconsistent
 716  *   with other API that specify rectangles in model space, and when used
 717  *   with a coordinate space that puts the origin at the center and y+
 718  *   extending up, it's awkward to use. Please use cogl_clip_push_rectangle()
 719  *   instead
 720  */
 721 void
 722 cogl_clip_push (float x_offset,
 723                 float y_offset,
 724                 float width,
 725                 float height) G_GNUC_DEPRECATED;
 726
 727 #endif /* COGL_DISABLE_DEPRECATED */
 728
 729 /**
 730  * cogl_clip_push_rectangle:
 731  * @x0: x coordinate for top left corner of the clip rectangle
 732  * @y0: y coordinate for top left corner of the clip rectangle
 733  * @x1: x coordinate for bottom right corner of the clip rectangle
 734  * @y1: y coordinate for bottom right corner of the clip rectangle
 735  *
 736  * Specifies a rectangular clipping area for all subsequent drawing
 737  * operations. Any drawing commands that extend outside the rectangle
 738  * will be clipped so that only the portion inside the rectangle will
 739  * be displayed. The rectangle dimensions are transformed by the
 740  * current model-view matrix.
 741  *
 742  * The rectangle is intersected with the current clip region. To undo
 743  * the effect of this function, call cogl_clip_pop().
 744  *
 745  * Since: 1.2
 746  */
 747 void
 748 cogl_clip_push_rectangle (float x0,
 749                           float y0,
 750                           float x1,
 751                           float y1);
 752
 753 /**
 754  * cogl_clip_push_from_path_preserve:
 755  *
 756  * Sets a new clipping area using the current path. The current path
 757  * is then cleared. The clipping area is intersected with the previous
 758  * clipping area. To restore the previous clipping area, call
 759  * cogl_clip_pop().
 760  *
 761  * Since: 1.0
 762  */
 763 void
 764 cogl_clip_push_from_path_preserve (void);
 765
 766 #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API
 767 /**
 768  * cogl_clip_push_primitive:
 769  * @primitive: A #CoglPrimitive describing a flat 2D shape
 770  * @bounds_x1: x coordinate for the top-left corner of the primitives
 771  *             bounds
 772  * @bounds_y1: y coordinate for the top-left corner of the primitives
 773  *             bounds
 774  * @bounds_x2: x coordinate for the top-left corner of the primitives
 775  *             bounds
 776  * @bounds_y2: x coordinate for the bottom-right corner of the
 777  *             primitives bounds.
 778  * @bounds_x1: y coordinate for the bottom-right corner of the
 779  *             primitives bounds.
 780  *
 781  * Sets a new clipping area using a 2D shaped described with a
 782  * #CoglPrimitive. The shape must not contain self overlapping
 783  * geometry and must lie on a single 2D plane. A bounding box of the
 784  * 2D shape in local coordinates (the same coordinates used to
 785  * describe the shape) must be given. It is acceptable for the bounds
 786  * to be larger than the true bounds but behaviour is undefined if the
 787  * bounds are smaller than the true bounds.
 788  *
 789  * The primitive is transformed by the current model-view matrix and
 790  * the silhouette is intersected with the previous clipping area.  To
 791  * restore the previous clipping area, call
 792  * cogl_clip_pop().
 793  *
 794  * Since: 1.10
 795  * Stability: unstable
 796  */
 797 void
 798 cogl_clip_push_primitive (CoglPrimitive *primitive,
 799                           float bounds_x1,
 800                           float bounds_y1,
 801                           float bounds_x2,
 802                           float bounds_y2);
 803 #endif
 804
 805 /**
 806  * cogl_clip_pop:
 807  *
 808  * Reverts the clipping region to the state before the last call to
 809  * cogl_clip_push().
 810  */
 811 void
 812 cogl_clip_pop (void);
 813
 814 #ifndef COGL_DISABLE_DEPRECATED
 815
 816 /**
 817  * cogl_clip_ensure:
 818  *
 819  * Ensures that the current clipping region has been set in GL. This
 820  * will automatically be called before any Cogl primitives but it
 821  * maybe be neccessary to call if you are using raw GL calls with
 822  * clipping.
 823  *
 824  * Deprecated: 1.2: Calling this function has no effect
 825  *
 826  * Since: 1.0
 827  */
 828 void
 829 cogl_clip_ensure (void) G_GNUC_DEPRECATED;
 830
 831 /**
 832  * cogl_clip_stack_save:
 833  *
 834  * Save the entire state of the clipping stack and then clear all
 835  * clipping. The previous state can be returned to with
 836  * cogl_clip_stack_restore(). Each call to cogl_clip_push() after this
 837  * must be matched by a call to cogl_clip_pop() before calling
 838  * cogl_clip_stack_restore().
 839  *
 840  * Deprecated: 1.2: This was originally added to allow us to save the
 841  *   clip stack when switching to an offscreen framebuffer, but it's
 842  *   not necessary anymore given that framebuffers now own separate
 843  *   clip stacks which will be automatically switched between when a
 844  *   new buffer is set. Calling this function has no effect
 845  *
 846  * Since: 0.8.2
 847  */
 848 void
 849 cogl_clip_stack_save (void) G_GNUC_DEPRECATED;
 850
 851 /**
 852  * cogl_clip_stack_restore:
 853  *
 854  * Restore the state of the clipping stack that was previously saved
 855  * by cogl_clip_stack_save().
 856  *
 857  * Deprecated: 1.2: This was originally added to allow us to restore
 858  *   the clip stack when switching back from an offscreen framebuffer,
 859  *   but it's not necessary anymore given that framebuffers now own
 860  *   separate clip stacks which will be automatically switched between
 861  *   when a new buffer is set. Calling this function has no effect
 862  *
 863  * Since: 0.8.2
 864  */
 865 void
 866 cogl_clip_stack_restore (void) G_GNUC_DEPRECATED;
 867
 868 #endif /* COGL_DISABLE_DEPRECATED */
 869
 870 /**
 871  * cogl_set_framebuffer:
 872  * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
 873  *
 874  * This redirects all subsequent drawing to the specified framebuffer. This can
 875  * either be an offscreen buffer created with cogl_offscreen_new_to_texture ()
 876  * or in the future it may be an onscreen framebuffers too.
 877  *
 878  * Since: 1.2
 879  */
 880 void
 881 cogl_set_framebuffer (CoglFramebuffer *buffer);
 882
 883 /**
 884  * cogl_push_framebuffer:
 885  * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
 886  *
 887  * Redirects all subsequent drawing to the specified framebuffer. This can
 888  * either be an offscreen buffer created with cogl_offscreen_new_to_texture ()
 889  * or in the future it may be an onscreen framebuffer too.
 890  *
 891  * You should understand that a framebuffer owns the following state:
 892  * <itemizedlist>
 893  *  <listitem><simpara>The projection matrix</simpara></listitem>
 894  *  <listitem><simpara>The modelview matrix stack</simpara></listitem>
 895  *  <listitem><simpara>The viewport</simpara></listitem>
 896  *  <listitem><simpara>The clip stack</simpara></listitem>
 897  * </itemizedlist>
 898  * So these items will automatically be saved and restored when you
 899  * push and pop between different framebuffers.
 900  *
 901  * Also remember a newly allocated framebuffer will have an identity matrix for
 902  * the projection and modelview matrices which gives you a coordinate space
 903  * like OpenGL with (-1, -1) corresponding to the top left of the viewport,
 904  * (1, 1) corresponding to the bottom right and +z coming out towards the
 905  * viewer.
 906  *
 907  * If you want to set up a coordinate space like Clutter does with (0, 0)
 908  * corresponding to the top left and (framebuffer_width, framebuffer_height)
 909  * corresponding to the bottom right you can do so like this:
 910  *
 911  * |[
 912  * static void
 913  * setup_viewport (unsigned int width,
 914  *                 unsigned int height,
 915  *                 float fovy,
 916  *                 float aspect,
 917  *                 float z_near,
 918  *                 float z_far)
 919  * {
 920  *   float z_camera;
 921  *   CoglMatrix projection_matrix;
 922  *   CoglMatrix mv_matrix;
 923  *
 924  *   cogl_set_viewport (0, 0, width, height);
 925  *   cogl_perspective (fovy, aspect, z_near, z_far);
 926  *
 927  *   cogl_get_projection_matrix (&amp;projection_matrix);
 928  *   z_camera = 0.5 * projection_matrix.xx;
 929  *
 930  *   cogl_matrix_init_identity (&amp;mv_matrix);
 931  *   cogl_matrix_translate (&amp;mv_matrix, -0.5f, -0.5f, -z_camera);
 932  *   cogl_matrix_scale (&amp;mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
 933  *   cogl_matrix_translate (&amp;mv_matrix, 0.0f, -1.0 * height, 0.0f);
 934  *   cogl_set_modelview_matrix (&amp;mv_matrix);
 935  * }
 936  *
 937  * static void
 938  * my_init_framebuffer (ClutterStage *stage,
 939  *                      CoglFramebuffer *framebuffer,
 940  *                      unsigned int framebuffer_width,
 941  *                      unsigned int framebuffer_height)
 942  * {
 943  *   ClutterPerspective perspective;
 944  *
 945  *   clutter_stage_get_perspective (stage, &perspective);
 946  *
 947  *   cogl_push_framebuffer (framebuffer);
 948  *   setup_viewport (framebuffer_width,
 949  *                   framebuffer_height,
 950  *                   perspective.fovy,
 951  *                   perspective.aspect,
 952  *                   perspective.z_near,
 953  *                   perspective.z_far);
 954  * }
 955  * ]|
 956  *
 957  * The previous framebuffer can be restored by calling cogl_pop_framebuffer()
 958  *
 959  * Since: 1.2
 960  */
 961 void
 962 cogl_push_framebuffer (CoglFramebuffer *buffer);
 963
 964 /**
 965  * cogl_pop_framebuffer:
 966  *
 967  * Restores the framebuffer that was previously at the top of the stack.
 968  * All subsequent drawing will be redirected to this framebuffer.
 969  *
 970  * Since: 1.2
 971  */
 972 void
 973 cogl_pop_framebuffer (void);
 974
 975 #ifndef COGL_DISABLE_DEPRECATED
 976
 977 /**
 978  * cogl_set_draw_buffer:
 979  * @target: A #CoglBufferTarget that specifies what kind of framebuffer you
 980  *          are setting as the render target.
 981  * @offscreen: If you are setting a framebuffer of type COGL_OFFSCREEN_BUFFER
 982  *             then this is a CoglHandle for the offscreen buffer.
 983  *
 984  * Redirects all subsequent drawing to the specified framebuffer. This
 985  * can either be an offscreen buffer created with
 986  * cogl_offscreen_new_to_texture () or you can revert to your original
 987  * on screen window buffer.
 988  *
 989  * Deprecated: 1.2: The target argument was redundant since we could look at
 990  *    the type of CoglHandle given instead.
 991  */
 992 void
 993 cogl_set_draw_buffer (CoglBufferTarget target,
 994                       CoglHandle offscreen) G_GNUC_DEPRECATED;
 995
 996 /**
 997  * cogl_push_draw_buffer:
 998  *
 999  * Save cogl_set_draw_buffer() state.
1000  *
1001  * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API
1002  */
1003 void
1004 cogl_push_draw_buffer (void) G_GNUC_DEPRECATED;
1005
1006 /**
1007  * cogl_pop_draw_buffer:
1008  *
1009  * Restore cogl_set_draw_buffer() state.
1010  *
1011  * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API
1012  */
1013 void
1014 cogl_pop_draw_buffer (void) G_GNUC_DEPRECATED;
1015
1016 #endif /* COGL_DISABLE_DEPRECATED */
1017
1018 /**
1019  * cogl_read_pixels:
1020  * @x: The window x position to start reading from
1021  * @y: The window y position to start reading from
1022  * @width: The width of the rectangle you want to read
1023  * @height: The height of the rectangle you want to read
1024  * @source: Identifies which auxillary buffer you want to read
1025  *          (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
1026  * @format: The pixel format you want the result in
1027  *          (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)
1028  * @pixels: The location to write the pixel data.
1029  *
1030  * This reads a rectangle of pixels from the current framebuffer where
1031  * position (0, 0) is the top left. The pixel at (x, y) is the first
1032  * read, and the data is returned with a rowstride of (width * 4).
1033  *
1034  * Currently Cogl assumes that the framebuffer is in a premultiplied
1035  * format so if @format is non-premultiplied it will convert it. To
1036  * read the pixel values without any conversion you should either
1037  * specify a format that doesn't use an alpha channel or use one of
1038  * the formats ending in PRE.
1039  */
1040 void
1041 cogl_read_pixels (int x,
1042                   int y,
1043                   int width,
1044                   int height,
1045                   CoglReadPixelsFlags source,
1046                   CoglPixelFormat format,
1047                   guint8 *pixels);
1048
1049 /**
1050  * cogl_flush:
1051  *
1052  * This function should only need to be called in exceptional circumstances.
1053  *
1054  * As an optimization Cogl drawing functions may batch up primitives
1055  * internally, so if you are trying to use raw GL outside of Cogl you stand a
1056  * better chance of being successful if you ask Cogl to flush any batched
1057  * geometry before making your state changes.
1058  *
1059  * It only ensure that the underlying driver is issued all the commands
1060  * necessary to draw the batched primitives. It provides no guarantees about
1061  * when the driver will complete the rendering.
1062  *
1063  * This provides no guarantees about the GL state upon returning and to avoid
1064  * confusing Cogl you should aim to restore any changes you make before
1065  * resuming use of Cogl.
1066  *
1067  * If you are making state changes with the intention of affecting Cogl drawing
1068  * primitives you are 100% on your own since you stand a good chance of
1069  * conflicting with Cogl internals. For example clutter-gst which currently
1070  * uses direct GL calls to bind ARBfp programs will very likely break when Cogl
1071  * starts to use ARBfb programs itself for the material API.
1072  *
1073  * Since: 1.0
1074  */
1075 void
1076 cogl_flush (void);
1077
1078 /**
1079  * cogl_begin_gl:
1080  *
1081  * We do not advise nor reliably support the interleaving of raw GL drawing and
1082  * Cogl drawing functions, but if you insist, cogl_begin_gl() and cogl_end_gl()
1083  * provide a simple mechanism that may at least give you a fighting chance of
1084  * succeeding.
1085  *
1086  * Note: this doesn't help you modify the behaviour of Cogl drawing functions
1087  * through the modification of GL state; that will never be reliably supported,
1088  * but if you are trying to do something like:
1089  *
1090  * |[
1091  * {
1092  *    - setup some OpenGL state.
1093  *    - draw using OpenGL (e.g. glDrawArrays() )
1094  *    - reset modified OpenGL state.
1095  *    - continue using Cogl to draw
1096  * }
1097  * ]|
1098  *
1099  * You should surround blocks of drawing using raw GL with cogl_begin_gl()
1100  * and cogl_end_gl():
1101  *
1102  * |[
1103  * {
1104  *    cogl_begin_gl ();
1105  *    - setup some OpenGL state.
1106  *    - draw using OpenGL (e.g. glDrawArrays() )
1107  *    - reset modified OpenGL state.
1108  *    cogl_end_gl ();
1109  *    - continue using Cogl to draw
1110  * }
1111  * ]|
1112  *
1113  * Don't ever try and do:
1114  *
1115  * |[
1116  * {
1117  *    - setup some OpenGL state.
1118  *    - use Cogl to draw
1119  *    - reset modified OpenGL state.
1120  * }
1121  * ]|
1122  *
1123  * When the internals of Cogl evolves, this is very liable to break.
1124  *
1125  * This function will flush all batched primitives, and subsequently flush
1126  * all internal Cogl state to OpenGL as if it were going to draw something
1127  * itself.
1128  *
1129  * The result is that the OpenGL modelview matrix will be setup; the state
1130  * corresponding to the current source material will be set up and other world
1131  * state such as backface culling, depth and fogging enabledness will be sent
1132  * to OpenGL.
1133  *
1134  * <note>No special material state is flushed, so if you want Cogl to setup a
1135  * simplified material state it is your responsibility to set a simple source
1136  * material before calling cogl_begin_gl(). E.g. by calling
1137  * cogl_set_source_color4ub().</note>
1138  *
1139  * <note>It is your responsibility to restore any OpenGL state that you modify
1140  * to how it was after calling cogl_begin_gl() if you don't do this then the
1141  * result of further Cogl calls is undefined.</note>
1142  *
1143  * <note>You can not nest begin/end blocks.</note>
1144  *
1145  * Again we would like to stress, we do not advise the use of this API and if
1146  * possible we would prefer to improve Cogl than have developers require raw
1147  * OpenGL.
1148  *
1149  * Since: 1.0
1150  */
1151 void
1152 cogl_begin_gl (void);
1153
1154 /**
1155  * cogl_end_gl:
1156  *
1157  * This is the counterpart to cogl_begin_gl() used to delimit blocks of drawing
1158  * code using raw OpenGL. Please refer to cogl_begin_gl() for full details.
1159  *
1160  * Since: 1.0
1161  */
1162 void
1163 cogl_end_gl (void);
1164
1165 G_END_DECLS
1166
1167 #endif /* __COGL_1_CONTEXT_H__ */