docs-mini/README.canvas

   1 Canvas - A 2D Drawing API
   2 =========================
   3
   4 Author: Thomas Geymayer <admin@tomprogs.at>
   5 Revision: 2012/05/18
   6
   7 Introduction
   8 ------------
   9
  10 With the increasing complexity of (glass) cockpits the need for a simple API to
  11 draw on a 2D surface without modifying the C++ core increased heavily in the
  12 last time. The 2D canvas is an effort to satisfy this needs. It is now possible
  13 to create offscreen rendertargets only by using the property tree and placing
  14 them on any 3D object on the aircraft by using certain filter criteria.
  15
  16 Currently it is only possible to place text on the canvas but 2d shapes (using
  17 OpenVG) are going to follow.
  18
  19 Creating a canvas
  20 -----------------
  21
  22 A new canvas can be instantiated by creating a node /canvas/texture[<INDEX>]
  23 with at least the following children:
  24
  25  <size n="0" type="int">       The width of the underlying texture
  26  <size n="1" type="int">       The height of the underlying texture
  27
  28  <view n="0" type="int">    The width of the canvas
  29  <view n="1" type="int">    The height of the canvas
  30
  31 The dimensions of the canvas are needed to be able to use textures with
  32 different resolutions but use the same units for rendering to the canvas.
  33 Therefore you can choose any texture size with the same canvas size and always
  34 get the same results (apart from resolution dependent artifacts).
  35
  36 * Filtering:
  37
  38  Optionally you can enable mipmapping and/or multisampling (Coverage Sampling
  39  Antialiasing):
  40
  41   <mipmapping type="bool">       Use mipmapping (default: false)
  42   <coverage-samples type="int">  Coverage Samples (default: 0)
  43   <color-samples type="int">     Color Samples (default: 0, always
  44                                  have to be <= coverage-samples)
  45 Drawing
  46 -------
  47
  48 Drawing to the canvas is accomplished by creating nodes as childs of the
  49 canvas root node. Every shape has to be a child of a <group> node. Currently
  50 only drawing Text is possible:
  51
  52 * General:
  53  The following parameters are used by multiple elements:
  54
  55  Color:
  56   A color can be specified by the following subtree (NAME is replaced by
  57   another name depending on the usage of the color)
  58
  59   <NAME>
  60     <red type="float">
  61     <green type="float">
  62     <blue type="float">
  63     <alpha type="float">
  64   </NAME>
  65
  66 * Text:
  67  Create a <text> node and configure with the following properties:
  68
  69  <text type="string">        The text to be displayed
  70  <font type="string">        The font to be used (Searched in
  71                               1. aircraft-dir/Fonts
  72                               2. aircraft-dir
  73                               3. $FG_DATA/Fonts
  74                               4. Default osg font paths
  75  <character-size type="float">          The font size (default: 32)
  76  <character-aspect-ratio type="float">  Ratio between character height and width
  77                                         (default: 1)
  78  <tf>               A 3x3 transformation matrix specified by 6 values
  79                     (child elements <m n="0">, ..., <m n="5"> which equal to a,
  80                      ...,f used in the SVG standard) See
  81                     http://www.w3.org/TR/SVG/coords.html#TransformMatrixDefined
  82                     for details.
  83                     You can also use shortcuts and use an alternative to
  84                     specifying six values:
  85                      - Translation: <t n="0">, <t n="1"> (both default to 0)
  86                      - Rotation: <rot>
  87                      - Scale: <s n="0">, <s n="1"> (s[0] is required, s[1]
  88                                                     defaults to s[0])
  89  <alginment type="string">   Text alignment (default: "left-baseline") One of:
  90
  91                               "left-top"
  92                               "left-center"
  93                               "left-bottom"
  94
  95                               "center-top"
  96                               "center-center"
  97                               "center-bottom"
  98
  99                               "right-top"
 100                               "right-center"
 101                               "right-bottom"
 102
 103                               "left-baseline"
 104                               "center-baseline"
 105                               "right-baseline"
 106
 107                               "left-bottom-baseline"
 108                               "center-bottom-baseline"
 109                               "right-bottom-baseline"
 110  <draw-mode type="int">      A bitwise combination of the following values
 111                              1 (Text - default)
 112                              2 (Boundingbox)
 113                              4 (Filled boundingbox)
 114                              8 (Alignment -> Draw a cross at the position
 115                                of the text)
 116  <padding type="float">      Padding between for the boundingbox (default: 0)
 117  <color>                     Text color
 118  <color-fill>                Fill color (for the bounding box)
 119
 120 Placement
 121 ---------
 122
 123 To place the canvas into the scene one ore more <placement> elements can be
 124 added to the texture node. By setting at least on of the following nodes
 125 the objects where the canvas texture should be placed on are selected:
 126
 127  <texture type="string">  Match objects with the given texture assigned
 128  <node type="string">     Match objects with the given name
 129  <parent type="string">   Match objects with a parent matching the given name
 130                           (Not necessarily the direct parent)
 131
 132 Example
 133 -------
 134
 135 <canvas>
 136   <texture>
 137     <size n="0" type="int">384</size-x>
 138     <size n="1" type="int">512</size-y>
 139     <view n="0" type="int">768</view-width>
 140     <view n="1" type="int">1024</view-height>
 141     <mipmapping type="bool">false</mipmapping>
 142     <coverage-samples type="int">0</coverage-samples>
 143     <color-samples type="int">0</color-samples>
 144     <color-background>
 145       <red type="float">0</red>
 146       <green type="float">0.02</green>
 147       <blue type="float">0</blue>
 148       <alpha type="float">1</alpha>
 149     </color-background>
 150     <group>
 151       <text>
 152         <text type="string">TEST MESSAGE</text>
 153         <font type="string">helvetica_bold.txf</font>
 154         <character-size type="float">40</character-size>
 155         <tf>
 156           <!-- Translate (18|50) -->
 157           <tx>18</tx>
 158           <ty>50</ty>
 159         </tf>
 160       </text>
 161     </group>
 162     <placement>
 163       <!-- Place on objects with the texture EICAS.png
 164            and a parent called HDD 1 -->
 165       <texture type="string">EICAS.png</texture>
 166       <parent type="string">HDD 1</parent>
 167     </placement>
 168   </texture>
 169 </canvas>