README.md
1# Graphene
2### A thin layer of types for graphic libraries
3
4
5
6
7[](https://coveralls.io/github/ebassi/graphene?branch=master)
8[](https://opensource.org/licenses/MIT)
9
10When creating graphic libraries you most likely end up dealing with points
11and rectangles. If you're particularly unlucky, you may end up dealing
12with affine matrices and 2D transformations. If you're writing a graphic
13library with 3D transformations, though, you are going to hit the jackpot:
144x4 matrices, projections, transformations, vectors, and quaternions.
15
16Most of this stuff exists, in various forms, in other libraries, but it
17has the major drawback of coming along with the rest of those libraries,
18which may or may not be what you want. Those libraries are also available
19in various languages, as long as those languages are C++; again, it may or
20may not be something you want.
21
22For this reason, I decided to write the thinnest, smallest possible layer
23needed to write a canvas library; given its relative size, and the
24propensity for graphics libraries to have a pun in their name, I decided
25to call it Graphene.
26
27This library provides types and their relative API; it does not deal with
28windowing system surfaces, drawing, scene graphs, or input. You're
29supposed to do that yourself, in your own canvas implementation, which is
30the whole point of writing the library in the first place.
31
32### Dependencies
33
34Graphene has minimal dependencies.
35
36Graphene contains optimizations for speeding up vector operations; those
37optimizations are optional, and used only if both Graphene was compiled
38with support for them *and* if the system you're running on has them.
39Currently, Graphene supports the following platform-specific fast paths:
40
41 * Streaming SIMD Extensions (SSE) 2
42 * Optionally using SSE 4.1
43 * ARM NEON
44 * GCC vector extensions
45
46In the remote case in which none of these optimizations are available,
47Graphene will fall back to a naive scalar implementation.
48
49Graphene can, optionally, provide types for integrating with
50[GObject][gobject-api] properties and signals, as well as introspection
51information for its use with other languages through introspection-based
52bindings.
53
54### Installation
55
56In order to build and install Graphene you will need development tools and
57the headers of the dependencies. You will also need:
58
59 * [python3](https://www.python.org)
60 * [meson](http://mesonbuild.com)
61 * [ninja](https://ninja-build.org/)
62
63First of all, clone the Git repository:
64
65 $ git clone https://github.com/ebassi/graphene
66 $ cd graphene
67
68Then run:
69
70 $ meson _build # on Windows, it may be "meson.py"
71 $ cd _build
72 $ ninja test
73 # ninja install
74
75It is possible, when building Graphene, to disable specific optimizations by
76using configuration options:
77
78 * `-Dsse2=false` - will disable the SSE2 fast paths
79 * `-Darm_neon=false` - will disable the ARM NEON fast paths
80 * `-Dgcc_vector=false` - will disable the GCC vector intrinsics
81
82If you don't plan on generating introspection data, use `-Dintrospection=disabled`
83when configuring Graphene; similarly, if you don't plan on using GObject with
84Graphene, use `-Dgobject_types=false`. Disabling GObject types will also
85automatically disable generating introspection data.
86
87You can explicitly disable building the test suite and the benchmark suite,
88using the `-Dtests=false` and `-Dbenchmarks=false` configuration switches
89respectively. The tests suite depends on [µTest][mutest]; if it is not available
90at configuration time, tests will be disabled automatically.
91
92#### Building on Windows
93
94Graphene supports the Microsoft Visual C compiler 2017 and later versions.
95
96Graphene also supports the [MSYS2 toolchain](http://sourceforge.net/projects/msys2/).
97
98When using MSYS2, it's recommended to have an up to date installation;
99in order to build Graphene you will need to use the `pacman` command
100to install the necessary build dependencies first:
101
102 $ pacman -S base-devel
103 $ pacman -S python3
104 $ pacman -S mingw-w64-x86_64-meson # only MINGW64 target
105 $ pacman -S mingw-w64-i686-meson # only MINGW32 target
106
107For the optional support for GObject types, introspection, and
108documentation, you will need to install additional dependencies:
109
110 $ pacman -S gtk-doc # optional
111 $ pacman -S mingw-w64-x86_64-glib2 # optional, MINGW64 target only
112 $ pacman -S mingw-w64-i686-glib2 # optional, MINGW32 target only
113 $ pacman -S glib2 glib2-devel # optional, MSYS target only
114
115After installing all dependencies, you can now clone the Graphene
116repository locally, and follow the build instructions above.
117
118Please note that on some MSYS2 installations the Meson binary may be called
119`meson.py`.
120
121## Documentation
122
123### Release notes
124
125The release notes are available on the Graphene
126[wiki](https://github.com/ebassi/graphene/wiki/Release-Notes).
127
128### Available types
129
130Graphene provides common types needed to handle 3D transformations:
131
132 * [2D points](http://ebassi.github.io/graphene/docs/graphene-Point.html)
133 * [3D points](http://ebassi.github.io/graphene/docs/graphene-Point3D.html)
134 * [triangles](http://ebassi.github.io/graphene/docs/graphene-Triangle.html)
135 * [rectangles](http://ebassi.github.io/graphene/docs/graphene-Rectangle.html)
136 * [quads](http://ebassi.github.io/graphene/docs/graphene-Quad.html)
137 * [quaternions](http://ebassi.github.io/graphene/docs/graphene-Quaternion.html)
138 * [euler angles](http://ebassi.github.io/graphene/docs/graphene-Euler.html)
139 * [vectors](http://ebassi.github.io/graphene/docs/graphene-Vectors.html) (2, 3, or 4-sized)
140 * [matrices](http://ebassi.github.io/graphene/docs/graphene-Matrix.html)
141 * [planes](http://ebassi.github.io/graphene/docs/graphene-Plane.html)
142 * [axis aligned bounding boxes](http://ebassi.github.io/graphene/docs/graphene-Box.html)
143 * [spheres](http://ebassi.github.io/graphene/docs/graphene-Sphere.html)
144 * [frustums](http://ebassi.github.io/graphene/docs/graphene-Frustum.html)
145
146Graphene also provides its low-level SIMD [vector](http://ebassi.github.io/graphene/docs/graphene-SIMD-vector.html)
147and [matrix](http://ebassi.github.io/graphene/docs/graphene-SIMD-matrix.html)
148types, which are used to implement the API above.
149
150All types can be placed on the stack, but provide allocation/free functions
151for working on the heap as well. The contents of all structure types, unless
152noted otherwise, should be considered private, and should never be accessed
153directly.
154
155The full API reference for Graphene is [available online](http://ebassi.github.io/graphene/docs/).
156
157### License
158
159Graphene is released under the terms of the MIT/X11 license.
160
161See the [license file](./LICENSE.txt) for more details.
162
163[mutest]: https://github.com/ebassi/mutest
164[gobject-api]: https://developer.gnome.org/gobject/stable/
165
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}