Commit Graph

171 Commits

Author SHA1 Message Date
Robert Bragg
fd10e3a545 matrix gtype: registers a boxed type for CoglMatrix
To allow us to have gobject properties that accept a CoglMatrix value we
need to register a GType. This adds a cogl_gtype_matrix_get_type function
that will register a static boxed type called "CoglMatrix".

This adds a new section to the reference manual for GType integration
functions.
2010-12-07 12:16:50 +00:00
Robert Bragg
e9e824fd86 matrix: Adds experimental cogl_matrix_{transform,project}_points
This add two new function that allows us to transform or project an
array of points instead of only transforming one point at a time. Recent
benchmarking has shown cogl_matrix_transform_point to be a bottleneck
sometimes, so this should allow us to reduce the overhead when
transforming lots of vertices at the same time, and also reduce the cost
of 3 component, non-projective transforms.

For now they are marked as experimental (you have to define
COGL_ENABLE_EXPERIMENTAL_API) because there is some concern that it
introduces some inconsistent naming. cogl_matrix_transform_point would
have to be renamed cogl_matrix_project_point to be consistent, but that
would be an API break.
2010-11-23 12:50:29 +00:00
Robert Bragg
1b9a247174 cogl: Adds {push,pop,get}_source functions
This exposes the idea of a stack of source materials instead of just
having a single current material. This allows the writing of orthogonal
code that can change the current source material and restore it to its
previous state. It also allows the implementation of new composite
primitives that may want to validate the current source material and
possibly make override changes in a derived material.
2010-10-26 12:08:20 +01:00
Robert Bragg
8150292879 docs: Put deprecated Cogl symbols into new section
This adds a "Cogl deprecated API" chapter to the Cogl reference manual
so we can group all the documentation for deprecated symbols together
instead of having them clutter up the documentation of symbols we would
rather developers used.
2010-09-23 15:53:30 +01:00
Robert Bragg
d9d0b78811 docs: update the overview paragraph for Cogl
Instead of describing OpenGL as "a low level OpenGL abstraction
library" it is now summarised as "modern 3D graphics API".
2010-09-23 15:53:30 +01:00
Robert Bragg
fb05fe7958 docs: cogl-texture-3d wasn't listed as experimental
The CoglTexture3D API is only available when defining
COGL_ENABLE_EXPERIMENTAL_API so it should be listed in the experimental
section of the API reference.
2010-09-23 15:53:30 +01:00
Robert Bragg
e5e892fe47 docs: Use "Cogl" not "COGL" in Cogl API reference
Cogl isn't an acronym so we should use "Cogl" instead of "COGL" in
our documentation.
2010-09-23 15:53:29 +01:00
Emmanuele Bassi
fd0cd2e55c docs: Fix up the Cogl API reference build 2010-09-03 17:15:22 +01:00
Emmanuele Bassi
e950d2feec docs: Add annotation glossary to the Cogl API reference
It's the only way to let gtk-doc know that we're using annotations in
the comments.
2010-09-03 16:52:06 +01:00
Emmanuele Bassi
a77e14c969 docs: Pass -DCOGL_ENABLE_EXPERIMENTAL_API when scanning 2010-08-28 21:21:08 +01:00
Robert Bragg
8d80a88e14 cogl-program: Adds use_uniform_xyz methods
Instead of exposing an API that provides an OpenGL state machine style
where you first have to bind the program to the context using
cogl_program_use() followed by updating uniforms using
cogl_program_uniform_xyz we now have uniform setter methods that take an
explicit CoglHandle for the program.

This deprecates cogl_program_use and all the cogl_program_uniform
variants and provides the following replacements:
    cogl_program_set_uniform_1i
    cogl_program_set_uniform_1f
    cogl_program_set_uniform_int
    cogl_program_set_uniform_float
    cogl_program_set_uniform_matrix
2010-08-12 16:50:46 +01:00
Neil Roberts
671abec8b7 Make the material functions for setting the p wrap mode public
Now that we have 3D texture support it makes sense to expose the wrap
mode for the p coordinate.
2010-07-13 14:29:07 +01:00
Neil Roberts
5288f6d88d Add a Cogl texture 3D backend
This adds a publicly exposed experimental API for a 3D texture
backend. There is a feature flag which can be checked for whether 3D
textures are supported. Although we require OpenGL 1.2 which has 3D
textures in core, GLES only provides them through an extension so the
feature can be used to detect that.

The textures can be created with one of two new API functions :-

cogl_texture_3d_new_with_size

 and

cogl_texture_3d_new_from_data

There is also internally a new_from_bitmap function. new_from_data is
implemented in terms of this function.

The two constructors are effectively the only way to upload data to a
3D texture. It does not work to call glTexImage2D with the
GL_TEXTURE_3D target so the virtual for cogl_texture_set_region does
nothing. It would be possible to make cogl_texture_get_data do
something sensible like returning all of the images as a single long
image but this is not currently implemented and instead the virtual
just always fails. We may want to add API specific to the 3D texture
backend to get and set a sub region of the texture.

All of those three functions can throw a GError. This will happen if
the GPU does not support 3D textures or it does not support NPOTs and
an NPOT size is requested. It will also fail if the FBO extension is
not supported and the COGL_TEXTURE_NO_AUTO_MIPMAP flag is not
given. This could be avoided by copying the code for the
GL_GENERATE_MIPMAP TexParameter fallback, but in the interests of
keeping the code simple this is not yet done.

This adds a couple of functions to cogl-texture-driver for uploading
3D data and querying the 3D proxy
texture. prep_gl_for_pixels_upload_full now also takes sets the
GL_UNPACK_IMAGE_HEIGHT parameter so that 3D textures can have padding
between the images. Whenever 3D texture is uploading, both the height
of the images and the height of all of the data is specified (either
explicitly or implicilty from the CoglBitmap) so that the image height
can be deduced by dividing by the depth.
2010-07-13 14:28:52 +01:00
Neil Roberts
42dcffbc3a Make a public CoglBitmapError enum
There are many places in the texture backend that need to do
conversion using the CoglBitmap code. Currently none of these
functions can throw an error but they do return a value to indicate
failure. In future it would make sense if new texture functions could
throw an error and in that case they would want to use a CoglBitmap
error if the failure was due to the conversion. This moves the
internal CoglBitmap error from the quartz backend to be public in
cogl-bitmap.h so that it can be used in this way.
2010-07-13 14:28:45 +01:00
Neil Roberts
9e3705ecb3 Add cogl_vertex_buffer_is_indices to the public headers
This function has always been defined in the shared library but it was
missed from the public headers.
2010-07-09 18:57:54 +01:00
Neil Roberts
da3be3df6b cogl-material: Add support for point sprites
This adds a new API call to enable point sprite coordinate generation
for a material layer:

void
cogl_material_set_layer_point_sprite_coords_enabled (CoglHandle material,
                                                     int layer_index,
                                                     gboolean enable);

There is also a corresponding get function.

Enabling point sprite coords simply sets the GL_COORD_REPLACE of the
GL_POINT_SPRITE glTexEnv when flusing the material. There is no
separate application control for glEnable(GL_POINT_SPRITE). Instead it
is left permanently enabled under the assumption that it has no affect
unless GL_COORD_REPLACE is enabled for a texture unit.

http://bugzilla.openedhand.com/show_bug.cgi?id=2047
2010-07-08 16:34:30 +01:00
Neil Roberts
06b58baa10 cogl-material: Add a property for setting the point size
This adds cogl_material_{get,set}_point_size. If the point size is not
1.0f then glPointSize will be called when the material is flushed.

http://bugzilla.openedhand.com/show_bug.cgi?id=2047
2010-07-08 16:34:30 +01:00
Emmanuele Bassi
be6335c870 docs: Add a cogl-paths section
The path primitives have a specific section, now, and gtk-doc is loudly
complaining about it being defined but not referenced.
2010-07-02 17:49:09 +01:00
Neil Roberts
cea74d92ea Convert the ASCII art documentation in cogl-vertex-buffer to PNGs
The documentation for cogl_vertex_buffer_indices_get_for_quads was
using ugly ASCII art to draw the diagrams. These have now been
replaced with PNG figures.
2010-07-02 17:29:34 +01:00
Neil Roberts
432c37bd21 Add CoglMaterialWrapMode to the Cogl docs and fix docs for the getters
CoglMaterialWrapMode was missing from the cogl-sections.txt file so it
wasn't getting displayed. There were also no documented return values
from the getters.
2010-07-02 17:29:34 +01:00
Emmanuele Bassi
6fbe92193f docs: Various fixes for gtk-doc 2010-06-30 15:51:12 +01:00
Neil Roberts
cdf5b222db cogl-path: Allow changing the fill rule
This adds two new API calls- cogl_path_set_fill_rule and
cogl_path_get_fill_rule. This allows modifying the fill rule of the
current path. In addition to the previous default fill rule of
'even-odd' it now supports the 'non-zero' rule. The fill rule is a
property of the path (not the Cogl context) so creating a new path or
preserving a path with cogl_path_get_handle affects the fill rule.
2010-06-29 20:37:14 +01:00
Robert Bragg
fca054e949 cogl docs: Improve documentation for cogl_ortho
cogl_ortho is one of those APIs whos style was, for better or worse,
copied from OpenGL and for some inexplicable reason the near and far
arguments are inconsistent with the left, right, top, bottom arguments
because they don't take z coordinates they take a "distance" which
should be negative for a plane behind the viewer.

This updates the documentation to explain this.
2010-06-15 15:26:28 +01:00
Damien Lespiau
98f2d2516b cogl-color: Provide setters for all the channels
We only had getters for the red, green, blue and alpha channels of a
color. This meant that, if you wanted to change, say, the alpha
component of a color, one would need to query the red, green and blue
channels and use set_from_4ub() or set_from_4f().

Instead of this, just provide some setters for CoglColor, using the same
naming scheme than the existing getters.
2010-06-10 20:02:01 +01:00
Damien Lespiau
896dd975d1 cogl-color: Add cogl_color_unpremultiply()
For some operations on pre-multiplied colors (say, replace the alpha
value), you need to unpremultiply the color.

This patch provides the counterpart to cogl_color_premultiply().
2010-06-10 20:01:48 +01:00
Damien Lespiau
2e52c5f67b doc: Some fixes for the Cogl documentation
• 3 general fixes (typos, copy/paste),
 • ignore cogl-object-private.h,
 • cogl_fixed_atani() was in reality cogl_fixed_atan(), fixed in commit
   43564f05.
 • Fix the cogl-vector section: sections must have a </SECTION> tag at
   the end. Also the cogl-vector section was added in the middle of the
   cogl-buffer one. Let's shiffle it out and add that </SECTION> tag.
2010-06-07 14:32:32 +01:00
Robert Bragg
5af3ead3a2 CoglObject: Adds cogl_object_{get,set}_user_data
This provides a mechanism for associating private data with any
CoglObject. We expect Clutter will use this to associate weak materials
with normal materials.
2010-06-04 14:44:15 +01:00
Robert Bragg
ef08c6369a cogl-path: Adds missing cogl_is_path prototype
This adds a missing cogl_is_path prototype to the public cogl-path.h
header.
2010-06-04 14:44:15 +01:00
Robert Bragg
368dc48372 cogl-path: Renames cogl_path_get/set cogl_get/set_path
These aren't path methods so aren't consistent with the
cogl_object_method naming style we are aiming for.
2010-06-04 14:44:15 +01:00
Robert Bragg
fa22ee0e8d math: Adds an experimental cogl_vector3_* API
This adds a math utility API for handling 3 component, single precision
float vectors with the following; mostly self explanatory functions:

cogl_vector3_init
cogl_vector3_init_zero
cogl_vector3_equal
cogl_vector3_equal_with_epsilon
cogl_vector3_copy
cogl_vector3_free
cogl_vector3_invert
cogl_vector3_add
cogl_vector3_subtract
cogl_vector3_multiply_scalar
cogl_vector3_divide_scalar
cogl_vector3_normalize
cogl_vector3_magnitude
cogl_vector3_cross_product
cogl_vector3_dot_product
cogl_vector3_distance

Since the API is experimental you will need to define
COGL_ENABLE_EXPERIMENTAL_API before including cogl.h if you want to use
the API.
2010-05-20 17:18:24 +01:00
Neil Roberts
17a1595cb0 cogl-path: Document how a shape is filled
This adds some documentation to cogl_path_fill() describing the fill
rule Cogl uses.
2010-04-21 13:20:23 +01:00
Neil Roberts
e007bc5358 cogl-material: Add support for setting the wrap mode for a layer
Previously, Cogl's texture coordinate system was effectively always
GL_REPEAT so that if an application specifies coordinates outside the
range 0→1 it would get repeated copies of the texture. It would
however change the mode to GL_CLAMP_TO_EDGE if all of the coordinates
are in the range 0→1 so that in the common case that the whole texture
is being drawn with linear filtering it will not blend in edge pixels
from the opposite sides.

This patch adds the option for applications to change the wrap mode
per layer. There are now three wrap modes: 'repeat', 'clamp-to-edge'
and 'automatic'. The automatic map mode is the default and it
implements the previous behaviour. The wrap mode can be changed for
the s and t coordinates independently. I've tried to make the
internals support setting the r coordinate but as we don't support 3D
textures yet I haven't exposed any public API for it.

The texture backends still have a set_wrap_mode virtual but this value
is intended to be transitory and it will be changed whenever the
material is flushed (although the backends are expected to cache it so
that it won't use too many GL calls). In my understanding this value
was always meant to be transitory and all primitives were meant to set
the value before drawing. However there were comments suggesting that
this is not the expected behaviour. In particular the vertex buffer
drawing code never set a wrap mode so it would end up with whatever
the texture was previously used for. These issues are now fixed
because the material will always set the wrap modes.

There is code to manually implement clamp-to-edge for textures that
can't be hardware repeated. However this doesn't fully work because it
relies on being able to draw the stretched parts using quads with the
same values for tx1 and tx2. The texture iteration code doesn't
support this so it breaks. This is a separate bug and it isn't
trivially solved.

When flushing a material there are now extra options to set wrap mode
overrides. The overrides are an array of values for each layer that
specifies an override for the s, t or r coordinates. The primitives
use this to implement the automatic wrap mode. cogl_polygon also uses
it to set GL_CLAMP_TO_BORDER mode for its trick to render sliced
textures. Although this code has been added it looks like the sliced
trick has been broken for a while and I haven't attempted to fix it
here.

I've added a constant to represent the maximum number of layers that a
material supports so that I can size the overrides array. I've set it
to 32 because as far as I can tell we have that limit imposed anyway
because the other flush options use a guint32 to store a flag about
each layer. The overrides array ends up adding 32 bytes to each flush
options struct which may be a concern.

http://bugzilla.openedhand.com/show_bug.cgi?id=2063
2010-04-12 15:44:23 +01:00
Neil Roberts
067a520f26 cogl: Support retained paths
This adds three new API calls:

  CoglHandle cogl_path_get()
  void cogl_path_set(CoglHandle path)
  CoglHandle cogl_path_copy(CoglHandle path)

All of the fields relating to the path have been moved from the Cogl
context to a new CoglPath handle type. The cogl context now just
contains a CoglPath handle. All of the existing path commands
manipulate the data in the current path handle. cogl_path_new now just
creates a new path handle and unrefs the old one.

The path handle can be stored for later with cogl_path_get. The path
can then be copied with cogl_path_copy. Internally it implements
copy-on-write semantics with an extra optimisation that it will only
copy the data if the new path is modified, but not if the original
path is modified. It can do this because the only way to modify a path
is by appending to it so the copied path is able to store its own path
length and only render the nodes up to that length. For this to work
the copied path also needs to keep its own copies of the path extents
because the parent path may change these by adding nodes.

The clip stack now uses the cogl_path_copy mechanism to store paths in
the stack instead of directly copying the data. This should save some
memory and processing time.
2010-04-08 19:53:38 +01:00
Robert Bragg
d1353b3c1a cogl: renames cogl_multiply_matrix to cogl_transform
Although cogl_multiply_matrix was consistent with OpenGL, after further
consideration it was agreed that cogl_transform is a better name. Given
that it's in the global cogl_ namespace cogl_transform seems more self
documenting.
2010-04-08 14:37:01 +01:00
Emmanuele Bassi
40155e64d8 docs: Add 1.4 index to the API references
Now that master has branched for the 1.3 development cycle.
2010-03-25 09:45:59 +00:00
Damien Lespiau
9e74b04fbd docs: Add 2010 in COGL's Copyright notice
While at it, fix the usage of <year> in <copyright> to let the
stylesheet do the collation when having several years.
2010-02-12 17:29:51 +00:00
Emmanuele Bassi
395518fb34 docs: Fixes for Cogl 2010-02-12 15:52:07 +00:00
Robert Bragg
0f5f4e8645 cogl: improves header and coding style consistency
We've had complaints that our Cogl code/headers are a bit "special" so
this is a first pass at tidying things up by giving them some
consistency. These changes are all consistent with how new code in Cogl
is being written, but the style isn't consistently applied across all
code yet.

There are two parts to this patch; but since each one required a large
amount of effort to maintain tidy indenting it made sense to combine the
changes to reduce the time spent re indenting the same lines.

The first change is to use a consistent style for declaring function
prototypes in headers. Cogl headers now consistently use this style for
prototypes:

 return_type
 cogl_function_name (CoglType arg0,
                     CoglType arg1);

Not everyone likes this style, but it seems that most of the currently
active Cogl developers agree on it.

The second change is to constrain the use of redundant glib data types
in Cogl. Uses of gint, guint, gfloat, glong, gulong and gchar have all
been replaced with int, unsigned int, float, long, unsigned long and char
respectively. When talking about pixel data; use of guchar has been
replaced with guint8, otherwise unsigned char can be used.

The glib types that we continue to use for portability are gboolean,
gint{8,16,32,64}, guint{8,16,32,64} and gsize.

The general intention is that Cogl should look palatable to the widest
range of C programmers including those outside the Gnome community so
- especially for the public API - we want to minimize the number of
foreign looking typedefs.
2010-02-12 14:05:00 +00:00
Emmanuele Bassi
62fa1f9c28 docs: Clean up the unused symbols for Cogl
Gtk-doc is reporting a lot of false positives in the unused text file,
mostly because of new private files that have been added to Cogl but not
to the gtk-doc ignore list for the Cogl API reference.

Once the false positives have been removed we have a couple of really
missing symbols that should be added to the cogl-sections.txt file.
2010-02-09 15:29:29 +00:00
Emmanuele Bassi
ea0d0f1231 docs: Move some Cogl defines in the private section
The PixelFormat bit and mask #defines should not be used and are there
mostly for convenience, so we can push them to the "private" sub-section
of the API reference.

This pushed Cogl's API reference coverage to 100%.
2010-02-09 14:48:11 +00:00
Emmanuele Bassi
2674a1ead2 docs: Fixes for Cogl API reference
98% symbol docs coverage.
  335 symbols documented.
  0 symbols incomplete.
  8 not documented.

Not bad, if I may say so.
2010-02-09 14:41:37 +00:00
Damien Lespiau
cf960cfb3d cogl-texture: Add a new constructor to turn CoglBuffers into textures
The only goal of using COGL buffers is to use them to create
textures. cogl_texture_new_from_buffer() is the new symbol to create
textures out of buffers.
2010-02-08 17:14:49 +00:00
Damien Lespiau
47cc5a4e43 cogl-pixel-buffer: add a pixel buffer object class
This subclass of CoglBuffer aims at wrapping PBOs or other system
surfaces like DRM buffer objects. Two constructors are available:

cogl_pixel_buffer_new() with a size when you only care about the size of
the buffer (such a buffer can be used to store several texture data such
as the three planes of a I420 frame).

cogl_pixel_buffer_new_full() is more a 1:1 mapping between the data and
an underlying surface, with the possibility of having access to a low
level memory buffer that may have a stride.
2010-02-08 17:14:49 +00:00
Damien Lespiau
40b73a8c0c cogl-buffer: add an abstract class around openGL's buffer objects
Buffer objects are cool! This abstracts the buffer API first introduced
by GL_ARB_vertex_buffer_object and then extended to other objects.

The coglBuffer abstract class is intended to be the base class of all
the buffer objects, letting the user map() buffers. If the underlying
implementation does not support buffer objects (or only support VBO but
not FBO for instance), fallback paths should be provided.
2010-02-08 17:14:49 +00:00
Neil Roberts
b39d1b788a Merge branch 'more-texture-backends'
This adds three new texture backends.

- CoglTexture2D: This is a trimmed down version of CoglTexture2DSliced
  which only supports a single texture and only works with the
  GL_TEXTURE_2D target. The code is a lot simpler so it has a less
  overheads than dealing with slices. Cogl will use this wherever
  possible.

- CoglSubTexture: This is used to get a CoglHandle to represent a
  subregion of another texture. The texture can be used as if it was a
  standalone texture but it does not need to copy the resources.

- CoglAtlasTexture: This collects RGB and RGBA textures into a single
  GL texture with the aim of reducing texture state changes and
  increasing batching. The backend will try to manage the atlas and
  may move the textures around to close gaps in the texture. By
  default all textures will be placed in the atlas.
2010-02-06 00:20:32 +00:00
Damien Lespiau
8ef5e82dfa docs: fix new line in the cogl xml top level document
A comma in the FSF address is wrong. Supreme Offence.
2010-02-04 19:32:14 +00:00
Neil Roberts
efcbd20320 Merge remote branch 'master' into texture-debugging
Conflicts:
	clutter/cogl/cogl/cogl-context.h
2010-02-01 13:37:19 +00:00
Damien Lespiau
84a438be55 cogl: Fix gl equivalent of blend string
An example of what could be the equivalent of
    "RBG = REPLACE(TEXTURE)
     A   = MODULATE(PREVIOUS,TEXTURE)"
using the ARB_texture_env_combine extension was given, but it seems that
a few typo were left:
    * remove a spurius GL_COMBINE_ALPHA
    * use the _ALPHA variant of SRCN and OPERANDN when setting up the
      alpha combiner
2010-01-26 17:25:25 +00:00
Neil Roberts
c9cafc798c cogl: Add a sub texture backend
This adds a new texture backend which represents a sub texture of a
larger texture. The texture is created with a reference to the full
texture and a set of coordinates describing the region. The backend
simply defers to the full texture for all operations and maps the
coordinates to the other range. You can also use coordinates outside
the range [0,1] to create a repeated version of the full texture.

A new public API function called cogl_texture_new_from_sub_texture is
available to create the sub texture.
2009-12-02 22:03:08 +00:00
Robert Bragg
944423a8d9 cogl: deprecate cogl_draw_buffer API and replace with a cogl_framebuffer API
cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now
deprecated and new code should use the new cogl_framebuffer_* API instead.

Code that previously did:
    cogl_push_draw_buffer ();
    cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer);
    /* draw */
    cogl_pop_draw_buffer ();
should now be re-written as:
    cogl_push_framebuffer (buffer);
    /* draw */
    cogl_pop_framebuffer ();

As can be seen from the example above the rename has been used as an
opportunity to remove the redundant target argument from
cogl_set_draw_buffer; it now only takes one call to redirect to an offscreen
buffer, and finally the term framebuffer may be a bit more familiar to
anyone coming from an OpenGL background.
2009-11-26 19:33:14 +00:00
Robert Bragg
d2ce4f7137 docs: Don't document cogl_flush_gl_state as public API
This function was #if 0'd before we released Clutter 1.0 so there's no
implementation of it.  At some point we thought it might assist with
developers breaking out into raw OpenGL.  Breaking out to raw GL is a
difficult problem though so we decided instead we will wait for a specific
use case to arrise before trying to support it.
2009-11-24 17:58:22 +00:00
Emmanuele Bassi
421b85fcd5 docs: Add indices to the Cogl API reference
The Clutter API reference has an index of the symbols for each minor
version, and a list of deprecated symbols. The Cogl API reference
should have the same layout.
2009-11-19 14:30:01 +00:00
Emmanuele Bassi
bae4b213d3 docs: Fix Cogl API reference build
• Ignore all the private header files

• Add all missing/unused symbols

• Remove deprecated symbols from 0.*
2009-11-19 13:56:42 +00:00
Robert Bragg
2e0e441031 [cogl-clip] deprecate parts and cleanup the API
cogl_clip_push() which accepts a rectangle in model space shouldn't have
been defined to take x,y,width,height arguments because this isn't consistant
with other Cogl API dealing with model space rectangles.  If you are using a
coordinate system with the origin at the center and the y+ extending up,
then x,y,width,height isn't as natural as (x0,y0)(x1,y1). This API has
now been replace with cogl_clip_push_rectangle()

(As a general note: the Cogl API should only use the x,y,width,height style
when the appropriate coordinate space is defined by Cogl to have a top left
origin.  E.g.  window coordinates, or potentially texture coordinates)

cogl_clip_push_window_rect() shouldn't have been defined to take float
arguments since we only clip with integral pixel precision. We also
shouldn't have abbreviated "rectangle". This API has been replaced with
cogl_clip_push_window_rectangle()

cogl_clip_ensure() wasn't documented at all in Clutter 1.0 and probably
no one even knew it existed. This API isn't useful, and so it's now
deprecated. If no one complains we may remove the API altogether for
Clutter 1.2.

cogl_clip_stack_save() and cogl_clip_stack_restore() were originally added
to allow us to save/restore the clip when switching to/from offscreen
rendering.  Now that offscreen draw buffers are defined to own their clip
state and the state will be automatically saved and restored this API is now
redundant and so deprecated.
2009-11-05 21:10:17 +00:00
Robert Bragg
eed2479556 [cogl] Removes the cogl-current-matrix abstraction
The indirection through this API isn't necessary since we no longer
arbitrate between the OpenGL matrix API and Cogl's client side API.  Also it
doesn't help to maintain an OpenGL style matrix mode API for internal use
since it's awkward to keep restoring the MODELVIEW mode and easy enough to
directly work with the matrix stacks of interest.

This replaces use of the _cogl_current_matrix API with direct use of the
_cogl_matrix_stack API.  All the unused cogl_current_matrix API is removed
and the matrix utility code left in cogl-current-matrix.c was moved to
cogl.c.
2009-10-20 12:32:50 +01:00
Robert Bragg
0bce7eac53 Intial Re-layout of the Cogl source code and introduction of a Cogl Winsys
As part of an incremental process to have Cogl be a standalone project we
want to re-consider how we organise the Cogl source code.

Currently this is the structure I'm aiming for:
cogl/
    cogl/
	<put common source here>
	winsys/
	   cogl-glx.c
	   cogl-wgl.c
	driver/
	    gl/
	    gles/
	os/ ?
    utils/
	cogl-fixed
	cogl-matrix-stack?
        cogl-journal?
        cogl-primitives?
    pango/

The new winsys component is a starting point for migrating window system
code (i.e.  x11,glx,wgl,osx,egl etc) from Clutter to Cogl.

The utils/ and pango/ directories aren't added by this commit, but they are
noted because I plan to add them soon.

Overview of the planned structure:

* The winsys/ API is the API that binds OpenGL to a specific window system,
  be that X11 or win32 etc.  Example are glx, wgl and egl. Much of the logic
  under clutter/{glx,osx,win32 etc} should migrate here.

* Note there is also the idea of a winsys-base that may represent a window
  system for which there are multiple winsys APIs.  An example of this is
  x11, since glx and egl may both be used with x11.  (currently only Clutter
  has the idea of a winsys-base)

* The driver/ represents a specific varient of OpenGL. Currently we have "gl"
  representing OpenGL 1.4-2.1 (mostly fixed function) and "gles" representing
  GLES 1.1 (fixed funciton) and 2.0 (fully shader based)

* Everything under cogl/ should fundamentally be supporting access to the
  GPU.  Essentially Cogl's most basic requirement is to provide a nice GPU
  Graphics API and drawing a line between this and the utility functionality
  we add to support Clutter should help keep this lean and maintainable.

* Code under utils/ as suggested builds on cogl/ adding more convenient
  APIs or mechanism to optimize special cases. Broadly speaking you can
  compare cogl/ to OpenGL and utils/ to GLU.

* clutter/pango will be moved to clutter/cogl/pango

How some of the internal configure.ac/pkg-config terminology has changed:
backendextra -> CLUTTER_WINSYS_BASE # e.g. "x11"
backendextralib -> CLUTTER_WINSYS_BASE_LIB # e.g. "x11/libclutter-x11.la"
clutterbackend -> {CLUTTER,COGL}_WINSYS # e.g. "glx"
CLUTTER_FLAVOUR -> {CLUTTER,COGL}_WINSYS
clutterbackendlib -> CLUTTER_WINSYS_LIB
CLUTTER_COGL -> COGL_DRIVER # e.g. "gl"

Note: The CLUTTER_FLAVOUR and CLUTTER_COGL defines are kept for apps

As the first thing to take advantage of the new winsys component in Cogl;
cogl_get_proc_address() has been moved from cogl/{gl,gles}/cogl.c into
cogl/common/cogl.c and this common implementation first trys
_cogl_winsys_get_proc_address() but if that fails then it falls back to
gmodule.
2009-10-16 18:58:50 +01:00
Emmanuele Bassi
76480b466f docs: Add the "clipping" section to the COGL API reference
All the clip-related API in COGL is missing from the API reference
because the cogl-clipping section is not included inside the main
index file.
2009-10-07 17:41:54 +01:00
Emmanuele Bassi
7feae67026 [docs] Remove the version number from the title
The version number in the title made sense when we were breaking
API with every minor release. Now that we're API stable we can
drop that and make the output in Devhelp and on the website slightly
more good looking.
2009-08-13 16:15:04 +01:00
Emmanuele Bassi
ff833fa068 [cogl] Expose cogl_is_vertex_buffer()
The function is public and available in the shared object, but
it's not present in the header, so this is not an API/ABI change.
2009-08-04 11:15:05 +01:00
Emmanuele Bassi
ab88c0a888 [build] Use API_VERSION, not MAJORMINOR
The correct macro for Clutter's API version is CLUTTER_API_VERSION,
not CLUTTER_MAJORMINOR anymore.
2009-07-28 11:42:58 +01:00
Emmanuele Bassi
d1b8cab65d [doc] Miscellaneous documentation fixes
Remove private symbols, and add missing public ones.
2009-07-20 12:49:35 +01:00
Robert Bragg
afe10f9897 [doc] Remove references to cogl_vertex_buffer_delete_indices
These referencese were left over from before indices got CoglHandles to
uniquely identify them.  cogl_handle_unref can be used to delete indices
now.
2009-07-19 10:23:00 +01:00
Robert Bragg
b4bc9eb458 [cogl] Improve ability to break out into raw OpenGL via begin/end mechanism
Although we wouldn't recommend developers try and interleve OpenGL drawing
with Cogl drawing - we would prefer patches that improve Cogl to avoid this
if possible - we are providing a simple mechanism that will at least give
developers a fighting chance if they find it necissary.

Note: we aren't helping developers change OpenGL state to modify the
behaviour of Cogl drawing functions - it's unlikley that can ever be
reliably supported - but if they are trying to do something like:

   - setup some OpenGL state.
   - draw using OpenGL (e.g. glDrawArrays() )
   - reset modified OpenGL state.
   - continue using Cogl to draw

They should surround their blocks of raw OpenGL with cogl_begin_gl() and
cogl_end_gl():

   cogl_begin_gl ();
   - setup some OpenGL state.
   - draw using OpenGL (e.g. glDrawArrays() )
   - reset modified OpenGL state.
   cogl_end_gl ();
   - continue using Cogl to draw

Again; we aren't supporting code like this:
   - setup some OpenGL state.
   - use Cogl to draw
   - reset modified OpenGL state.
When the internals of Cogl evolves, this is very liable to break.

cogl_begin_gl() will flush all internally batched Cogl primitives, and emit
all internal Cogl state to OpenGL as if it were going to draw something
itself.

The result is that the OpenGL modelview matrix will be setup; the state
corresponding to the current source material will be setup and other world
state such as backface culling, depth and fogging enabledness will be also
be sent to OpenGL.

Note: no special material state is flushed, so if developers want Cogl to setup
a simplified material state it is the their responsibility to set a simple
source material before calling cogl_begin_gl. E.g. by calling
cogl_set_source_color4ub().

Note: It is the developers responsibility to restore any OpenGL state that they
modify to how it was after calling cogl_begin_gl() if they don't do this then
the result of further Cogl calls is undefined.
2009-06-30 17:13:38 +01:00
Robert Bragg
99f53c3922 Adds a cogl_flush() to give developers breaking into raw GL a fighting chance
This function should only need to be called in exceptional circumstances
since Cogl can normally determine internally when a flush is necessary.

As an optimization Cogl drawing functions may batch up primitives
internally, so if you are trying to use raw GL outside of Cogl you stand a
better chance of being successful if you ask Cogl to flush any batched
geometry before making your state changes.

cogl_flush() ensures that the underlying driver is issued all the commands
necessary to draw the batched primitives.  It provides no guarantees about
when the driver will complete the rendering.

This provides no guarantees about the GL state upon returning and to avoid
confusing Cogl you should aim to restore any changes you make before
resuming use of Cogl.

If you are making state changes with the intention of affecting Cogl drawing
primitives you are 100% on your own since you stand a good chance of
conflicting with Cogl internals.  For example clutter-gst which currently
uses direct GL calls to bind ARBfp programs will very likely break when Cogl
starts to use ARBfb programs internally for the material API, but for now it
can use cogl_flush() to at least ensure that the ARBfp program isn't applied
to additional primitives.

This does not provide a robust generalized solution supporting safe use of
raw GL, its use is very much discouraged.
2009-06-30 17:13:38 +01:00
Robert Bragg
606fb8f56f [cogl] Adds cogl_read_pixels to replace direct use of glReadPixels
To allow for flushing of batched geometry within Cogl we can't support users
directly calling glReadPixels.  glReadPixels is also awkward, not least
because it returns upside down image data.

All the unit tests have been swithed over and clutter_stage_read_pixels now
sits on top of this too.
2009-06-29 23:49:06 +01:00
Emmanuele Bassi
e0adc985ad [docs] Various gtk-doc fixes for COGL
Try to keep the gtk-doc errors down to a minimum.
2009-06-10 12:57:36 +01:00
Neil Roberts
e7e8978029 [cogl] Move the texture filters to be a property of the material layer
The texture filters are now a property of the material layer rather
than the texture object. Whenever a texture is painted with a material
it sets the filters on all of the GL textures in the Cogl texture. The
filter is cached so that it won't be changed unnecessarily.

The automatic mipmap generation has changed so that the mipmaps are
only generated when the texture is painted instead of every time the
data changes. Changing the texture sets a flag to mark that the
mipmaps are dirty. This works better if the FBO extension is available
because we can use glGenerateMipmap. If the extension is not available
it will temporarily enable automatic mipmap generation and reupload
the first pixel of each slice. This requires tracking the data for the
first pixel.

The COGL_TEXTURE_AUTO_MIPMAP flag has been replaced with
COGL_TEXTURE_NO_AUTO_MIPMAP so that it will default to
auto-mipmapping. The mipmap generation is now effectively free if you
are not using a mipmap filter mode so you would only want to disable
it if you had some special reason to generate your own mipmaps.

ClutterTexture no longer has to store its own copy of the filter
mode. Instead it stores it in the material and the property is
directly set and read from that. This fixes problems with the filters
getting out of sync when a cogl handle is set on the texture
directly. It also avoids the mess of having to rerealize the texture
if the filter quality changes to HIGH because Cogl will take of
generating the mipmaps if needed.
2009-06-04 19:03:40 +01:00
Emmanuele Bassi
b900c314b7 [docs] Rework the API reference version generation
Clutter copies the gtk-doc from the usual gtk+ template, and
has a version.xml.in containing only:

  @VERSION@

Without a newline at the end. Unfortunately, it appears that
autoconf has started adding a newline to the generated version.xml
which then is used as the payload for the "version" XML entity.

Instead of using a secondary file we can make configure generate
the whole clutter-docs.xml and cogl-docs.xml files from a template;
this way we also get the ability to substitute more autoconf variables
into the documentation -- if needs be.
2009-06-01 17:40:23 +01:00
Neil Roberts
39cb36ba01 [cogl-vertex-buffer] Add cogl_vertex_buffer_indices_get_for_quads
This function can be used as an efficient way of drawing groups of
quads without using GL_QUADS. It generates a VBO containing the
indices needed to render using pairs of GL_TRIANGLES. The VBO is
globally cached so that it only needs to be uploaded whenever more
indices are requested than ever before.
2009-06-01 14:50:52 +01:00
Emmanuele Bassi
ae9b871b38 [docs] Fixes for the API reference
* Add unused symbols

* Document and sync argument names with their gtk-doc counterpart

* Add missing descriptions
2009-05-28 17:18:13 +01:00
Robert Bragg
2f0bda49fc [cogl] renamed cogl_enable_* to cogl_set_*_enabled + added getters
cogl_enable_depth_test and cogl_enable_backface_culling have been renamed
and now have corresponding getters, the new functions are:
  cogl_set_depth_test_enabled
  cogl_get_depth_test_enabled
  cogl_set_backface_culling_enabled
  cogl_get_backface_culling_enabled
2009-05-28 02:43:36 +01:00
Robert Bragg
18193e5322 [cogl matrix] Support ortho and perspective projections.
This adds cogl_matrix api for multiplying matrices either by a perspective
or ortho projective transform.  The internal matrix stack and current-matrix
APIs also have corresponding support added.

New public API:
cogl_matrix_perspective
cogl_matrix_ortho
cogl_ortho
cogl_set_modelview_matrix
cogl_set_projection_matrix
2009-05-28 02:43:35 +01:00
Robert Bragg
25b3c84a5a [cogl] Remove cogl_{create,destroy}_context from the public API
cogl_create_context is dealt with internally when _cogl_get_default context
is called, and cogl_destroy_context is currently never called.

It might be nicer later to get an object back when creating a context so
Cogl can support multiple contexts, so these functions are being removed
from the API until we get a chance to address context management properly.

For now cogl_destroy_context is still exported as _cogl_destroy_context so
Clutter could at least install a library deinit handler to call it.
2009-05-28 02:43:35 +01:00
Robert Bragg
1669fd7332 [vbo indices] tweak add_indices api to return an id and add delete_indices api
Originally cogl_vertex_buffer_add_indices let the user pass in their own unique
ID for the indices; now the Id is generated internally and returned to the
caller.
2009-05-28 02:43:35 +01:00
Robert Bragg
58b89eabdf [cogl-vertex-buffers] Support putting index arrays into VBOS
It's now possible to add arrays of indices to a Cogl vertex buffer and
they will be put into an OpenGL vertex buffer object. Since it's quite
common for index arrays to be static it saves the OpenGL driver from
having to validate them repeatedly.

This changes the cogl_vertex_buffer_draw_elements API: It's no longer
possible to provide a pointer to an index array at draw time. So
cogl_vertex_buffer_draw_elements now takes an indices identifier that
should correspond to an idendifier returned when calling
cogl_vertex_buffer_add_indices ()
2009-05-28 02:43:34 +01:00
Robert Bragg
492f0e5d14 [material] Reduce the material API in preperation for releasing Clutter 1.0
There were a number of functions intended to support creating of new
primitives using materials, but at this point they aren't used outside of
Cogl so until someone has a usecase and we can get feedback on this
API, it's being removed before we release Clutter 1.0.
2009-05-28 02:43:34 +01:00
Robert Bragg
2dc882f685 [cogl-material] Removes all the API made redundant by the blend strings API
This removes the following API:
  cogl_material_set_blend_factors
  cogl_material_set_layer_combine_function
  cogl_material_set_layer_combine_arg_src
  cogl_material_set_layer_combine_arg_op

These were rather awkward to use, so since it's expected very few people are
using them at this point and it should be straight forward to switch over
to blend strings, the API is being removed before we release Clutter 1.0.
2009-05-28 02:43:34 +01:00
Robert Bragg
bc8a18ebc3 [cogl-material] Support string based blending and layer combine descriptions
Setting up layer combine functions and blend modes is very awkward to do
programatically.  This adds a parser for string based descriptions which are
more consise and readable.

E.g. a material layer combine function could now be given as:
  "RGBA = ADD (TEXTURE[A], PREVIOUS[RGB])"
or
  "RGB = REPLACE (PREVIOUS)"
  "A = MODULATE (PREVIOUS, TEXTURE)"

The simple syntax and grammar are only designed to expose standard fixed
function hardware, more advanced combining must be done with shaders.

This includes standalone documentation of blend strings covering the aspects
that are common to blending and texture combining, and adds documentation
with examples specific to the new cogl_material_set_blend() and
cogl_material_layer_set_combine() functions.

Note: The hope is to remove the now redundant bits of the material API
before 1.0
2009-05-28 02:43:28 +01:00
Robert Bragg
6db0d42193 [cogl] Remove the COGL{enum,int,uint} typedefs
COGLenum, COGLint and COGLuint which were simply typedefs for GL{enum,int,uint}
have been removed from the API and replaced with specialised enum typedefs, int
and unsigned int. These were causing problems for generating bindings and also
considered poor style.

The cogl texture filter defines CGL_NEAREST and CGL_LINEAR etc are now replaced
by a namespaced typedef 'CoglTextureFilter' so they should be replaced with
COGL_TEXTURE_FILTER_NEAREST and COGL_TEXTURE_FILTER_LINEAR etc.

The shader type defines CGL_VERTEX_SHADER and CGL_FRAGMENT_SHADER are handled by
a CoglShaderType typedef and should be replaced with COGL_SHADER_TYPE_VERTEX and
COGL_SHADER_TYPE_FRAGMENT.

cogl_shader_get_parameteriv has been replaced by cogl_shader_get_type and
cogl_shader_is_compiled. More getters can be added later if desired.
2009-05-12 14:53:44 +01:00
Robert Bragg
869a2b4167 [cogl-offscreen] Cleans up the cogl offscreen API and adds documentation
There were several functions I believe no one is currently using that were
only implemented in the GL backend (cogl_offscreen_blit_region and
cogl_offscreen_blit) that have simply been removed so we have a chance to
think about design later with a real use case.

There was one nonsense function (cogl_offscreen_new_multisample) that
sounded exciting but in all cases it just returned COGL_INVALID_HANDLE
(though at least for GL it checked for multisampling support first!?)
it has also been removed.

The MASK draw buffer type has been removed. If we want to expose color
masking later then I think it at least would be nicer to have the mask be a
property that can be set on any draw buffer.

The cogl_draw_buffer and cogl_{push,pop}_draw_buffer function prototypes
have been moved up into cogl.h since they are for managing global Cogl state
and not for modifying or creating the actual offscreen buffers.

This also documents the API so for example desiphering the semantics of
cogl_offscreen_new_to_texture() should be a bit easier now.
2009-05-02 04:12:26 +01:00
Robert Bragg
c8862e35cc [cogl] Only expose CoglBitmap as a CoglHandle
It was inconsistent that we exposed the CoglBitmap struct instead of an
opaque CoglHandle.
2009-05-02 04:12:26 +01:00
Robert Bragg
2866b0e33b [cogl-vertex-buffer] fix cogl_vertex_buffer_draw_elements prototype
This function was renamed a while ago in the .c file from
cogl_vertex_buffer_draw_range_elements  but the corresponding .h and
doc/reference/cogl changes weren't made.
2009-03-16 16:19:39 +00:00
Robert Bragg
a76e333f50 [cogl-vertex-buffer] Allow querying back the number of vertices a buffer represents
This may be convenient e.g. at draw time if you are simply drawing all vertices
2009-03-16 16:17:02 +00:00
Robert Bragg
f816644022 [cogl-matrix] Documents that CoglMatrix members should be considered read only
In the future if we want to annotate matrices with internal flags, and add
caching of the inverse matrix then we need to ensure that all matrix
modifications are done by cogl_matrix API so we'd know when to dirty the
cache or update the flags.

This just adds documentation to that effect, and assuming the most likley
case where someone would try and directly write to matrix members would
probably be to load a constant matrix other than the identity matrix; I
renamed cogl_matrix_init_from_gl_matrix to cogl_matrix_init_from_array to
make it seem more general purpose.
2009-02-26 16:42:32 +00:00
Emmanuele Bassi
e226ffa364 [docs] Rename cogl-docs from sgml to xml
The cogl-docs.sgml file has always been XML, so it's only fitting that
we actually call it cogl-docs.xml.
2009-02-20 12:02:31 +00:00
Emmanuele Bassi
82d093bbb7 [docs] Use the --name-space option
Now that we depend on gtk-doc 1.11 we can use the --name-space
command line option for the mkdb utility.
2009-02-20 11:58:04 +00:00
Emmanuele Bassi
19634b4b0a [docs] Update build for COGL API reference
We need to initialize the type system for gtk-doc-scan, now that
COGL exposes GTypes.
2009-02-19 17:22:21 +00:00
Emmanuele Bassi
5abb11ba6b [cogl] Add cogl_is_material to cogl-material.h
The COGL_DEFINE_HANDLE macro generates a cogl_is_<type> function
as well, to check whether a CoglHandle opaque pointer is of type
<type>.

The handle for CoglMaterial does not export cogl_is_material() in
its installed header.
2009-02-19 11:55:54 +00:00
Robert Bragg
89d8ebcbb0 [Cogl] Renames cogl_paint_init to cogl_clear and adds a cogl_disable_fog function
cogl_paint_init was a bit too miscellaneous; it mainly cleared the color, depth
and stencil buffers but arbitrarily it also disabled fogging and lighting.

It no longer disables lighting, since we know Cogl never enables lighting and
disabling of fog is now handled with a seperate function.

Since I noticed cogl_set_fog was taking a density argument documented as
"Ignored" I've also added a mode argument to cogl_set_fog which exposes the
exponential fog modes which can make use of the density.
2009-02-18 16:00:52 +00:00
Robert Bragg
145c2eb5f9 [Cogl] cogl_clip_{set*,unset} renamed to cogl_clip_{push*,pop}
This is so they self document the stacking semantics of the cogl clip API
2009-02-18 16:00:51 +00:00
Robert Bragg
5901b4d045 [docs] Various gtk-doc updates for Cogl
This hides a number of internal structs and enums from the docs, and moves
some functions to more appropriate sections as well as misc description
updates (mostly for the vertex buffer api)
2009-02-09 14:33:14 +00:00
Emmanuele Bassi
1f473c02e0 [cogl-docs] Add the Materials section
The COGL Materials API was not linked from the COGL reference
index.
2009-01-28 16:47:29 +00:00
Emmanuele Bassi
d6f6c06af5 [docs] Documentation fixes
Update the COGL API reference to avoid a lot of warnings coming
from gtk-doc.
2009-01-27 16:53:01 +00:00
Robert Bragg
0c8c273980 Merge commit 'origin/master' into cogl-material
Conflicts:

	clutter/clutter-texture.c
	clutter/cogl/cogl-texture.h
	clutter/cogl/cogl.h.in
	clutter/cogl/common/Makefile.am
	clutter/cogl/gl/Makefile.am
	clutter/cogl/gles/Makefile.am
	clutter/cogl/gles/cogl-gles2-wrapper.c
	clutter/cogl/gles/cogl-gles2-wrapper.h
2009-01-23 15:23:49 +00:00
Emmanuele Bassi
dcbb0833c1 [docs] Remove sources of warnings in API references 2009-01-21 16:41:18 +00:00
Emmanuele Bassi
16ad994dfa [docs] Add CoglTextureFlags to the API reference 2009-01-21 10:59:19 +00:00
Robert Bragg
de41fdd9d1 Renames the mesh api to the "vertex buffer api".
This better reflects the fact that the api manages sets of vertex attributes,
and the attributes really have no implied form. It is only when you use the
attributes to draw that they become mesh like; when you specify how they should
be interpreted, e.g. as triangle lists or fans etc. This rename frees up the
term "mesh", which can later be applied to a concept slightly more fitting.
E.g. at some point it would be nice to have a higher level abstraction that
sits on top of cogl vertex buffers that adds the concept of faces. (Somthing
like Blender's mesh objects.) There have also been some discussions over
particle engines, and these can be defined in terms of emitter faces; so some
other kind of mesh abstraction might be usefull here.
2009-01-20 22:29:35 +00:00
Robert Bragg
4e60f2f5b0 [Automatic fixed-to-float.sh change] Applies a number fixed to float patches
To deal with all the corner cases that couldn't be scripted a number of patches
were written for the remaining 10% of the effort.

Note: again no API changes were made in Clutter, only in Cogl.
2009-01-20 16:20:54 +00:00
Robert Bragg
a0c5690d55 Merge commit 'origin/master' into cogl-material
Conflicts:

	clutter/clutter-texture.c
	clutter/cogl/cogl-texture.h
	clutter/cogl/gles/cogl-context.c
	clutter/cogl/gles/cogl-context.h
2009-01-13 13:37:38 +00:00
Robert Bragg
5b61106684 [doc] Hooks up cogl-material reference documentation
Adds some more gtk-doc comments to cogl-material.h, and adds a new section to
cogl-sections.txt
2008-12-22 16:35:52 +00:00