git.rot13.org Git - simavr/blob - examples/shared/libc3/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 Introduction
  16 -----------
  17 The general idea is that the library keeps track of geometry and stuff, but doesn't
  18 do *any* opengl or related calls. Instead, it uses callbacks into code that will
  19 take care of the rendering related tasks.
  20
  21 So for example a c3pixels represents a texture, but a callback into the rendering
  22 layer will be responsible to push the pixels to OpenGL, and store the object back
  23 into the c3pixels for reference.
  24
  25 Status
  26 -------
  27 The API is generally functional, but it's brand new. I try not to add bits that
  28 I aren't needed, and I also don't add stuff that isn't tested.
  29
  30 There is an ASCII STL file loader that works, and a few other bit of geometry related
  31 helpers.
  32
  33 It's currently used in one 'serious' project and also in my [3D printer simulator](https://github.com/buserror-uk/simavr/tree/master/examples/board_reprap),
  34 as part of simavr. There you cal also find the "opengl renderer" set of callbacks, in the
  35 near future, this layer will be part of a *libc3-gl* companion library.
  36
  37 General Roadmap
  38 ---------------
  39 There is a [PDF Flowchart](https://github.com/buserror-uk/libc3/raw/master/doc/libc3-flowchart.pdf)
  40 of how things are mostly organized as far as data structure goes, but the following is a
  41 breakdown of the major components.
  42
  43 The API has various bits:
  44 * c3algebra: C derivative of an old C++ piece of code I had lying around and that has
  45 been present in my toolset for a long time. It gives you *vectors* (c3vec2, c3vec3, c3vec4)
  46 and *matrices* (c3mat3, c3mat4) with various tools to manipulate them.
  47 * c3quaternion: Quaternion implementation using c3algebra
  48 * c3camera/c3arcball: camera manipulation bits
  49
  50 The basic data structure is as follow:
  51 * *c3context*:
  52         Hosts a "root" object, and a list of 'viewpoints' (ie either cameras, or lights).
  53         it can reproject the objects & geometries, and call the callbacks to draw them.
  54
  55         The context also keeps a list of *c3pixels* and *c3program* that are referenced
  56         by the geometries.
  57 * *c3object*:
  58         * Has a list of (sub) c3objects
  59         * Has a list of c3transforms (ie matrices)
  60         * Has a list of c3geometry (ie real vertices and stuff)
  61   The object is a container for other objects, and for geometry itself. Objects don't
  62   necessary have geometry and/or sub objects, and don't even need transforms if their
  63   vertices are already projected.
  64 * *c3geometry*:
  65         * Has a 'type' (raw for simple vertices, texture, triangles etc)
  66         * Has a 'subtype' (mostly can be used to draw GL types)
  67         * Has a 'material' (ie color, texture, a GPU program... to be completed)
  68         * Has a list of vertices
  69         * Has a cached copy of a vertices when it has been 'projected'
  70         * Has a list of texture coordinates (optional)
  71         * Has a list of vertices colors (optional)
  72         * Had a list of vertices indexes (optional)
  73 * *c3transform*:
  74         Is just a sugar coated matrix, with an optional name.
  75
  76 Also there are:
  77 * *c3pixels*:
  78         Is just a wrapper/holder for some pixels, either allocated, or inherited,
  79         it's mostly used for *c3texture*
  80 * *c3texture*:
  81         Associates a *c3geometry* with a *c3pixels* and has a standard Quad
  82         for vertices. The OpenGL drawing is not done there, it's done by the application using
  83         the generic *c3context* driver.
  84 * *c3cairo*:
  85         Placeholder for now, inherits from *c3texture* and will contain a
  86         cairo surface mapped to a GL texture.
  87
  88 Draw Drivers "Inheritance"
  89 ------------
  90 Various object uses static tables of callbacks to implement their behaviours
  91 it's kinda cheap c++ inheritance, without the usual bloat.
  92
  93 There just a couple macros to call the driver chain for a particular function call.
  94 The relevant bits are in c3driver*.h.
  95
  96 Mostly the code looks for a matching callback in a static table, and call it if found.
  97 If that callback wants, it can also call the inherited object callback too.
  98
  99 Dirtyness
 100 ---------
 101 There is a notion of 'dirtyness' in the tree, when you touch a *c3transform*, and/remove
 102 objects and geometry, a dirty bit is propagated up the tree of object. This tells the
 103 rendering it needs to reproject the dirty bits and repopulate the projected vertice
 104 cache.
 105
 106 The 'dirty' bit moves both ways, when setting a dirty bit to true, it propagates upward,
 107 when you set it to false, it propagates downward in the tree.