const virtual function: 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 = ""]]])Allocates a copy of the
Pathon the free store, puts a pointer to the copy on picture.shapes, sets itsfill_draw_valuetoDRAW, and the values of itsdraw_color,dashed, andpenaccording to the arguments.The second version is convenient for passing a
Pictureargument 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 aColor. Colors are described in Color Reference.The most basic
Colorsare predefined in 3DLDF (in thenamespace Colors), and users may create newColorsand specify their red-green-blue values.The
Path pcould be drawn in red by callingp.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
stringrepresenting a “dash pattern”, as defined in MetaPost1. Dash patterns have no meaning in 3DLDF, they are simplystringsthat are written unchanged toout_stream.p.draw(black, "evenly");
![]()
Fig. 122.
- ppen
- A
stringrepresenting a “pen”, as defined in Metafont and MetaPost2. Pens have no meaning in 3DLDF, they are simplystringsthat are written unchanged toout_stream.p.draw(black, "", "pensquare xscaled 3mm yscaled .25mm scaled .5mm");
![]()
Fig. 123.
- picture
- Indicates the
Pictureon which thePathshould 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 pontotemp_picture. It also demonstrates how the labels are put ontotemp_picture, and howtemp_pictureis output. In the previous examples, the commands for making the labels and outputtingcurrent_picturewere 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.
const function: 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 = ""]]])This functions are for drawing help lines. They are like
draw(), except thatdraw_help()returns immediately, ifdo_help_lines(a static data member inPath) isfalse. Also, the defaults for ddraw_color and ddashed differ from those fordraw().
const virtual function: 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 = ""]]])Like
draw(), except that the MetaPost commanddrawarrowis written toout_streamwhenpictureis output. The second version is convenient for passing aPictureargument 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.
*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]]]]]]]]]]])origin, [const Point& shift_y = origin, [const Point& shift_z = origin, [Picture& picture = current_picture]]]]]]]]]])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 aFocushas 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
Colorother 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 usualstringsfor 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_axesis called without any arguments, so the defaults are used.draw_axes();
![]()
Fig. 127.
In [next figure] , the
Point Pis 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
Pointsused for placing the labels are three-dimensionalPoints, 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 wayPicture::output()functions.- picture
- The
Picture, onto which thePathsandLabelsare put.
const function: void fill ([const Color& ffill_color = *Colors::default_color, [Picture& picture = current_picture]])*Colors::default_color])Allocates a copy of the
Pathon the free store, puts a pointer to it onto picture.shapes, sets itsfill_draw_valuetoFILL, and itsfill_colorto*ffill_color.The second version is convenient for passing a
Pictureargument without having to specify all of the other arguments.The arguments are similar to those of
draw(), except that theColorargument is called ffill_color instead of ddraw_color.p.fill(gray);
![]()
Fig. 129.
const function: 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 = ""]]]])Allocates a copy of the
Pathon the free store, puts a pointer to the copy onto picture.shapes, sets itsfill_draw_valuetoFILLDRAW, itsdraw_colorandfill_colorto*ddraw_color and*ffill_color, respectively, itsdashedto ddashed, and itspento ppen.The second version is convenient for passing a
Pictureargument without having to specify all of the other arguments.The arguments are similar to those of
draw()andfill(), except that both ddraw_color and ffill_color are used.3DLDF's
filldraw()differs from Metafont's and MetaPost'sfilldrawcommands: In Metafont and MetaPost,filldrawingis equivalent to filling apathand then drawing its border using thepen. Metafont does not have colors. While MetaPost does, itsfilldrawcommand 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.
current_picture]]])Allocates a copy of the
Pathon the free store, puts a pointer to it on picture.shapes, sets itsfill_draw_valuetoUNDRAW, and the values of itsdashedandpenaccording to the arguments.The second version is convenient for passing a
Pictureargument without having to specify all of the other arguments.This function “undraws” a
Path. This is equivalent to drawing thePathusing 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.
current_picture])Allocates a copy of the
Pathon the free store, puts a pointer to it on picture.shapesand sets itsfill_draw_valuetoUNFILLThis 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.
*Colors::background_color, [string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]]])*Colors::background_color, [string ddashed = "", [string ppen = ""]]])Allocates a copy of the
Pathon the free store, puts a pointer to it on picture.shapes, sets itsfill_draw_valuetoUNFILLDRAW, and the values of itsdraw_color,dashed, andpenaccording to the arguments. While the default for ddraw_color is*Colors::background_color, any otherColorcan be used, so thatunfilldraw()can unfill aPathand draw an outline around it.The second version is convenient for passing a
Pictureargument 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 thePathwill be “undrawn” using the pen specified with the ppen argument, or MetaPost'scurrentpen, if no ppen argument is specified. In addition, thePathwill be drawn using theColorspecified in the ddraw_color argument. Since the default is*Colors::background_color, thePathwill be “undrawn” unless a differentColoris 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.
[1] Hobby, A User's Manual for MetaPost, p. 32.
[2] Knuth, The METAFONTbook, Chapter 4, p. 21ff. Hobby, A User's Manual for MetaPost, p. 32.
[3] The usual interpretation of "" as a
position argument to a
labelling command would be to put it directly onto *(Label.pt),
which in this case would put it onto the arrowhead. Since this
will probably never be desirable, I've decided to use "" to
suppress drawing axes. Formerly, draw_axes() used three
additional arguments for this purpose.