4
* An object oriented GL/GLES Abstraction/Utility Layer
6
* Copyright (C) 2008,2009 Intel Corporation.
8
* This library is free software; you can redistribute it and/or
10
* modify it under the terms of the GNU Lesser General Public
11
* License as published by the Free Software Foundation; either
12
* version 2 of the License, or (at your option) any later version.
14
* This library is distributed in the hope that it will be useful,
15
* but WITHOUT ANY WARRANTY; without even the implied warranty of
16
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
* Lesser General Public License for more details.
19
* You should have received a copy of the GNU Lesser General Public
20
* License along with this library; if not, write to the
21
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22
* Boston, MA 02111-1307, USA.
30
#define __COGL_H_INSIDE__
32
#include <cogl/cogl-defines-@CLUTTER_COGL@.h>
34
#include <cogl/cogl-vertex-buffer.h>
35
#include <cogl/cogl-matrix.h>
36
#include <cogl/cogl-vertex-buffer.h>
37
#include <cogl/cogl-fixed.h>
38
#include <cogl/cogl-color.h>
39
#include <cogl/cogl-offscreen.h>
40
#include <cogl/cogl-material.h>
41
#include <cogl/cogl-path.h>
42
#include <cogl/cogl-shader.h>
43
#include <cogl/cogl-bitmap.h>
44
#include <cogl/cogl-texture.h>
45
#include <cogl/cogl-types.h>
46
#include <cogl/cogl-debug.h>
47
#include <cogl/cogl-deprecated.h>
48
#include <cogl/cogl-enum-types.h>
54
* @short_description: General purpose API
56
* General utility functions for COGL.
60
* cogl_get_option_group:
62
* Retrieves the #GOptionGroup used by COGL to parse the command
63
* line options. Clutter uses this to handle the COGL command line
64
* options during its initialization process.
66
* Return value: a #GOptionGroup
70
GOptionGroup * cogl_get_option_group (void);
76
* Returns all of the features supported by COGL.
78
* Return value: A logical OR of all the supported COGL features.
82
CoglFeatureFlags cogl_get_features (void);
85
* cogl_features_available:
86
* @features: A bitmask of features to check for
88
* Checks whether the given COGL features are available. Multiple
89
* features can be checked for by or-ing them together with the '|'
90
* operator. %TRUE is only returned if all of the requested features
93
* Return value: %TRUE if the features are available, %FALSE otherwise.
95
gboolean cogl_features_available (CoglFeatureFlags features);
98
* cogl_get_proc_address:
99
* @name: the name of the function.
101
* Gets a pointer to a given GL or GL ES extension function. This acts
102
* as a wrapper around glXGetProcAddress() or whatever is the
103
* appropriate function for the current backend.
105
* Return value: a pointer to the requested function or %NULL if the
106
* function is not available.
108
CoglFuncPtr cogl_get_proc_address (const gchar *name);
111
* cogl_check_extension:
112
* @name: extension to check for
113
* @ext: list of extensions
115
* Check whether @name occurs in list of extensions in @ext.
117
* Returns: %TRUE if the extension occurs in the list, %FALSE otherwize.
119
gboolean cogl_check_extension (const gchar *name,
124
* @red: Return location for the number of red bits or %NULL
125
* @green: Return location for the number of green bits or %NULL
126
* @blue: Return location for the number of blue bits or %NULL
127
* @alpha: Return location for the number of alpha bits or %NULL
129
* Gets the number of bitplanes used for each of the color components
130
* in the color buffer. Pass %NULL for any of the arguments if the
131
* value is not required.
133
void cogl_get_bitmasks (gint *red,
140
* @fovy: Vertical of view angle in degrees.
141
* @aspect: Aspect ratio of diesplay
142
* @z_near: Nearest visible point
143
* @z_far: Furthest visible point along the z-axis
145
* Replaces the current projection matrix with a perspective matrix
146
* based on the provided values.
148
void cogl_perspective (float fovy,
155
* @left: Left clipping plane
156
* @right: Right clipping plane
157
* @bottom: Bottom clipping plane
158
* @top: Top clipping plane
159
* @z_near: Nearest visible point
160
* @z_far: Furthest visible point along the z-axis
162
* Replaces the current projection matrix with a perspective matrix
163
* for the given viewing frustum.
167
void cogl_frustum (float left,
176
* @left: The coordinate for the left clipping plane
177
* @right: The coordinate for the right clipping plane
178
* @bottom: The coordinate for the bottom clipping plane
179
* @top: The coordinate for the top clipping plane
180
* @near: The coordinate for the near clipping plane (may be negative if
181
* the plane is behind the viewer)
182
* @far: The coordinate for the far clipping plane (may be negative if
183
* the plane is behind the viewer)
185
* Replaces the current projection matrix with a parallel projection
190
void cogl_ortho (float left,
198
* _cogl_setup_viewport:
199
* @width: Width of the viewport
200
* @height: Height of the viewport
201
* @fovy: Field of view angle in degrees
202
* @aspect: Aspect ratio to determine the field of view along the x-axis
203
* @z_near: Nearest visible point along the z-axis
204
* @z_far: Furthest visible point along the z-axis
206
* Replaces the current viewport and projection matrix with the given
207
* values. The viewport is placed at the top left corner of the window
208
* with the given width and height. The projection matrix is replaced
209
* with one that has a viewing angle of @fovy along the y-axis and a
210
* view scaled according to @aspect along the x-axis. The view is
211
* clipped according to @z_near and @z_far on the z-axis.
213
* This function is used only by Clutter.
215
void _cogl_setup_viewport (guint width,
224
* @width: Width of the viewport
225
* @height: Height of the viewport
227
* Replace the current viewport with the given values.
231
void cogl_viewport (guint width,
237
* Store the current model-view matrix on the matrix stack. The matrix
238
* can later be restored with cogl_pop_matrix().
240
void cogl_push_matrix (void);
245
* Restore the current model-view matrix from the matrix stack.
247
void cogl_pop_matrix (void);
251
* @x: Amount to scale along the x-axis
252
* @y: Amount to scale along the y-axis
253
* @z: Amount to scale along the z-axis
255
* Multiplies the current model-view matrix by one that scales the x,
256
* y and z axes by the given values.
258
void cogl_scale (float x,
264
* @x: Distance to translate along the x-axis
265
* @y: Distance to translate along the y-axis
266
* @z: Distance to translate along the z-axis
268
* Multiplies the current model-view matrix by one that translates the
269
* model along all three axes according to the given values.
271
void cogl_translate (float x,
277
* @angle: Angle in degrees to rotate.
278
* @x: X-component of vertex to rotate around.
279
* @y: Y-component of vertex to rotate around.
280
* @z: Z-component of vertex to rotate around.
282
* Multiplies the current model-view matrix by one that rotates the
283
* model around the vertex specified by @x, @y and @z. The rotation
284
* follows the right-hand thumb rule so for example rotating by 10
285
* degrees about the vertex (0, 0, 1) causes a small counter-clockwise
288
void cogl_rotate (float angle,
294
* cogl_get_modelview_matrix:
295
* @matrix: pointer to a CoglMatrix to recieve the matrix
297
* Stores the current model-view matrix in @matrix.
299
void cogl_get_modelview_matrix (CoglMatrix *matrix);
302
* cogl_set_modelview_matrix:
303
* @matrix: pointer to a CoglMatrix to set as the new model-view matrix
305
* Loads matrix as the new model-view matrix.
307
void cogl_set_modelview_matrix (CoglMatrix *matrix);
310
* cogl_get_projection_matrix:
311
* @matrix: pointer to a CoglMatrix to recieve the matrix
313
* Stores the current projection matrix in @matrix.
315
void cogl_get_projection_matrix (CoglMatrix *matrix);
318
* cogl_set_projection_matrix:
319
* @matrix: pointer to a CoglMatrix to set as the new projection matrix
321
* Loads matrix as the new projection matrix.
323
void cogl_set_projection_matrix (CoglMatrix *matrix);
327
* @v: pointer to a 4 element array of #float<!-- -->s to
328
* receive the viewport dimensions.
330
* Stores the current viewport in @v. @v[0] and @v[1] get the x and y
331
* position of the viewport and @v[2] and @v[3] get the width and
334
void cogl_get_viewport (float v[4]);
337
* cogl_set_depth_test_enabled:
338
* @setting: %TRUE to enable depth testing or %FALSE to disable.
340
* Sets whether depth testing is enabled. If it is disabled then the
341
* order that actors are layered on the screen depends solely on the
342
* order specified using clutter_actor_raise() and
343
* clutter_actor_lower(), otherwise it will also take into account the
344
* actor's depth. Depth testing is disabled by default.
346
void cogl_set_depth_test_enabled (gboolean setting);
349
* cogl_get_depth_test_enabled:
351
* Queries if depth testing has been enabled via cogl_set_depth_test_enable()
353
* Returns: %TRUE if depth testing is enabled, and %FALSE otherwise
355
gboolean cogl_get_depth_test_enabled (void);
358
* cogl_set_backface_culling_enabled:
359
* @setting: %TRUE to enable backface culling or %FALSE to disable.
361
* Sets whether textures positioned so that their backface is showing
362
* should be hidden. This can be used to efficiently draw two-sided
363
* textures or fully closed cubes without enabling depth testing. This
364
* only affects calls to the cogl_rectangle* family of functions and
365
* cogl_vertex_buffer_draw*. Backface culling is disabled by default.
367
void cogl_set_backface_culling_enabled (gboolean setting);
370
* cogl_get_backface_culling_enabled:
372
* Queries if backface culling has been enabled via
373
* cogl_set_backface_culling_enabled()
375
* Returns: %TRUE if backface culling is enabled, and %FALSE otherwise
377
gboolean cogl_get_backface_culling_enabled (void);
381
* @fog_color: The color of the fog
382
* @mode: A CoglFogMode that determines the equation used to calculate the
383
* fogging blend factor.
384
* @density: Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode
386
* @z_near: Position along z-axis where no fogging should be applied
387
* @z_far: Position along z-axes where full fogging should be applied
389
* Enables fogging. Fogging causes vertices that are further away from the eye
390
* to be rendered with a different color. The color is determined according to
391
* the chosen fog mode; at it's simplest the color is linearly interpolated so
392
* that vertices at @z_near are drawn fully with their original color and
393
* vertices at @z_far are drawn fully with @fog_color. Fogging will remain
394
* enabled until you call cogl_disable_fog().
396
* <note>The fogging functions only work correctly when primitives use
397
* unmultiplied alpha colors. By default Cogl will premultiply textures
398
* and cogl_set_source_color() will premultiply colors, so unless you
399
* explicitly load your textures requesting an unmultiplied internal format
400
* and use cogl_material_set_color() you can only use fogging with fully
401
* opaque primitives. This might improve in the future when we can depend
402
* on fragment shaders.</note>
404
void cogl_set_fog (const CoglColor *fog_color,
413
* This function disables fogging, so primitives drawn afterwards will not be
414
* blended with any previously set fog color.
416
void cogl_disable_fog (void);
420
* @COGL_BUFFER_BIT_COLOR: Selects the primary color buffer
421
* @COGL_BUFFER_BIT_DEPTH: Selects the depth buffer
422
* @COGL_BUFFER_BIT_STENCIL: Selects the stencil buffer
424
* Types of auxiliary buffers
429
COGL_BUFFER_BIT_COLOR = 1L<<0,
430
COGL_BUFFER_BIT_DEPTH = 1L<<1,
431
COGL_BUFFER_BIT_STENCIL = 1L<<2
436
* @color: Background color to clear to
437
* @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary
440
* Clears all the auxiliary buffers identified in the @buffers mask, and if
441
* that includes the color buffer then the specified @color is used.
443
void cogl_clear (const CoglColor *color,
448
* @material: A CoglMaterial object
450
* This function sets the source material that will be used to fill subsequent
451
* geometry emitted via the cogl API.
453
* Note: in the future we may add the ability to set a front facing material,
454
* and a back facing material, in which case this function will set both to the
459
void cogl_set_source (CoglHandle material);
462
* cogl_set_source_color:
463
* @color: a #CoglColor
465
* This is a convenience function for creating a solid fill source material
466
* from the given color. This color will be used for any subsequent drawing
469
* The color will be premultiplied by Cogl, so the color should be
470
* non-premultiplied. For example: use (1.0, 0.0, 0.0, 0.5) for
471
* semi-transparent red.
473
* See also cogl_set_source_color4ub() and cogl_set_source_color4f()
474
* if you already have the color components.
478
void cogl_set_source_color (const CoglColor *color);
481
* cogl_set_source_color4ub:
482
* @red: value of the red channel, between 0 and 255
483
* @green: value of the green channel, between 0 and 255
484
* @blue: value of the blue channel, between 0 and 255
485
* @alpha: value of the alpha channel, between 0 and 255
487
* This is a convenience function for creating a solid fill source material
488
* from the given color using unsigned bytes for each component. This
489
* color will be used for any subsequent drawing operation.
491
* The value for each component is an unsigned byte in the range
496
void cogl_set_source_color4ub (guint8 red,
502
* cogl_set_source_color4f:
503
* @red: value of the red channel, between 0 and %1.0
504
* @green: value of the green channel, between 0 and %1.0
505
* @blue: value of the blue channel, between 0 and %1.0
506
* @alpha: value of the alpha channel, between 0 and %1.0
508
* This is a convenience function for creating a solid fill source material
509
* from the given color using normalized values for each component. This color
510
* will be used for any subsequent drawing operation.
512
* The value for each component is a fixed point number in the range
513
* between 0 and %1.0. If the values passed in are outside that
514
* range, they will be clamped.
518
void cogl_set_source_color4f (float red,
524
* cogl_set_source_texture:
525
* @texture_handle: The Cogl texture you want as your source
527
* This is a convenience function for creating a material with the first
528
* layer set to #texture_handle and setting that material as the source with
531
* Note: There is no interaction between calls to cogl_set_source_color
532
* and cogl_set_source_texture. If you need to blend a texture with a color then
533
* you can create a simple material like this:
535
* material = cogl_material_new ();
536
* cogl_material_set_color4ub (material, 0xff, 0x00, 0x00, 0x80);
537
* cogl_material_set_layer (material, 0, tex_handle);
538
* cogl_set_source (material);
543
void cogl_set_source_texture (CoglHandle texture_handle);
546
* SECTION:cogl-clipping
547
* @short_description: Fuctions for manipulating a stack of clipping regions
549
* To support clipping your geometry to rectangles or paths Cogl exposes a
550
* stack based API whereby each clip region you push onto the stack is
551
* intersected with the previous region.
555
* cogl_clip_push_window_rect:
556
* @x_offset: left edge of the clip rectangle in window coordinates
557
* @y_offset: top edge of the clip rectangle in window coordinates
558
* @width: width of the clip rectangle
559
* @height: height of the clip rectangle
561
* Specifies a rectangular clipping area for all subsequent drawing
562
* operations. Any drawing commands that extend outside the rectangle
563
* will be clipped so that only the portion inside the rectangle will
564
* be displayed. The rectangle dimensions are not transformed by the
565
* current model-view matrix.
567
* The rectangle is intersected with the current clip region. To undo
568
* the effect of this function, call cogl_clip_pop().
570
void cogl_clip_push_window_rect (float x_offset,
577
* @x_offset: left edge of the clip rectangle
578
* @y_offset: top edge of the clip rectangle
579
* @width: width of the clip rectangle
580
* @height: height of the clip rectangle
582
* Specifies a rectangular clipping area for all subsequent drawing
583
* operations. Any drawing commands that extend outside the rectangle
584
* will be clipped so that only the portion inside the rectangle will
585
* be displayed. The rectangle dimensions are transformed by the
586
* current model-view matrix.
588
* The rectangle is intersected with the current clip region. To undo
589
* the effect of this function, call cogl_clip_pop().
591
void cogl_clip_push (float x_offset,
597
* cogl_clip_push_from_path:
599
* Sets a new clipping area using the current path. The current path
600
* is then cleared. The clipping area is intersected with the previous
601
* clipping area. To restore the previous clipping area, call
606
void cogl_clip_push_from_path (void);
609
* cogl_clip_push_from_path_preserve:
611
* Sets a new clipping area using the current path. The current path
612
* is then cleared. The clipping area is intersected with the previous
613
* clipping area. To restore the previous clipping area, call
618
void cogl_clip_push_from_path_preserve (void);
623
* Reverts the clipping region to the state before the last call to
626
void cogl_clip_pop (void);
631
* Ensures that the current clipping region has been set in GL. This
632
* will automatically be called before any Cogl primitives but it
633
* maybe be neccessary to call if you are using raw GL calls with
638
void cogl_clip_ensure (void);
641
* cogl_clip_stack_save:
643
* Save the entire state of the clipping stack and then clear all
644
* clipping. The previous state can be returned to with
645
* cogl_clip_stack_restore(). Each call to cogl_clip_push() after this
646
* must be matched by a call to cogl_clip_pop() before calling
647
* cogl_clip_stack_restore().
651
void cogl_clip_stack_save (void);
654
* cogl_clip_stack_restore:
656
* Restore the state of the clipping stack that was previously saved
657
* by cogl_clip_stack_save().
661
void cogl_clip_stack_restore (void);
664
* cogl_set_draw_buffer:
665
* @target: A #CoglBufferTarget that specifies what kind of draw buffer you
666
* are setting as the render target.
667
* @offscreen: If you are setting a draw buffer of type COGL_OFFSCREEN_BUFFER
668
* then this is a CoglHandle for the offscreen buffer.
670
* This redirects all subsequent drawing to the specified draw buffer. This
671
* can either be an offscreen buffer created with
672
* cogl_offscreen_new_to_texture () or you can revert to your original
673
* on screen window buffer.
675
void cogl_set_draw_buffer (CoglBufferTarget target,
676
CoglHandle offscreen);
679
* cogl_push_draw_buffer:
681
* Save cogl_set_draw_buffer() state.
683
void cogl_push_draw_buffer (void);
686
* cogl_pop_draw_buffer:
688
* Restore cogl_set_draw_buffer() state.
690
void cogl_pop_draw_buffer (void);
693
* CoglReadPixelsFlags:
694
* @COGL_READ_PIXELS_COLOR_BUFFER: Read from the color buffer
696
* Flags for cogl_read_pixels()
700
typedef enum { /*< prefix=COGL_READ_PIXELS >*/
701
COGL_READ_PIXELS_COLOR_BUFFER = 1L << 0
702
} CoglReadPixelsFlags;
706
* @x: The window x position to start reading from
707
* @y: The window y position to start reading from
708
* @width: The width of the rectangle you want to read
709
* @height: The height of the rectangle you want to read
710
* @source: Identifies which auxillary buffer you want to read
711
* (only COGL_READ_PIXELS_COLOR_BUFFER supported currently)
712
* @format: The pixel format you want the result in
713
* (only COGL_PIXEL_FORMAT_RGBA_8888 supported currently)
714
* @pixels: The location to write the pixel data.
716
* This reads a rectangle of pixels from the current draw buffer where
717
* position (0, 0) is the top left. The pixel at (x, y) is the first
718
* read, and the data is returned with a rowstride of (width * 4)
720
void cogl_read_pixels (int x,
724
CoglReadPixelsFlags source,
725
CoglPixelFormat format,
731
* This function should only need to be called in exceptional circumstances.
733
* As an optimization Cogl drawing functions may batch up primitives
734
* internally, so if you are trying to use raw GL outside of Cogl you stand a
735
* better chance of being successful if you ask Cogl to flush any batched
736
* geometry before making your state changes.
738
* It only ensure that the underlying driver is issued all the commands
739
* necessary to draw the batched primitives. It provides no guarantees about
740
* when the driver will complete the rendering.
742
* This provides no guarantees about the GL state upon returning and to avoid
743
* confusing Cogl you should aim to restore any changes you make before
744
* resuming use of Cogl.
746
* If you are making state changes with the intention of affecting Cogl drawing
747
* primitives you are 100% on your own since you stand a good chance of
748
* conflicting with Cogl internals. For example clutter-gst which currently
749
* uses direct GL calls to bind ARBfp programs will very likely break when Cogl
750
* starts to use ARBfb programs itself for the material API.
754
void cogl_flush (void);
759
* We do not advise nor reliably support the interleaving of raw GL drawing and
760
* Cogl drawing functions, but if you insist, cogl_begin_gl() and cogl_end_gl()
761
* provide a simple mechanism that may at least give you a fighting chance of
764
* Note: this doesn't help you modify the behaviour of Cogl drawing functions
765
* through the modification of GL state; that will never be reliably supported,
766
* but if you are trying to do something like:
769
* - setup some OpenGL state.
770
* - draw using OpenGL (e.g. glDrawArrays() )
771
* - reset modified OpenGL state.
772
* - continue using Cogl to draw
775
* You should surround blocks of drawing using raw GL with cogl_begin_gl()
780
* - setup some OpenGL state.
781
* - draw using OpenGL (e.g. glDrawArrays() )
782
* - reset modified OpenGL state.
784
* - continue using Cogl to draw
788
* Don't ever try and do:
791
* - setup some OpenGL state.
793
* - reset modified OpenGL state.
796
* When the internals of Cogl evolves, this is very liable to break.
798
* This function will flush all batched primitives, and subsequently flush
799
* all internal Cogl state to OpenGL as if it were going to draw something
802
* The result is that the OpenGL modelview matrix will be setup; the state
803
* corresponding to the current source material will be set up and other world
804
* state such as backface culling, depth and fogging enabledness will be sent
807
* Note: no special material state is flushed, so if you want Cogl to setup a
808
* simplified material state it is your responsibility to set a simple source
809
* material before calling cogl_begin_gl. E.g. by calling
810
* cogl_set_source_color4ub().
812
* Note: It is your responsibility to restore any OpenGL state that you modify
813
* to how it was after calling cogl_begin_gl() if you don't do this then the
814
* result of further Cogl calls is undefined.
816
* Note: You can not nest begin/end blocks.
818
* Again we would like to stress, we do not advise the use of this API and if
819
* possible we would prefer to improve Cogl than have developers require raw
824
void cogl_begin_gl (void);
829
* This is the counterpart to cogl_begin_gl() used to delimit blocks of drawing
830
* code using raw OpenGL. Please refer to cogl_begin_gl() for full details.
834
void cogl_end_gl (void);
837
* Internal API available only to Clutter.
839
* These are typically only to deal with the poor seperation of
840
* responsabilities that currently exists between Clutter and Cogl.
841
* Eventually a lot of the backend code currently in Clutter will
842
* move down into Cogl and these functions will be removed.
845
void _cogl_destroy_context (void);
847
/* XXX: Removed before we release Clutter 1.0 since the implementation
848
* wasn't complete, and so we assume no one is using this yet. Util we
849
* have some one with a good usecase, we can't pretend to support breaking
850
* out into raw OpenGL. */
853
* cogl_flush_gl_state:
854
* @flags: flags controlling what is flushed; currently unused, pass in 0
856
* As an optimization, COGL functions may not immediately modify GL's
857
* state, instead batching up changes and applying them "just in
858
* time." Unapplied state could include glEnable() flags and the
859
* current transformation matrix among other examples. If you want to
860
* use GL directly, you need to flush any state COGL may have kept
861
* around. cogl_flush_gl_state() syncs all of COGL's state to GL.
865
void cogl_flush_gl_state (int flags);
869
void _cogl_set_indirect_context (gboolean indirect);
873
#undef __COGL_H_INSIDE__
875
#endif /* __COGL_H__ */
added
removed
clutter/cogl/cogl.h.in
