Commit Graph

42 Commits

Author SHA1 Message Date
Lionel Landwerlin
28e37775c0 matrix: add missing transfer annotation
Reviewed-by: Robert Bragg <robert@linux.intel.com>
2013-09-23 15:02:31 +01:00
Chun-wei Fan
aa878ddca6 Fix the placement of deprecation macros
The deprecation macros, which expand to __declspec (deprecated) on Visual
Studio, is expected to be before the return type of the function which
is annotated by them, and having the deprecation macros there is also
accepted by GCC as well.

This will fix the builds of all applications/libraries using Cogl under
Visual Studio,

Reviewed-by: Robert Bragg <robert@linux.intel.com>
2013-08-19 22:44:45 +01:00
Robert Bragg
74b8cc3acb Include cogl-defines.h before checking COGL_HAS_ define
This makes sure we include cogl-defines.h in cogl-matrix.h before
checking if COGL_HAS_GYPE_SUPPORT is defined

Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit aa5ba324bb3b2ce77be29942f8716d61919cefeb)
2013-05-16 15:28:00 +01:00
Robert Bragg
afbb13e1a4 Add compiler deprecation warnings
This adds compiler symbol deprecation declarations for old Cogl APIs so
that users can easily see via compiler warning when they are using these
symbols, and also see a hint for what the apis should be replaced with.

So that users of Cogl can manage when to show these warnings this
introduces a scheme borrowed from glib whereby you can declare what
version of the Cogl api you are using:

COGL_VERSION_MIN_REQUIRED can be defined to indicate the oldest Cogl api
that the application wants to use. Cogl will only warn about
deprecations for symbols that were deprecated earlier than this required
version. If this is left undefined then by default Cogl will warn about
all deprecations.

COGL_VERSION_MAX_ALLOWED can be defined to indicate the newest api
that the application uses. If the application uses symbols newer than
this then Cogl will give a warning about that.

This patch removes the need to maintain the COGL_DISABLE_DEPRECATED
guards around deprecated symbols.

This patch fixes a few uses of deprecated symbols in the examples/

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2013-04-24 22:23:50 +01:00
Damien Lespiau
8c1708ec93 doc: Fix argument syntax of existing commment blocks
Fixes:
  Parsing comment block file : parameter expecter

by correctly declaring parameters.

(cherry picked from commit 2fe9bc2017fa966ab445674a530aac0c17204040)
2013-01-22 17:48:12 +00:00
Damien Lespiau
7b43289ec9 doc: Use Returns: to annotate return values
gtk-doc complains that having a sentence starting by Return is a bit
ambiguous and it'd rather see 'Returns:' spelled out.

Fixes 2 warnings:

 warning: Free-form return value description in $symbol. Use `Returns:'
 to avoid ambiguities

(cherry picked from commit 9718f31717b3a0e01b7c4c69cea138f39d23c0e0)
2013-01-22 17:48:11 +00:00
Robert Bragg
cab4622eb3 matrix-stack: make CoglMatrixStack public
We have found several times now when writing code using Cogl that it
would really help if Cogl's matrix stack api was public as a utility
api. In Rig for example we want to avoid redundant arithmetic when
deriving the matrices of entities used to render and we aren't able
to simply use the framebuffer's matrix stack to achieve this. Also when
implementing cairo-cogl we found that it would be really useful if we
could have a matrix stack utility api.

(cherry picked from commit d17a01fd935d88fab96fe6cc0b906c84026c0067)
2013-01-22 17:48:11 +00:00
Neil Roberts
4f6fe6f0e2 Fixes for --disable-glib
This fixes some problems which were stopping --disable-glib from
working properly:

• A lot of the public headers were including glib.h. This shouldn't be
  necessary because the API doesn't expose any glib types. Otherwise
  any apps would require glib in order to get the header.

• The public headers were using G_BEGIN_DECLS. There is now a
  replacement macro called COGL_BEGIN_DECLS which is defined in
  cogl-types.h.

• A similar fix has been done for G_GNUC_NULL_TERMINATED and
  G_GNUC_DEPRECATED.

• The CFLAGS were not including $(builddir)/deps/glib which was
  preventing it finding the generated glibconfig.h when building out
  of tree.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

(cherry picked from commit 4138b3141c2f39cddaea3d72bfc04342ed5092d0)
2013-01-22 17:48:05 +00:00
Robert Bragg
1161870670 matrix: Add cogl_debug_matrix_print api
As a convenience for debugging this adds a cogl_debug_matrix_print
function that prints out the components of a matrix and any internal
flags associated with the given matrix.

(cherry picked from commit 3b33889ff1204f19347a9548320ba95baa54c18c)
2013-01-18 17:28:25 +00:00
Neil Roberts
5e8ff248d2 Add functions to directly transform from a euler or a quaternion
This adds the following new functions to apply a rotation described by
a euler or a quaternion to either a CoglMatrix or directly to the
modelview stack of a framebuffer:

cogl_matrix_rotate_quaternion
cogl_matrix_rotate_euler
cogl_framebuffer_rotate_quaternion
cogl_framebuffer_rotate_euler

The direct framebuffer functions have corresponding functions in the
CoglMatrixStack to store an entry describing the rotation.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

(cherry picked from commit 5064315678b496395e1d01f266f322d73e55e324)
2012-08-06 14:27:43 +01:00
Neil Roberts
6eb8864866 Add a cogl_matrix_init_from_euler function
This creates a matrix to represent the given euler rotation. This
should be more efficient than creating the matrix by doing three
separate rotations because no separate intermediate matrices are
created and no matrix multiplication is needed.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

(cherry picked from commit e66d9965897999a4889063f6df9a20ea6abf97fe)
2012-08-06 14:27:43 +01:00
Neil Roberts
0210cc40f9 Make cogl_matrix_init_from_quaternion take a const quaternion
The quaternion is not modified so for consistency with the rest of the
API it should probably be const.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

(cherry picked from commit 7fa8c05c2ffb90cba03289a04e37866efc0890a5)
2012-08-06 14:27:43 +01:00
Damien Lespiau
7ff0b52d78 matrix: Add a init_translation() constructor
This allows people to initialize a matrix with a translation
transformation. The options to do it at the moment were:

* init_from_array() but it give cogl no information about the type of
  matrix.
* init_indentity() and then translate() but it means doing a lot of
  computations for no reason.

Reviewed-by: Robert Bragg <robert@linux.intel.com>

(cherry picked from commit 068b3b59221e405dc288d434b0008464684a7c12)
2012-08-06 14:27:41 +01:00
Robert Bragg
54735dec84 Switch use of primitive glib types to c99 equivalents
The coding style has for a long time said to avoid using redundant glib
data types such as gint or gchar etc because we feel that they make the
code look unnecessarily foreign to developers coming from outside of the
Gnome developer community.

Note: When we tried to find the historical rationale for the types we
just found that they were apparently only added for consistent syntax
highlighting which didn't seem that compelling.

Up until now we have been continuing to use some of the platform
specific type such as gint{8,16,32,64} and gsize but this patch switches
us over to using the standard c99 equivalents instead so we can further
ensure that our code looks familiar to the widest range of C developers
who might potentially contribute to Cogl.

So instead of using the gint{8,16,32,64} and guint{8,16,32,64} types this
switches all Cogl code to instead use the int{8,16,32,64}_t and
uint{8,16,32,64}_t c99 types instead.

Instead of gsize we now use size_t

For now we are not going to use the c99 _Bool type and instead we have
introduced a new CoglBool type to use instead of gboolean.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit 5967dad2400d32ca6319cef6cb572e81bf2c15f0)
2012-08-06 14:27:39 +01:00
Jasper St. Pierre
e98f279712 Fix some doc issues
Reviewed-by: Neil Roberts <neil@linux.intel.com>
2012-02-14 20:42:10 +00:00
Robert Bragg
1e03780510 matrix: Remove _EXP symbol mangling and add gtk-doc
We are in the process of removing all _EXP suffix mangling for
experimental APIs (Ref: c6528c4b6c) and adding missing gtk-doc
comments so that we can instead rely on the "Stability: unstable"
markers in the gtk-doc comments. This patch tackles the matrix api
symbols.
2012-01-16 18:27:20 +00:00
Robert Bragg
ff4921cef9 docs: updates cogl-matrix.h docs to be consistent
This update some of the cogl-matrix.h documentation to be consistent
with the corresponding documentation for framebuffer matrix-stack
methods in cogl-framebuffer.h

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-06 18:51:57 +00:00
Robert Bragg
a4f3d0d18b matrix: Add cogl_matrix_orthographic
This adds an experimental cogl_matrix_orthographic() function that is
more consistent with other Cogl api by taking x_1, y_1, x_2, y_2
arguments to define the top-left and bottom-right coordinates of the
orthographic coordinates instead of OpenGL style left, right, bottom and
top values.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-12-06 18:51:56 +00:00
Neil Roberts
d2fd168351 cogl-matrix: Add a public cogl_matrix_transpose()
This function takes a single matrix argument and replaces the matrix
with its transpose.

Reviewed-by: Robert Bragg <robert@linux.intel.com>
2011-11-16 16:32:11 +00:00
Robert Bragg
f37d9bbb4d matrix: Add cogl_matrix_look_at
Similar to the widely used gluLookAt API, this adds a CoglMatrix utility
for setting up a view transform in terms of positioning a camera/eye
position that points to a given object position aligned to a given
world-up vector.

Reviewed-by: Neil Roberts <neil@linux.intel.com>
2011-08-12 15:28:44 +01:00
Robert Bragg
d74cf9de81 matrix: Adds cogl_matrix_is_identity API
This adds a function called cogl_matrix_is_identity that can determine
if a given matrix is an identity matrix or not.

Signed-off-by: Neil Roberts <neil@linux.intel.com>
2011-07-04 15:31:50 +01:00
Emmanuele Bassi
552761f3a8 Remove G_CONST_RETURN
It is going to be deprecated by GLib, see bug:

  https://bugzilla.gnome.org/show_bug.cgi?id=644611
2011-06-09 16:21:15 +01:00
Robert Bragg
2da24ab863 Add compile time checks for size of public structs
To help catch accidental changes to the size of public structs that can
be allocated on the stack this patch adds compile time checks that our
struct sizes haven't changed.
2011-05-16 14:12:49 +01:00
Robert Bragg
d1434d1c33 math: Adds an experimental quaternion API
This adds an experimental quaternion utility API. It's not yet fully
documented but it's complete enough that people can start to experiment
with using it. It adds the following functions:

    cogl_quaternion_init_identity
    cogl_quaternion_init
    cogl_quaternion_init_from_angle_vector
    cogl_quaternion_init_from_array
    cogl_quaternion_init_from_x_rotation
    cogl_quaternion_init_from_y_rotation
    cogl_quaternion_init_from_z_rotation
    cogl_quaternion_equal
    cogl_quaternion_copy
    cogl_quaternion_free
    cogl_quaternion_get_rotation_angle
    cogl_quaternion_get_rotation_axis
    cogl_quaternion_normalize
    cogl_quaternion_dot_product
    cogl_quaternion_invert
    cogl_quaternion_multiply
    cogl_quaternion_pow
    cogl_quaternion_slerp
    cogl_quaternion_nlerp
    cogl_quaternion_squad
    cogl_get_static_identity_quaternion
    cogl_get_static_zero_quaternion

Since it's experimental API you'll need to define
COGL_ENABLE_EXPERIMENTAL_API before including cogl.h.
2011-05-16 14:11:47 +01:00
Robert Bragg
d4a5d70ee0 util: optimize _clutter_util_fully_transform_vertices
Instead of unconditionally combining the modelview and projection
matrices and then iterating each of the vertices to call
cogl_matrix_transform_point for each one in turn we now only combine the
matrices if there are more than 4 vertices (with less than 4 vertices
its less work to transform them separately) and we use the new
cogl_vertex_{transform,project}_points APIs which can hopefully
vectorize the transformations.

Finally the perspective divide and viewport scale is done in a separate
loop at the end and we don't do the spurious perspective divide and
viewport scale for the z component.
2011-03-07 13:26:20 +00:00
Robert Bragg
962b84ed56 matrix: adds 2d view transform conveniences
This adds two new experimental functions to cogl-matrix.c:
cogl_matrix_view_2d_in_perspective and cogl_matrix_view_2d_in_frustum
which can be used to setup a view transform that maps a 2D coordinate
system (0,0) top left and (width,height) bottom right to the current
viewport.

Toolkits such as Clutter that want to mix 2D and 3D drawing can use
these APIs to position a 2D coordinate system at an arbitrary depth
inside a 3D perspective projected viewing frustum.
2011-03-07 13:26:19 +00:00
Robert Bragg
b351aa4af4 matrix: note that _matrix_multiply can multiply in-place
This adds a note to clarify that cogl_matrix_multiply allows you to
multiply the @a matrix in-place, so @a can equal @result but @b can't
equal @result.
2011-02-09 17:21:48 +00:00
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
3ac023163f matrix: Adds matrix_copy and _free functions
As a pre-requisite for being able to register a boxed GType for
CoglMatrix (enabling us to define gobject properties that accept a
CoglMatrix) this adds cogl_matrix_copy and _free 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
Emmanuele Bassi
b12f688415 docs: Fixes for gtk-doc 2010-09-03 16:12:24 +01:00
Robert Bragg
1047c1c082 matrix: add cogl_matrix_equal API
This adds a way to compare two CoglMatrix structures to see if they
represent the same transformations. memcmp can't be used because a
CoglMatrix contains private flags and padding.
2010-06-09 15:19:31 +01:00
Neil Roberts
908be0480c cogl: Make private members really hard to accidentally use
CoglColor and CoglMatrix have public declarations with private members
so that we are free to change the implementation but the structures
could still be allocated on the stack in applications. However it's
quite easy not to realise the members are private and then access them
directly. This patch wraps the members in a macro which redefines the
symbol name when including the header outside of the clutter source.

http://bugzilla.openedhand.com/show_bug.cgi?id=2065
2010-04-12 15:38:58 +01:00
Neil Roberts
dedb753d30 CoglMatrix: Don't make the matrix fields private
The xx, yx, zx etc fields are meant to be read-only but they were
marked as private with the gtk-doc annotation. This patch moves the
private marker so that the 16 float member fields are public but the
type, inverted matrix, flags and padding are not.
2010-04-12 15:38:58 +01:00
Neil Roberts
232c960b67 Fix indentation in CoglMatrix
The members of CoglMatrix were indented by 4 characters instead of 2.
2010-04-12 15:38:58 +01:00
Emmanuele Bassi
72f4ddf532 Remove mentions of the FSF address
Since using addresses that might change is something that finally
the FSF acknowledge as a plausible scenario (after changing address
twice), the license blurb in the source files should use the URI
for getting the license in case the library did not come with it.

Not that URIs cannot possibly change, but at least it's easier to
set up a redirection at the same place.

As a side note: this commit closes the oldes bug in Clutter's bug
report tool.

http://bugzilla.openedhand.com/show_bug.cgi?id=521
2010-03-01 12:56:10 +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
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
Emmanuele Bassi
fab83d14f4 docs: Documentation fixes for CoglMatrix
Clean up the references, the docbook tags, and the style to fit in
with the rest of the API references for Cogl and Clutter.
2009-11-19 13:56:47 +00:00
Robert Bragg
28c7e940bf [matrix] Adds cogl_matrix_get_inverse API
This new API takes advantage of the recently imported Mesa code to support
inverse matrix calculation.  The matrix code keeps track (via internal
flags) of the transformations a matrix represents so that it can select an
optimized inversion function.

Note: although other aspects of the Cogl matrix API have followed a similar
style to Cairo's matrix API we haven't added a cogl_matrix_invert API
because the inverse of a CoglMatrix is actually cached as part of the
CoglMatrix structure meaning a destructive API like cogl_matrix_invert
doesn't let users take advantage of this caching design.
2009-11-04 03:34:05 +00:00
Robert Bragg
0a1db7c4d8 [cogl-matrix] Import Mesa's matrix manipulation code
This pulls in code from Mesa to improve our matrix manipulation support. It
includes support for calculating the inverse of matrices based on top of a
matrix categorizing system that allows optimizing certain matrix types.
(the main thing we were after) but also adds some optimisations for
rotations.

Changes compared to the original code from Mesa:

- Coding style is consistent with the rest of Cogl
- Instead of allocating matrix->m and matrix->inv using malloc, our public
  CoglMatrix typedef is large enough to directly contain the matrix, its
  inverse, a type and a set of flags.
- Instead of having a _math_matrix_analyse which updates the type, flags and
  inverse, we have _math_matrix_update_inverse which essentially does the
  same thing (internally making use of _math_matrix_update_type_and_flags())
  but with additional guards in place to bail out when the inverse matrix is
  still valid.
- When initializing a matrix with the identity matrix we don't immediately
  initialize the inverse matrix; rather we just set the dirty flag for the
  inverse (since it's likely the user won't request the inverse of the
  identity matrix)
2009-11-04 03:34:04 +00: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