filters/gp_filter_resize_alloc: Check w and h
[gfxprim.git] / doc / gfx.txt
blobf029674faa648ec399ebdd58fbe0baf550064717
1 Drawing primitives
2 ------------------
4 Drawing primitives implements algorithms to draw basic geometric shapes such
5 as lines, circles, etc.
7 You may want to see the link:coordinate_system.html[coordinate system] first.
9 See also RGB tripplet to pixel link:convert.html[conversions].
11 Rotation Flags
12 ~~~~~~~~~~~~~~
14 Drawing orientation is affected by the link:pixmap.html[pixmap rotation
15 flags]. The parameters passed to the functions are transformed accordingly to
16 the flags before the drawing, which allows for fast and transparent rotated or
17 mirrored rendering.
20 Getting and Putting Pixels
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~
23 link:get_put_pixel.html[getpixel() and putpixel()] are implemented in the
24 library core.
26 Fill
27 ~~~~
29 [source,c]
30 --------------------------------------------------------------------------------
31 void gp_fill(gp_pixmap *pixmap, gp_pixel pixel);
32 --------------------------------------------------------------------------------
34 Fills the whole pixmap bitmap with the specified pixel value.
36 NOTE: gp_fill() is implemented in the library Core rather than in GFX so that
37       it's available to all library parts.
39 Lines
40 ~~~~~
42 [source,c]
43 --------------------------------------------------------------------------------
44 void gp_hline_xxy(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, gp_pixel pixel);
46 void gp_hline(gp_pixmap *pixmap, gp_coord x0, gp_coord x1, gp_coord y, gp_pixel pixel);
47 --------------------------------------------------------------------------------
49 Draws a horizontal line from (x0, y) to (x1, y), inclusive. The coordinates
50 x0, x1 can be specified in any order.
52 'gp_hline()' is an alias for 'gp_hline_xxy()'.
54 [source,c]
55 --------------------------------------------------------------------------------
56 void gp_hline_xyw(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size w, gp_pixel pixel);
57 --------------------------------------------------------------------------------
59 Draws a horizontal line from (x, y) to (x+w-1, y), inclusive.
62 [source,c]
63 --------------------------------------------------------------------------------
64 void gp_vline_xyy(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
65                   gp_pixel pixel);
67 void gp_vline(gp_pixmap *pixmap, gp_coord x, gp_coord y0, gp_coord y1,
68               gp_pixel pixel);
69 --------------------------------------------------------------------------------
71 Draws a vertical line from (x, y0) to (x, y1), inclusive. The coordinates
72 y0, y1 can be specified in any order.
74 'gp_vline()' is an alias for 'gp_vline_xyy()'.
76 [source,c]
77 --------------------------------------------------------------------------------
78 void gp_vline_xyh(gp_pixmap *pixmap, gp_coord x, gp_coord y, gp_size h,
79                   gp_pixel pixel);
81 --------------------------------------------------------------------------------
83 Draws a vertical line from (x, y) to (x, y+h-1), inclusive.
85 [source,c]
86 --------------------------------------------------------------------------------
87 void gp_line(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
88              gp_coord x1, gp_coord y1, gp_pixel pixel);
89 --------------------------------------------------------------------------------
91 Draws a line from (x0, y0) to (x1, y1), inclusive. The starting and ending
92 point can be specified in any order (the implementation guarantees that
93 exactly the same set of pixels will be drawn in both cases).
95 Circles
96 ~~~~~~~
98 [source,c]
99 --------------------------------------------------------------------------------
100 void gp_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
101                gp_size r, gp_pixel pixel);
102 --------------------------------------------------------------------------------
104 Draws a circle centered at (xcenter, ycenter) with radius 'r' (in pixels).
106 The circle is drawn so that all affected pixels will fit into a square
107 specified by points (xcenter-r, ycenter-r, xcenter+r, ycenter+r), inclusive.
109 [source,c]
110 --------------------------------------------------------------------------------
111 void gp_fill_circle(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
112                     gp_size r, gp_pixel pixel);
113 --------------------------------------------------------------------------------
115 Draws a filled circle.
117 The set of pixels affected by 'gp_fill_circle()' is exactly the same as if
118 drawing the circle boundary using 'gp_circle()' and then filling all pixels
119 within the boundary with the same color.
121 Rings
122 ~~~~~
123 [source,c]
124 --------------------------------------------------------------------------------
125 void gp_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
126              gp_size r1, gp_size r2, gp_pixel pixel);
127 --------------------------------------------------------------------------------
129 Draws a ring (two circles centered at (xcenter, ycenter) with radii 'r1' and 'r2').
131 The result is exactly the same as calling 'gp_circle()' with the same center
132 and appropriate radii.
134 [source,c]
135 --------------------------------------------------------------------------------
136 void gp_fill_ring(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
137                   gp_size r1, gp_size r2, gp_pixel pixel);
138 --------------------------------------------------------------------------------
140 Draws a filled ring.
142 The smaller of r1 and r2 is used for inner radius and bigger one for outer
143 radius.
145 Ellipses
146 ~~~~~~~~
148 [source,c]
149 --------------------------------------------------------------------------------
150 void gp_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
151                 gp_size a, gp_size b, gp_pixel pixel);
152 --------------------------------------------------------------------------------
154 Draws an axis-aligned ellipse.
156 The ellipse is drawn so that all affected pixels will fit into a rectangle
157 specified by points (xcenter-a, ycenter-b, xcenter+a, ycenter+b), inclusive.
159 [source,c]
160 --------------------------------------------------------------------------------
161 void gp_fill_ellipse(gp_pixmap *pixmap, gp_coord xcenter, gp_coord ycenter,
162                      gp_size a, gp_size b, gp_pixel pixel);
163 --------------------------------------------------------------------------------
165 Draws a filled axis-aligned ellipse.
167 Triangles
168 ~~~~~~~~~
170 [source,c]
171 --------------------------------------------------------------------------------
172 void gp_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
173                  gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
174                  gp_pixel pixel);
175 --------------------------------------------------------------------------------
177 Draws a triangle.
179 [source,c]
180 --------------------------------------------------------------------------------
181 void gp_fill_triangle(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
182                       gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
183                       gp_pixel pixel);
184 --------------------------------------------------------------------------------
186 Draws a filled triangle.
188 Rects
189 ~~~~~
191 [source,c]
192 --------------------------------------------------------------------------------
193 void gp_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
194                   gp_coord x1, gp_coord y1, gp_pixel pixel);
196 void gp_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
197                   gp_size w, gp_size h, gp_pixel pixel);
199 void gp_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
200              gp_coord x1, gp_coord y1, gp_pixel pixel);
201 --------------------------------------------------------------------------------
203 Draws a rectangle.
205 The 'gp_rect_xyxy()' expects two corner points (x0, y0), and (x1, y1).
206 The 'gp_rect_xywh()' expects a corner point (x0, y0), width and height.
207 The 'gp_rect()' function is an alias for 'gp_rect_xyxy()'.
209 [source,c]
210 --------------------------------------------------------------------------------
211 void gp_fill_rect_xyxy(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
212                        gp_coord x1, gp_coord y1, gp_pixel pixel);
214 void gp_fill_rect_xywh(gp_pixmap *pixmap, gp_coord x, gp_coord y,
215                        gp_size w, gp_size h, gp_pixel pixel);
217 void gp_fill_rect(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
218                   gp_coord x1, gp_coord y1, gp_pixel pixel);
219 --------------------------------------------------------------------------------
221 Draws a filled rectangle.
223 The 'gp_rect_xyxy' fills an area between corner points (x0, y0) and (x1, y1),
224 inclusive.
225 The 'gp_rect_xywh' fills an area starting from (x0, y0) with specified width
226 and height, i.e. from (x0, y0) to (x0 + w, x1 + y), NOT inclusive.
227 The 'gp_fill_rect()' functions is an alias for 'gp_fill_rect_xyxy()'.
229 Tetragons
230 ~~~~~~~~~
232 [source,c]
233 --------------------------------------------------------------------------------
234 void gp_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
235                  gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
236                  gp_coord x3, gp_coord y3, gp_pixel pixel);
237 --------------------------------------------------------------------------------
239 Draws a tetragon.
241 [source,c]
242 --------------------------------------------------------------------------------
243 void gp_fill_tetragon(gp_pixmap *pixmap, gp_coord x0, gp_coord y0,
244                      gp_coord x1, gp_coord y1, gp_coord x2, gp_coord y2,
245                      gp_coord x3, gp_coord y3, gp_pixel pixel);
246 --------------------------------------------------------------------------------
248 Draws a filled tetragon.
250 Polygons
251 ~~~~~~~~
253 [source,c]
254 --------------------------------------------------------------------------------
255 void gp_polygon(gp_pixmap *pixmap, unsigned int vertex_count,
256                 const gp_coord *xy, gp_pixel pixel);
257 --------------------------------------------------------------------------------
259 Draws a polygon.
261 [source,c]
262 --------------------------------------------------------------------------------
263 void gp_fill_polygon(gp_pixmap *pixmap, unsigned int vertex_count,
264                      const gp_coord *xy, gp_pixel pixel);
265 --------------------------------------------------------------------------------
267 Draws a filled polygon.
269 The coordinages are passed in [x0, y0, x1, y1, ...] order, the vertex count
270 describes a number of nodes, i.e. half of the size of the array.