git.rot13.org Git - simavr/blob - examples/board_reprap/src/c3/README.md

   1 libc3 - No frill 'scene' graph library in C
   2 =====
   3 (C) 2012 Michel Pollet <buserror@gmail.com>
   4
   5 **WARNING** This API is not your nanny. It is made to be lean, mean, efficient
   6 with no frill, no asserts, no bounds checking, no sugar coating.
   7
   8 On the other hand it's fast, reasonably clean and is a micro-fraction of the
   9 other giganormous 'scene graphs' or 'game engine' libraries around.
  10
  11 It's vaguely inspired by THREE.js funnily enough, because it allows you to
  12 hack around and quickly get stuff on screen with the minimal amount of
  13 effort.
  14
  15 The API has various bits:
  16 * c3algebra: C derivative of an old C++ piece of code I had lying around and that has
  17 been present in my toolset for a long time. It gives you *vectors* (c3vec2, c3vec3, c3vec4)
  18 and *matrices* (c3mat3, c3mat4) with various tools to manipulate them.
  19 * c3quaternion: Quaternion implementation using c3algebra
  20 * c3camera/c3arcball: camera manipulation, not perfect
  21
  22 The data structure is as follow:
  23 * *c3object*:
  24         * Has a list of (sub) c3objects
  25         * Has a list of c3transforms (ie matrices)
  26         * Has a list of c3geometry (ie real vertices and stuff)
  27   The object is a container for other objects, and for geometry itself. Objects don't
  28   necessary have geometry and/or sub objects, and don't even need transforms if their
  29   vertices are already projected.
  30 * *c3geometry*:
  31         * Has a 'type' (lines, quads, triangles..)
  32         * Has a 'material' (ie color, texture... to be completed)
  33         * Has a list of vertices
  34         * Has a list of texture coordinates (optional)
  35         * Has a list of vertices colors (optional)
  36         * Has a cached copy of a vertices when it has been 'projected'
  37 * *c3transform*:
  38         Is just a sugar coated matrix, with an optional name.
  39
  40 Dirtyness
  41 ---------
  42 There is a notion of 'dirtyness' in the tree, when you touch c3transform, and/remove
  43 objects and geometry, a dirty bit is propagated up the tree of object. This tells the
  44 rendering it needs to reproject the dirty bits and repopulate the projected vertice
  45 cache.
  46
  47 The 'dirty' bit moves both ways, when setting a dirty bit to true, it propagates upward,
  48 when you set it to false, it propagates downward in the tree.
  49
  50 "Inheritance"
  51 -------------
  52 There is a vague notion of inheritance for objects, where you can create more complex
  53 ones and install a 'driver' (ie a function pointer table) that will be called to
  54 perform various things. The skim is still evolving.
  55