Repository files navigation

When creating graphic libraries you most likely end up dealing with pointsand rectangles. If you're particularly unlucky, you may end up dealingwith affine matrices and 2D transformations. If you're writing a graphiclibrary with 3D transformations, though, you are going to hit the jackpot:4x4 matrices, projections, transformations, vectors, and quaternions.

Most of this stuff exists, in various forms, in other libraries, but ithas the major drawback of coming along with the rest of those libraries,which may or may not be what you want. Those libraries are also availablein various languages, as long as those languages are C++; again, it may ormay not be something you want.

For this reason, I decided to write the thinnest, smallest possible layerneeded to write a canvas library; given its relative size, and thepropensity for graphics libraries to have a pun in their name, I decidedto call it Graphene.

This library provides types and their relative API; it does not deal withwindowing system surfaces, drawing, scene graphs, or input. You'resupposed to do that yourself, in your own canvas implementation, which isthe whole point of writing the library in the first place.

Graphene has minimal dependencies.

Graphene contains optimizations for speeding up vector operations; thoseoptimizations are optional, and used only if both Graphene was compiledwith support for themand if the system you're running on has them.Currently, Graphene supports the following platform-specific fast paths:

• Streaming SIMD Extensions (SSE) 2
• Optionally using SSE 4.1
• ARM NEON
• GCC vector extensions

In the remote case in which none of these optimizations are available,Graphene will fall back to a naive scalar implementation.

Graphene can, optionally, provide types for integrating withGObject properties and signals, as well as introspectioninformation for its use with other languages through introspection-basedbindings.

In order to build and install Graphene you will need development tools andthe headers of the dependencies. You will also need:

• python3
• meson
• ninja

First of all, clone the Git repository:

$ git clone https://github.com/ebassi/graphene$ cd graphene

Then run:

$ meson setup _build$ meson compile -C _build$ meson test -C _build$ meson install -C _build

It is possible, when building Graphene, to disable specific optimizations byusing configuration options:

• -Dsse2=false - will disable the SSE2 fast paths
• -Darm_neon=false - will disable the ARM NEON fast paths
• -Dgcc_vector=false - will disable the GCC vector intrinsics

If you don't plan on generating introspection data, use-Dintrospection=disabledwhen configuring Graphene; similarly, if you don't plan on using GObject withGraphene, use-Dgobject_types=false. Disabling GObject types will alsoautomatically disable generating introspection data.

You can explicitly disable building the test suite and the benchmark suite,using the-Dtests=false and-Dbenchmarks=false configuration switchesrespectively. The tests suite depends onµTest; if it is not availableat configuration time, tests will be disabled automatically.

Graphene supports the Microsoft Visual C compiler 2017 and later versions.

Graphene also supports theMSYS2 toolchain.

When using MSYS2, it's recommended to have an up to date installation;in order to build Graphene you will need to use thepacman commandto install the necessary build dependencies first:

$ pacman -S base-devel$ pacman -S python3$ pacman -S mingw-w64-x86_64-meson# only MINGW64 target$ pacman -S mingw-w64-i686-meson# only MINGW32 target

For the optional support for GObject types, introspection, anddocumentation, you will need to install additional dependencies:

$ pacman -S gtk-doc                 # optional$ pacman -S mingw-w64-x86_64-glib2  # optional, MINGW64 target only$ pacman -S mingw-w64-i686-glib2    # optional, MINGW32 target only$ pacman -S glib2 glib2-devel       # optional, MSYS target only

After installing all dependencies, you can now clone the Graphenerepository locally, and follow the build instructions above.

Please note that on some MSYS2 installations the Meson binary may be calledmeson.py.

You can follow thecontribution guide if you want toparticipate in this project. Graphene also has acode ofconduct, so make sure to follow it when interactingon the project's issue tracker.

The release notes are available on the Graphenewiki.

Graphene provides common types needed to handle 3D transformations:

• 2D points
• 3D points
• triangles
• rectangles
• quads
• quaternions
• euler angles
• vectors (2, 3, or 4-sized)
• matrices
• planes
• 3D axis aligned bounding boxes
• spheres
• frustums

Graphene also provides its low-level SIMDvectorandmatrixtypes, which are used to implement the API above.

All types can be placed on the stack, but provide allocation/free functionsfor working on the heap as well. The contents of all structure types, unlessnoted otherwise, should be considered private, and should never be accesseddirectly.

The full API reference for Graphene isavailable online.

Graphene is released under the terms of the MIT/X11 license.

See thelicense file for more details.