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
Path
on the free store, puts a pointer to the copy on picture.shapes
, sets itsfill_draw_value
toDRAW
, and the values of itsdraw_color
,dashed
, andpen
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 aColor
. Colors are described in Color Reference.The most basic
Colors
are predefined in 3DLDF (in thenamespace Colors
), and users may create newColors
and specify their red-green-blue values.The
Path p
could 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
string
representing a “dash pattern”, as defined in MetaPost1. Dash patterns have no meaning in 3DLDF, they are simplystrings
that are written unchanged toout_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 simplystrings
that are written unchanged toout_stream
.p.draw(black, "", "pensquare xscaled 3mm yscaled .25mm scaled .5mm");
![]()
Fig. 123.
- picture
- Indicates the
Picture
on which thePath
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
ontotemp_picture
. It also demonstrates how the labels are put ontotemp_picture
, and howtemp_picture
is output. In the previous examples, the commands for making the labels and outputtingcurrent_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.
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 commanddrawarrow
is written toout_stream
whenpicture
is output. The second version is convenient for passing aPicture
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.
*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 aFocus
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 usualstrings
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-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 thePaths
andLabels
are put.
const
function: void fill ([const Color& ffill_color = *Colors::default_color
, [Picture& picture = current_picture
]])*Colors::default_color
])Allocates a copy of the
Path
on the free store, puts a pointer to it onto picture.shapes
, sets itsfill_draw_value
toFILL
, and itsfill_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 theColor
argument 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
Path
on the free store, puts a pointer to the copy onto picture.shapes
, sets itsfill_draw_value
toFILLDRAW
, itsdraw_color
andfill_color
to*
ddraw_color and*
ffill_color, respectively, itsdashed
to ddashed, and itspen
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()
andfill()
, except that both ddraw_color and ffill_color are used.3DLDF's
filldraw()
differs from Metafont's and MetaPost'sfilldraw
commands: In Metafont and MetaPost,filldrawing
is equivalent to filling apath
and then drawing its border using thepen
. Metafont does not have colors. While MetaPost does, itsfilldraw
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.
current_picture
]]])Allocates a copy of the
Path
on the free store, puts a pointer to it on picture.shapes
, sets itsfill_draw_value
toUNDRAW
, and the values of itsdashed
andpen
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 thePath
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.
current_picture
])Allocates a copy of the
Path
on the free store, puts a pointer to it on picture.shapes
and sets itsfill_draw_value
toUNFILL
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.
*Colors::background_color
, [string ddashed = "", [string ppen = "", [Picture& picture = current_picture]]]])*Colors::background_color
, [string ddashed = "", [string ppen = ""]]])Allocates a copy of the
Path
on the free store, puts a pointer to it on picture.shapes
, sets itsfill_draw_value
toUNFILLDRAW
, and the values of itsdraw_color
,dashed
, andpen
according to the arguments. While the default for ddraw_color is*Colors::background_color
, any otherColor
can be used, so thatunfilldraw()
can unfill aPath
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 thePath
will be “undrawn” using the pen specified with the ppen argument, or MetaPost'scurrentpen
, if no ppen argument is specified. In addition, thePath
will be drawn using theColor
specified in the ddraw_color argument. Since the default is*Colors::background_color
, thePath
will be “undrawn” unless a differentColor
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.
[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.