4 * An object oriented GL/GLES Abstraction/Utility Layer
6 * Copyright (C) 2010 Intel Corporation.
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.
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.
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/>.
23 * Robert Bragg <robert@linux.intel.com>
27 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
28 #error "Only <cogl/cogl.h> can be included directly."
31 #ifndef __COGL_1_CONTEXT_H__
32 #define __COGL_1_CONTEXT_H__
36 #include <cogl/cogl-types.h>
37 #include <cogl/cogl-texture.h>
38 #include <cogl/cogl-framebuffer.h>
43 * cogl_get_option_group:
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.
49 * Return value: a #GOptionGroup
54 cogl_get_option_group (void);
60 * Returns all of the features supported by COGL.
62 * Return value: A logical OR of all the supported COGL features.
67 cogl_get_features (void);
70 * cogl_features_available:
71 * @features: A bitmask of features to check for
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
78 * Return value: %TRUE if the features are available, %FALSE otherwise.
81 cogl_features_available (CoglFeatureFlags features);
84 * cogl_get_proc_address:
85 * @name: the name of the function.
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.
91 * Return value: a pointer to the requested function or %NULL if the
92 * function is not available.
95 cogl_get_proc_address (const char *name);
97 #ifndef COGL_DISABLE_DEPRECATED
100 * cogl_check_extension:
101 * @name: extension to check for
102 * @ext: list of extensions
104 * Check whether @name occurs in list of extensions in @ext.
106 * Return value: %TRUE if the extension occurs in the list, %FALSE otherwise.
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:
112 * gboolean retval = (strstr (ext, name) != NULL) ? TRUE : FALSE;
116 cogl_check_extension (const char *name,
117 const char *ext) G_GNUC_DEPRECATED;
119 #endif /* COGL_DISABLE_DEPRECATED */
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
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.
133 cogl_get_bitmasks (int *red,
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)
145 * Replaces the current projection matrix with a perspective matrix
146 * based on the provided values.
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>
154 cogl_perspective (float fovy,
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)
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.
179 cogl_frustum (float left,
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)
197 * Replaces the current projection matrix with an orthographic projection
198 * matrix. See <xref linkend="cogl-ortho-matrix"/> to see how the matrix is
201 * <figure id="cogl-ortho-matrix">
203 * <graphic fileref="cogl_ortho.png" format="PNG"/>
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>
216 cogl_ortho (float left,
223 #ifndef COGL_DISABLE_DEPRECATED
227 * @width: Width of the viewport
228 * @height: Height of the viewport
230 * Replace the current viewport with the given values.
234 * Deprecated: 1.2: Use cogl_set_viewport() instead
237 cogl_viewport (unsigned int width,
238 unsigned int height) G_GNUC_DEPRECATED;
240 #endif /* COGL_DISABLE_DEPRECATED */
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
249 * Replaces the current viewport with the given values.
254 cogl_set_viewport (int x,
262 * Stores the current model-view matrix on the matrix stack. The matrix
263 * can later be restored with cogl_pop_matrix().
266 cogl_push_matrix (void);
271 * Restores the current model-view matrix from the matrix stack.
274 cogl_pop_matrix (void);
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
282 * Multiplies the current model-view matrix by one that scales the x,
283 * y and z axes by the given values.
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
296 * Multiplies the current model-view matrix by one that translates the
297 * model along all three axes according to the given values.
300 cogl_translate (float x,
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.
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
318 cogl_rotate (float angle,
325 * @matrix: the matrix to multiply with the current model-view
327 * Multiplies the current model-view matrix by the given matrix.
332 cogl_transform (const CoglMatrix *matrix);
335 * cogl_get_modelview_matrix:
336 * @matrix: (out): return location for the model-view matrix
338 * Stores the current model-view matrix in @matrix.
341 cogl_get_modelview_matrix (CoglMatrix *matrix);
344 * cogl_set_modelview_matrix:
345 * @matrix: the new model-view matrix
347 * Loads @matrix as the new model-view matrix.
350 cogl_set_modelview_matrix (CoglMatrix *matrix);
353 * cogl_get_projection_matrix:
354 * @matrix: (out): return location for the projection matrix
356 * Stores the current projection matrix in @matrix.
359 cogl_get_projection_matrix (CoglMatrix *matrix);
362 * cogl_set_projection_matrix:
363 * @matrix: the new projection matrix
365 * Loads matrix as the new projection matrix.
368 cogl_set_projection_matrix (CoglMatrix *matrix);
372 * @v: (out) (array fixed-size=4): pointer to a 4 element array
373 * of #float<!-- -->s to receive the viewport dimensions.
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
380 cogl_get_viewport (float v[4]);
383 * cogl_set_depth_test_enabled:
384 * @setting: %TRUE to enable depth testing or %FALSE to disable.
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.
392 * Deprecated: 1.4: Use cogl_material_set_depth_test_enabled()
396 cogl_set_depth_test_enabled (gboolean setting);
399 * cogl_get_depth_test_enabled:
401 * Queries if depth testing has been enabled via cogl_set_depth_test_enable()
403 * Return value: %TRUE if depth testing is enabled, and %FALSE otherwise
405 * Deprecated: 1.4: Use cogl_material_get_depth_test_enabled()
409 cogl_get_depth_test_enabled (void);
412 * cogl_set_backface_culling_enabled:
413 * @setting: %TRUE to enable backface culling or %FALSE to disable.
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.
422 cogl_set_backface_culling_enabled (gboolean setting);
425 * cogl_get_backface_culling_enabled:
427 * Queries if backface culling has been enabled via
428 * cogl_set_backface_culling_enabled()
430 * Return value: %TRUE if backface culling is enabled, and %FALSE otherwise
433 cogl_get_backface_culling_enabled (void);
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
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().
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>
461 cogl_set_fog (const CoglColor *fog_color,
470 * This function disables fogging, so primitives drawn afterwards will not be
471 * blended with any previously set fog color.
474 cogl_disable_fog (void);
478 * @color: Background color to clear to
479 * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
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.
486 cogl_clear (const CoglColor *color,
487 unsigned long buffers);
491 * @material: A #CoglMaterial
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().
501 cogl_set_source (void *material);
506 * Returns the current source material as previously set using
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>
515 * Return value: The current source material.
520 cogl_get_source (void);
524 * @material: A #CoglMaterial
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().
533 cogl_push_source (void *material);
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().
545 cogl_pop_source (void);
548 * cogl_set_source_color:
549 * @color: a #CoglColor
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
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.
559 * See also cogl_set_source_color4ub() and cogl_set_source_color4f()
560 * if you already have the color components.
565 cogl_set_source_color (const CoglColor *color);
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
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.
578 * The value for each component is an unsigned byte in the range
584 cogl_set_source_color4ub (guint8 red,
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
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.
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.
607 cogl_set_source_color4f (float red,
613 * cogl_set_source_texture:
614 * @texture: The #CoglTexture you want as your source
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
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:
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);
633 cogl_set_source_texture (CoglTexture *texture);
637 * SECTION:cogl-clipping
638 * @short_description: Fuctions for manipulating a stack of clipping regions
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.
645 #ifndef COGL_DISABLE_DEPRECATED
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
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.
660 * The rectangle is intersected with the current clip region. To undo
661 * the effect of this function, call cogl_clip_pop().
663 * Deprecated: 1.2: Use cogl_clip_push_window_rectangle() instead
666 cogl_clip_push_window_rect (float x_offset,
669 float height) G_GNUC_DEPRECATED;
671 #endif /* COGL_DISABLE_DEPRECATED */
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
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.
686 * The rectangle is intersected with the current clip region. To undo
687 * the effect of this function, call cogl_clip_pop().
692 cogl_clip_push_window_rectangle (int x_offset,
697 #ifndef COGL_DISABLE_DEPRECATED
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
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.
712 * The rectangle is intersected with the current clip region. To undo
713 * the effect of this function, call cogl_clip_pop().
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()
722 cogl_clip_push (float x_offset,
725 float height) G_GNUC_DEPRECATED;
727 #endif /* COGL_DISABLE_DEPRECATED */
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
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.
742 * The rectangle is intersected with the current clip region. To undo
743 * the effect of this function, call cogl_clip_pop().
748 cogl_clip_push_rectangle (float x0,
754 * cogl_clip_push_from_path_preserve:
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
764 cogl_clip_push_from_path_preserve (void);
766 #ifdef COGL_ENABLE_EXPERIMENTAL_2_0_API
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
772 * @bounds_y1: y coordinate for the top-left corner of the primitives
774 * @bounds_x2: x coordinate for the top-left corner of the primitives
776 * @bounds_y2: x coordinate for the bottom-right corner of the
778 * @bounds_x1: y coordinate for the bottom-right corner of the
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.
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
795 * Stability: unstable
798 cogl_clip_push_primitive (CoglPrimitive *primitive,
808 * Reverts the clipping region to the state before the last call to
812 cogl_clip_pop (void);
814 #ifndef COGL_DISABLE_DEPRECATED
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
824 * Deprecated: 1.2: Calling this function has no effect
829 cogl_clip_ensure (void) G_GNUC_DEPRECATED;
832 * cogl_clip_stack_save:
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().
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
849 cogl_clip_stack_save (void) G_GNUC_DEPRECATED;
852 * cogl_clip_stack_restore:
854 * Restore the state of the clipping stack that was previously saved
855 * by cogl_clip_stack_save().
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
866 cogl_clip_stack_restore (void) G_GNUC_DEPRECATED;
868 #endif /* COGL_DISABLE_DEPRECATED */
871 * cogl_set_framebuffer:
872 * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
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.
881 cogl_set_framebuffer (CoglFramebuffer *buffer);
884 * cogl_push_framebuffer:
885 * @buffer: A #CoglFramebuffer object, either onscreen or offscreen.
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.
891 * You should understand that a framebuffer owns the following state:
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>
898 * So these items will automatically be saved and restored when you
899 * push and pop between different framebuffers.
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
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:
913 * setup_viewport (unsigned int width,
914 * unsigned int height,
921 * CoglMatrix projection_matrix;
922 * CoglMatrix mv_matrix;
924 * cogl_set_viewport (0, 0, width, height);
925 * cogl_perspective (fovy, aspect, z_near, z_far);
927 * cogl_get_projection_matrix (&projection_matrix);
928 * z_camera = 0.5 * projection_matrix.xx;
930 * cogl_matrix_init_identity (&mv_matrix);
931 * cogl_matrix_translate (&mv_matrix, -0.5f, -0.5f, -z_camera);
932 * cogl_matrix_scale (&mv_matrix, 1.0f / width, -1.0f / height, 1.0f / width);
933 * cogl_matrix_translate (&mv_matrix, 0.0f, -1.0 * height, 0.0f);
934 * cogl_set_modelview_matrix (&mv_matrix);
938 * my_init_framebuffer (ClutterStage *stage,
939 * CoglFramebuffer *framebuffer,
940 * unsigned int framebuffer_width,
941 * unsigned int framebuffer_height)
943 * ClutterPerspective perspective;
945 * clutter_stage_get_perspective (stage, &perspective);
947 * cogl_push_framebuffer (framebuffer);
948 * setup_viewport (framebuffer_width,
949 * framebuffer_height,
951 * perspective.aspect,
952 * perspective.z_near,
953 * perspective.z_far);
957 * The previous framebuffer can be restored by calling cogl_pop_framebuffer()
962 cogl_push_framebuffer (CoglFramebuffer *buffer);
965 * cogl_pop_framebuffer:
967 * Restores the framebuffer that was previously at the top of the stack.
968 * All subsequent drawing will be redirected to this framebuffer.
973 cogl_pop_framebuffer (void);
975 #ifndef COGL_DISABLE_DEPRECATED
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.
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.
989 * Deprecated: 1.2: The target argument was redundant since we could look at
990 * the type of CoglHandle given instead.
993 cogl_set_draw_buffer (CoglBufferTarget target,
994 CoglHandle offscreen) G_GNUC_DEPRECATED;
997 * cogl_push_draw_buffer:
999 * Save cogl_set_draw_buffer() state.
1001 * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API
1004 cogl_push_draw_buffer (void) G_GNUC_DEPRECATED;
1007 * cogl_pop_draw_buffer:
1009 * Restore cogl_set_draw_buffer() state.
1011 * Deprecated: 1.2: The draw buffer API was replaced with a framebuffer API
1014 cogl_pop_draw_buffer (void) G_GNUC_DEPRECATED;
1016 #endif /* COGL_DISABLE_DEPRECATED */
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.
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).
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.
1041 cogl_read_pixels (int x,
1045 CoglReadPixelsFlags source,
1046 CoglPixelFormat format,
1052 * This function should only need to be called in exceptional circumstances.
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.
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.
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.
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.
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
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:
1092 * - setup some OpenGL state.
1093 * - draw using OpenGL (e.g. glDrawArrays() )
1094 * - reset modified OpenGL state.
1095 * - continue using Cogl to draw
1099 * You should surround blocks of drawing using raw GL with cogl_begin_gl()
1100 * and cogl_end_gl():
1105 * - setup some OpenGL state.
1106 * - draw using OpenGL (e.g. glDrawArrays() )
1107 * - reset modified OpenGL state.
1109 * - continue using Cogl to draw
1113 * Don't ever try and do:
1117 * - setup some OpenGL state.
1118 * - use Cogl to draw
1119 * - reset modified OpenGL state.
1123 * When the internals of Cogl evolves, this is very liable to break.
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
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
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>
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>
1143 * <note>You can not nest begin/end blocks.</note>
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
1152 cogl_begin_gl (void);
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.
1167 #endif /* __COGL_1_CONTEXT_H__ */