doc/gfx_python.txt

   1 Python GFX module
   2 -----------------
   3
   4 The python binding maps mostly to the C API with the 'GP_' prefix stripped.
   5
   6 The gfx module adds methods to the gfx context submodule.
   7
   8 NOTE: You may want to see the link:coordinate_system.html[coordinate system]
   9       first.
  10
  11 Drawing functions
  12 ~~~~~~~~~~~~~~~~~
  13
  14 All drawing functions takes a 'pixel' value (to describe color) which
  15 link:core_python.html#Colors_and_Pixels[can be obtained], for a particular
  16 pixel type (context), from a RGB triplet.
  17
  18 All drawing functions are clipped. Drawing outside of a context is no-op.
  19
  20 WARNING: Drawing functions takes strictly integer coordinates, make sure that
  21          all divisions are integer divisions (i.e. use // instead of /) to
  22          ensure portability with Python 3.X.
  23
  24 Line Based Primitives
  25 ^^^^^^^^^^^^^^^^^^^^^
  26
  27 [source,python]
  28 -------------------------------------------------------------------------------
  29 import gfxprim.gfx as gfx
  30
  31      context.gfx.HLine(x0, x1, y, pixel)
  32
  33 -------------------------------------------------------------------------------
  34
  35 Draws a horizontal line from 'x0' to 'x1' at 'y'.
  36
  37 [source,python]
  38 -------------------------------------------------------------------------------
  39 import gfxprim.gfx as gfx
  40
  41      context.gfx.VLine(x, y0, y1, pixel)
  42
  43 -------------------------------------------------------------------------------
  44
  45 Draws a vertical line from 'y0' to 'y1' at 'x'.
  46
  47
  48 [source,python]
  49 -------------------------------------------------------------------------------
  50 import gfxprim.gfx as gfx
  51
  52      context.gfx.Line(x0, y0, x1, y1, pixel)
  53
  54 -------------------------------------------------------------------------------
  55
  56 Draws a line from x0, y0 to x1, y1.
  57
  58 [source,python]
  59 -------------------------------------------------------------------------------
  60 import gfxprim.gfx as gfx
  61
  62      context.gfx.Rect(x0, y0, x1, y1, pixel)
  63
  64 -------------------------------------------------------------------------------
  65
  66 Draws a rectangle defined by two points.
  67
  68 [source,python]
  69 -------------------------------------------------------------------------------
  70 import gfxprim.gfx as gfx
  71
  72      context.gfx.Triangle(x0, y0, x1, y1, x1, y2, pixel)
  73
  74 -------------------------------------------------------------------------------
  75
  76 Draws a triangle defined by three points.
  77
  78 [source,python]
  79 -------------------------------------------------------------------------------
  80 import gfxprim.gfx as gfx
  81
  82      context.gfx.Tetragon(x0, y0, x1, y1, x1, y2, x3, y3, pixel)
  83
  84 -------------------------------------------------------------------------------
  85
  86 Draws a tetragon defined by four points.
  87
  88 [source,python]
  89 -------------------------------------------------------------------------------
  90 import gfxprim.gfx as gfx
  91
  92      context.gfx.Polygon([x0, y0, x1, y1, ...], pixel)
  93
  94      context.gfx.Polygon([(x0, y0), (x1, y1), ...], pixel)
  95
  96 -------------------------------------------------------------------------------
  97
  98 Draws a polygon defined by points, points can be either flat list of 2N
  99 integers or list of N tuples.
 100
 101 [source,python]
 102 -------------------------------------------------------------------------------
 103 import gfxprim.gfx as gfx
 104
 105      context.gfx.Circle(x, y, r, pixel)
 106
 107 -------------------------------------------------------------------------------
 108
 109 Draws a circle.
 110
 111 [source,python]
 112 -------------------------------------------------------------------------------
 113 import gfxprim.gfx as gfx
 114
 115      context.gfx.Ellipse(x, y, a, b, pixel)
 116
 117 -------------------------------------------------------------------------------
 118
 119 Draws an ellipse.
 120
 121 [source,python]
 122 -------------------------------------------------------------------------------
 123 import gfxprim.gfx as gfx
 124
 125      context.gfx.Ring(x, y, r1, r2, pixel)
 126
 127 -------------------------------------------------------------------------------
 128
 129 Draws a ring.
 130
 131 Filled Primitives
 132 ^^^^^^^^^^^^^^^^^
 133
 134 [source,python]
 135 -------------------------------------------------------------------------------
 136 import gfxprim.gfx as gfx
 137
 138     context.gfx.Fill(pixel)
 139
 140 -------------------------------------------------------------------------------
 141
 142 Fills context with particular 'pixel' value.
 143
 144 [source,python]
 145 -------------------------------------------------------------------------------
 146 import gfxprim.gfx as gfx
 147
 148      context.gfx.FillRect(x0, y0, x1, y1, pixel)
 149
 150 -------------------------------------------------------------------------------
 151
 152 Fills a rectangle defined by two points.
 153
 154 [source,python]
 155 -------------------------------------------------------------------------------
 156 import gfxprim.gfx as gfx
 157
 158      context.gfx.FillTriangle(x0, y0, x1, y1, x1, y2, pixel)
 159
 160 -------------------------------------------------------------------------------
 161
 162 Draws a filled triangle defined by three points.
 163
 164 [source,python]
 165 -------------------------------------------------------------------------------
 166 import gfxprim.gfx as gfx
 167
 168      context.gfx.FillTetragon(x0, y0, x1, y1, x1, y2, x3, y3, pixel)
 169
 170 -------------------------------------------------------------------------------
 171
 172 Draws a filled tetragon defined by four points.
 173
 174 [source,python]
 175 -------------------------------------------------------------------------------
 176 import gfxprim.gfx as gfx
 177
 178      context.gfx.FillPolygon([x0, y0, x1, y1, ...], pixel)
 179
 180      context.gfx.FillPolygon([(x0, y0), (x1, y1), ...], pixel)
 181
 182 -------------------------------------------------------------------------------
 183
 184 Fills a polygon defined by points, points can be either flat list of 2N
 185 integers or list of N tuples.
 186
 187 [source,python]
 188 -------------------------------------------------------------------------------
 189 import gfxprim.gfx as gfx
 190
 191      context.gfx.FillCircle(x, y, r, pixel)
 192
 193 -------------------------------------------------------------------------------
 194
 195 Fills a circle.
 196
 197 [source,python]
 198 -------------------------------------------------------------------------------
 199 import gfxprim.gfx as gfx
 200
 201      context.gfx.FillEllipse(x, y, a, b, pixel)
 202
 203 -------------------------------------------------------------------------------
 204
 205 Fills an ellipse.
 206
 207 [source,python]
 208 -------------------------------------------------------------------------------
 209 import gfxprim.gfx as gfx
 210
 211      context.gfx.FillRing(x, y, r1, r2, pixel)
 212
 213 -------------------------------------------------------------------------------
 214
 215 Fills a ring, i.e. area enclosed between two circles.
 216
 217 TIP: See gfx module link:example_py_gfx.html[example].