Drawing and Filling

void draw ([const Color& ddraw_color = *Colors::default_color, [const string ddashed = "", [const string ppen = "", [Picture& picture = current_picture]]]])	const virtual function
void draw (Picture& picture, [const Color& ddraw_color = *Colors::default_color, [string ddashed = "", [string ppen = ""]]])	const Virtual function

Allocates a copy of the Path on the free store, puts a pointer to the copy on picture.shapes, sets its fill_draw_value to DRAW, and the values of its draw_color, dashed, and pen according to the arguments. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. All of the arguments to draw() are optional, so it can be invoked as follows: Point A; Point B(2); Point C(3, 3); Point D(1, 2); Point E(-1, 1); Path p("..", true, &A, &B, &C, &D, &E, 0); p.draw(); Fig. 120. The arguments: ddraw_color Used to specify a color for the Path. ddraw_color is a reference to a Color. Colors are described in Color Reference. The most basic Colors are predefined in 3DLDF (in the namespace Colors), and users may create new Colors and specify their red-green-blue values. The Path p could be drawn in red by calling p.draw(Colors::red). This manual isn't intended to be printed in color, so there's no figure to demonstrate this. However, gray values can be printed on non-color printers. using namespace Colors; p.draw(gray, "", "pencircle scaled .25mm"); Fig. 121. ddashed A string representing a "dash pattern", as defined in MetaPost1. Dash patterns have no meaning in 3DLDF, they are simply strings that are written unchanged to out_stream. p.draw(black, "evenly"); Fig. 122. ppen A string representing a "pen", as defined in Metafont and MetaPost2. Pens have no meaning in 3DLDF, they are simply strings that are written unchanged to out_stream. p.draw(black, "", "pensquare xscaled 3mm yscaled .25mm scaled .5mm"); Fig. 123. picture Indicates the Picture on which the Path should be drawn. The two versions of draw() differ in the position of the picture argument: In the first version, it's the last argument, while in the second version, it's the first argument. If a picture argument is used, it's often more convenient to use the second version. The following example puts Path p onto temp_picture. It also demonstrates how the labels are put onto temp_picture, and how temp_picture is output. In the previous examples, the commands for making the labels and outputting current_picture were left out in order to reduce clutter. See Point Reference; Labelling, and Picture Reference; Outputting; Output Functions. Picture temp_picture; p.draw(temp_picture); A.dotlabel("A", "bot", temp_picture); B.dotlabel("B", "bot", temp_picture); C.dotlabel("C", "top", temp_picture); D.dotlabel("D", "top", temp_picture); E.dotlabel("E", "lft", temp_picture); temp_picture.output(Projections::PARALLEL_X_Y); Fig. 124.

void draw_help ([const Color& ddraw_color = *help_color, [string ddashed = help_dash_pattern, [string ppen = "", [Picture& picture = current_picture]]]])	const function
void draw_help (Picture& picture, [const Color& ddraw_color = *help_color, [string ddashed = help_dash_pattern, [string ppen = ""]]])	const function

This functions are for drawing help lines. They are like draw(), except that draw_help() returns immediately, if do_help_lines (a static data member in Path) is false. Also, the defaults for ddraw_color and ddashed differ from those for draw().

void drawarrow ([const Color& ddraw_color = *Colors::default_color, [string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]]])	const virtual function
void drawarrow (Picture& picture, [const Color& ddraw_color = *Colors::default_color, [string ddashed = "", [string ppen = ""]]])	const virtual function

Like draw(), except that the MetaPost command drawarrow is written to out_stream when picture is output. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. Point m; Point n(2, 2); m.dotlabel("$m$", "bot"); n.dotlabel("$n$"); m.drawarrow(n); Fig. 125.

void draw_axes ([real dist = 2.5, [string pos_x = "bot", [string pos_y = "lft", [string pos_z = "bot", [const Color& ddraw_color = *Colors::default_color, [const string ddashed = "", [const string ppen = "", [const Point& shift_x = origin, [const Point& shift_y = origin, [const Point& shift_z = origin, [Picture& picture = current_picture]]]]]]]]]]])	Non-member function
void draw_axes (const Color& ddraw_color, [real dist = 2.5, [string pos_x = "bot", [string pos_y = "lft", [string pos_z = "bot", [const string ddashed = "", [const string ppen = "", [const Point& shift_x = origin, [const Point& shift_y = origin, [const Point& shift_z = origin, [Picture& picture = current_picture]]]]]]]]]])	Non-member function

These functions draw lines centered on the origin, and ending in arrows in the directions of the positive x, y, and z-axes, and labels them with the appropriate letters. draw_axes() is used in many of the figures in this handbook. It can be helpful in determining whether a Focus has a good "up" direction. See Focus Reference; Data Members. In the first version, all of the arguments are optional. In the second version, ddraw_color is required and has been moved to the front of the argument list. This version is often convenient, when a Color other than the default is desired. The arguments: dist The length of the lines drawn. The default is 2.5. The value 0 can be used as a dummy argument, if the default for dist is desired, but other arguments must be specified. pos_x pos_y pos_z The position arguments for the labelling commands for each of the axes. The defaults are "bot" for the x and z-axes, and "lft" for the y-axis. The usual strings for the position of labels can be used, namely: "top", "bot", "lft", "rt", "ulft", "urt", "llft", "lrt", and "". If "" is used, that axis is not drawn. This can be useful for parallel projections onto one of the major planes3. In addition, "d" can be used to indicate that the default should be used for that label. This can be useful if one needs a placeholder, but doesn't remember what the default is for that label. draw_axes(0, "bot", "rt", ""); current_picture.output(Projections::PARALLEL_X_Y); Fig. 126. In addition, the arguments shift_x, shift_y, and shift_z can be used to adjust the positions of the labels further (see below). ddraw_color ddashed ppen Arguments for the drawarrow() command, described above, in this section. shift_x shift_y shift_z Offsets for the labels. These arguments make it possible to adjust the positions of the labels. The defaults are origin, so no shifting takes place, if they are used. In [next figure] , draw_axes is called without any arguments, so the defaults are used. draw_axes(); Fig. 127. In [next figure] , the Point P is used to shift the labels. Please note that placeholders must be used for the first arguments. Point P(.5, .5, .5); draw_axes(0, "d", "d", "d", black, "", "", P, -P, P); Fig. 128. Please note that the Points used for placing the labels are three-dimensional Points, whether the shift_x, shift_y, and/or shift_z arguments are used or not. It is not currently possible to adjust the positions of the labels on the two-dimensional projection itself. This would probably be more useful, but would require changing the way Picture::output() functions. picture The Picture, onto which the Paths and Labels are put.

void fill ([const Color& ffill_color = *Colors::default_color, [Picture& picture = current_picture]])	const function
void fill (Picture& picture, [const Color& ffill_color = *Colors::default_color])	Function

Allocates a copy of the Path on the free store, puts a pointer to it onto picture.shapes, sets its fill_draw_value to FILL, and its fill_color to *ffill_color. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. The arguments are similar to those of draw(), except that the Color argument is called ffill_color instead of ddraw_color. p.fill(gray); Fig. 129.

void filldraw ([const Color& ddraw_color = *Colors::default_color, [const Color& ffill_color = *Colors::background_color, [string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]]]])	const function
void filldraw (Picture& picture, [const Color& ddraw_color = *Colors::default_color, [const Color& ffill_color = *Colors::background_color, [string ddashed = "", [string ppen = ""]]]])	const function

Allocates a copy of the Path on the free store, puts a pointer to the copy onto picture.shapes, sets its fill_draw_value to FILLDRAW, its draw_color and fill_color to *ddraw_color and *ffill_color, respectively, its dashed to ddashed, and its pen to ppen. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. The arguments are similar to those of draw() and fill(), except that both ddraw_color and ffill_color are used. 3DLDF's filldraw() differs from Metafont's and MetaPost's filldraw commands: In Metafont and MetaPost, filldrawing is equivalent to filling a path and then drawing its border using the pen. Metafont does not have colors. While MetaPost does, its filldraw command does not foresee the use of different colors for drawing and filling. p.filldraw(black, gray, "", "pencircle scaled 2mm"); Fig. 130. It can often be useful to draw the outline of a Path, but to have it hide objects that lie behind it. This is why the default for ffill_color is *Colors::background_color. default_focus.set(3, 0, -10, 3, 10, 10, 10); Point p[8]; p[0] = p[1] = p[2] = p[3] = p[4] = p[5] = p[6] = p[7].set(-1,-1, 5); p[1] *= p[2] *= p[3] *= p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45); p[2] *= p[3] *= p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45); p[3] *= p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45); p[4] *= p[5] *= p[6] *= p[7].rotate(0, 0, 45); p[5] *= p[6] *= p[7].rotate(0, 0, 45); p[6] *= p[7].rotate(0, 0, 45); p[7].rotate(0, 0, 45); Path r0("..", true, &p[0], &p[1], &p[2], &p[3], &p[4], &p[5], &p[6], &p[7], 0); r0.filldraw(black, light_gray); r0.scale(2, .5); r0.shift(0, 0, -2.5); r0.filldraw(black, gray); r0.scale(.25, 3); r0.shift(0, 0, -2.5); r0.filldraw(); Fig. 131.

void undraw ([string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]])	Function
void undraw (Picture& picture, [string ddashed = "", [string ppen = ""]])	Function

Allocates a copy of the Path on the free store, puts a pointer to it on picture.shapes, sets its fill_draw_value to UNDRAW, and the values of its dashed and pen according to the arguments. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. This function "undraws" a Path. This is equivalent to drawing the Path using the background color (*Colors::background_color). Undrawing is useful for removing a portion of a Path. Point P0(1, 1); Point P1(2, 1); Point P2(2, 3); Point P3(-1, 1); Path p("--", false, &origin, &P0, &P1, &P2, &P3, 0); p.draw(black, "", "pencircle scaled 3mm"); p.undraw("", "pencircle scaled 1mm"); Fig. 132.

void unfill ([Picture& picture = current_picture])

Function

Allocates a copy of the Path on the free store, puts a pointer to it on picture.shapes and sets its fill_draw_value to UNFILL This function is useful for removing a portion of a filled region. Point pt[4]; pt[0].set(-2, -2); pt[1].set(2, -2); pt[2].set(2, 2); pt[3].set(-2, 2); Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], 0); p.draw(); p.dotlabel(); p.filldraw(black, gray); p.scale(.5, .5); p.unfill(); Fig. 133.

void unfilldraw ([const Color& ddraw_color = *Colors::background_color, [string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]]])	Function
void unfilldraw (Picture& picture, [const Color& ddraw_color = *Colors::background_color, [string ddashed = "", [string ppen = ""]]])	Function

Allocates a copy of the Path on the free store, puts a pointer to it on picture.shapes, sets its fill_draw_value to UNFILLDRAW, and the values of its draw_color, dashed, and pen according to the arguments. While the default for ddraw_color is *Colors::background_color, any other Color can be used, so that unfilldraw() can unfill a Path and draw an outline around it. The second version is convenient for passing a Picture argument without having to specify all of the other arguments. This function is similar to unfill() (see Path Reference; Drawing and Filling), except that the outline of the Path will be "undrawn" using the pen specified with the ppen argument, or MetaPost's currentpen, if no ppen argument is specified. In addition, the Path will be drawn using the Color specified in the ddraw_color argument. Since the default is *Colors::background_color, the Path will be "undrawn" unless a different Color is specified. Point pt[6]; pt[0].set(-2, -2); pt[1].set(0, -3); pt[2].set(2, -2); pt[3].set(2, 2); pt[4].set(0, 3); pt[5].set(-2, 2); Path p("--", true, &pt[0], &pt[1], &pt[2], &pt[3], &pt[4], &pt[5], 0); p.fill(gray); p.scale(.5, .5); p.unfilldraw(black, "", "pensquare xscaled 3mm"); Fig. 134.