libgedacairo/README

   1 ==============================================
   2  'gschem and Friends' Electronic Design Suite
   3 ==============================================
   4
   5 Copyright (C) 1998-2019 gEDA Developers
   6
   7 Cairo-based schematic and symbol renderer
   8 =========================================
   9
  10 The libgedacairo library provides a renderer for schematics and
  11 symbols based on the Cairo vector graphics library and the Pango font
  12 library.  Data for rendering is loaded using libgeda.
  13
  14 The library does *not* provide a rendering widget for programs
  15 (although it could be used to implement one).  It is intended for more
  16 general rendering usage, e.g. to screen, to printers, or to various
  17 image formats.
  18
  19 The library is based on Peter Clifton's preexisting gschem rendering
  20 code.
  21
  22 Please submit bug reports and patches to
  23 <http://bugs.launchpad.net/geda>, using the `libgedacairo' tag.
  24
  25 Using libgedacairo in your programs
  26 -----------------------------------
  27
  28 To use the library in your GNU Autotools-based program, add:
  29
  30   PKG_PROG_PKG_CONFIG
  31   PKG_CHECK_MODULES([GEDACAIRO], [libgedacairo], [], [])
  32
  33 to your `configure.ac', and then add:
  34
  35   AM_CFLAGS = $(GEDACAIRO_CFLAGS
  36   AM_LDFLAGS = $(GEDACAIRO_LDFLAGS)
  37
  38 to your `Makefile.am'.
  39
  40 To compile a very simple program without using a GNU Autotools, you
  41 could use a command like:
  42
  43   cc `pkg-config --cflags --libs libgedacairo` -o myprog myprog.c
  44
  45 Header files
  46 ------------
  47
  48 The main header file for the library is `libgedacairo/libgedacairo.h'.
  49
  50 It makes two main groups of API functions and and types available: the
  51 main EdaRenderer class (based on GObject), and a set of hinted
  52 rendering functions.
  53
  54 Coordinate systems
  55 ------------------
  56
  57 An important concept to understand when using an EdaRenderer is the
  58 distinction between Cairo's "device coordinates" and "user
  59 coordinates".  (Yes, go and look it up now).
  60
  61 Before calling any libgedacairo drawing functions, you must set up the
  62 Cairo context's transformation matrix so that user coordinates match
  63 coordinates on the schematic or symbol page.
  64
  65 The EdaRenderer class
  66 ---------------------
  67
  68 The EdaRenderer class is the main interface to the library.  It uses
  69 information from libgeda OBJECT structures to draw various schematic
  70 elements, control grips, and cues.
  71
  72 EdaRenderer is a GObject class, with several properties that control
  73 its behaviour:
  74
  75   "cairo-context"  [pointer]
  76       The `cairo_t' drawing context which the renderer draws to.
  77   "pango-context"  [pointer]
  78       The state of the Pango string-to-glyph itemiser.  If you don't set
  79       one explicitly, the renderer will automatically create one from
  80       the drawing context.
  81   "font-name"  [string]
  82       The font to use when drawing text.  By default, this is "Arial".
  83   "color-map"  [pointer]
  84       A GArray of libgeda `COLOR' structures which is used as the
  85       color map for drawing.  Note that the EdaRenderer does not make
  86       a copy of this array, and doesn't free it when the EdaRenderer
  87       is destroyed.
  88   "override-color"  [int] Index of a colour to force all drawing to
  89       take place with.  This can be used e.g. when highlighting a set
  90       of objects in a particular colour.  If "override-color" is set
  91       to -1, color override is disabled.
  92   "grip-size"  [double]
  93       Size to draw grips, in *user* coordinates.
  94   "render-flags"  [EdaRendererFlags]
  95       Flags that control various rendering options.
  96
  97 A EdaRendererFlags value can include any of these flags:
  98
  99   EDA_RENDERER_FLAG_HINTING
 100       Enable line hinting.  Set this flag if you are rendering to
 101       screen or to a raster image file, because it makes things look
 102       prettier.
 103   EDA_RENDERER_FLAG_PICTURE_OUTLINE
 104       Draw only the outlines of pictures, and not their contents.
 105   EDA_RENDERER_FLAG_TEXT_HIDDEN
 106       Draw text even if it is set to be invisible.
 107   EDA_RENDERER_FLAG_TEXT_OUTLINE
 108       Draw only the outlines of text objects.
 109   EDA_RENDERER_FLAG_TEXT_ORIGIN
 110       Draw small "X" markers indicating where text objects are
 111       anchored.
 112
 113 To actually draw things, EdaRenderer has three methods:
 114
 115   eda_renderer_draw()
 116       This does basic drawing of an OBJECT.
 117
 118   eda_renderer_draw_grips()
 119       Draw grips at all of the control points of an OBJECT.
 120
 121   eda_renderer_draw_cues()
 122       Draw cues for an object (e.g. at the unconnected ends of pins and
 123       nets, and at junctions in nets and buses).
 124
 125 Sometimes, it is useful to obtain the rendered bounding box of an
 126 OBJECT (for example, a text OBJECT's bounding box is determined by the
 127 font).
 128
 129   eda_renderer_get_user_bounds()
 130       Obtain the user bounds (which should be the same as world
 131       bounds) for an OBJECT.
 132
 133 These four methods all can be overridden from subclasses.
 134
 135 Lower-level drawing
 136 -------------------
 137
 138 Sometimes EdaRenderer is not enough!  libgedacairo provides a bunch of
 139 functions for doing lower-level drawing.
 140
 141 Several of these drawing functions take a `flags' argument.  At the
 142 moment, the only flag that may be applied is `EDA_CAIRO_ENABLE_HINTS'.
 143 If you have an EdaRenderer and you wish to obtain the same
 144 EdaCairoFlags value as used internally by the renderer, you can call
 145 eda_renderer_get_cairo_flags().
 146
 147 The `center' variants of the drawing functions should be used to draw
 148 shapes that need to be symmetrically centred on a particular point.
 149 The `center_width' arguments that these functions accept specify the
 150 width of the line that they are to be centred on, if applicable.  The
 151 distinction is required in order to make sure line hinting takes place
 152 correctly.
 153
 154 The available shape drawing functions are:
 155
 156   eda_cairo_line()
 157       Draw a straight line segment.
 158
 159   eda_cairo_box(),  eda_cairo_center_box()
 160       Draw a rectangular box.
 161
 162   eda_cairo_arc(), eda_cairo_center_arc()
 163       Draw a circular arc segment.
 164
 165   eda_cairo_path()
 166       Draw a path made up of straight line and Bézier curve segments.
 167
 168 To actually do the drawing, there are two additional functions:
 169
 170   eda_cairo_set_source_color()
 171       Use a colour map index and a GArray of COLOR structures to set
 172       the current Cairo drawing colour.
 173   eda_cairo_stroke()
 174       Stroke the current Cairo path, with libgeda-compatible stroke
 175       parameters.
 176
 177 ..
 178    Local Variables:
 179    mode: text
 180    End: