Node: Picture Output Functions, Previous: Picture Output Namespaces, Up: Outputting Pictures


Output Functions

void output (const Focus& f, [const unsigned short projection = Projections::PERSP, [real factor = 1, [const unsigned short sort_value = Sorting::MAX_Z, [const bool do_warnings = true, [const real min_x_proj = -40, [const real max_x_proj = 40, [const real min_y_proj = -40, [const real max_y_proj = 40, [const real min_z_proj = -40, [const real max_z_proj = 40]]]]]]]]]]) Function
void output ([const unsigned short projection = Projections::PERSP, [real factor = 1, [const unsigned short sort_value = Sorting::MAX_Z, [const bool do_warnings = true, [const real min_x_proj = -40, [const real max_x_proj = 40, [const real min_y_proj = -40, [const real max_y_proj = 40, [const real min_z_proj = -40, [const real max_z_proj = 40]]]]]]]]]]) Function
These functions create a two-dimensional projection of the objects on the Picture and write MetaPost code to out_stream for drawing it.

The arguments:

const Focus& f
The Focus used for projection, also known as the center of projection, or the camera. This argument is used in the first version only. The second version, without a const Focus& f argument, merely calls the first version and passes it the global variable default_focus as its first argument, so default_focus is effectively the default for f. Defining two versions in this way makes it possible to call output() with projection as its first (and possibly only) argument. If instead, f were an optional argument with default_focus as its default, this wouldn't have been possible. It also wouldn't be possible to have f have a default in the first version, and to retain the second version, because the compiler wouldn't be able to resolve a call to output() with no arguments.
const unsigned short projection
Default: Projections::PERSP. The type of projection. Valid values are const unsigned shorts defined in namespace Projections (see Namespace Projections):
PERSP for the perspective projection,
PARALLEL_X_Y for parallel projection onto the x-y plane,
PARALLEL_X_Z for parallel projection onto the x-z plane, and
PARALLEL_Z_Y for parallel projection onto the z-y plane. %% !! TO DO: I plan to add isometric and axionometric projections soon.
real factor
Default: 1. Passed from output() to extract() and from there to project(). The world_coordinates of the Points that are projected are multiplied by factor, which enlarges or shrinks the projected image without altering the Picture itself. factor is probably most useful for parallel projections, where the Focus f isn't used; with a perspective projection, the parameters of the Focus can be used to influence the size of the projected image.
const unsigned short sort_value
Default: Sorting::MAX_Z. The value used should be one of the constants defined in namespace Sorting, See Namespace Sorting, above. If MAX_Z (the default) is used, the Shapes on the Picture are sorted according to the maximum z-value of the projective_extremes of the Points belonging to the Shape. If MIN_Z is used, they are sorted according to the minimum z-value, and if MEAN_Z is used, they are sorted according to the mean of the maximum and minimum z-values. If NO_SORT is used, the Shapes are output in the order in which they were put onto the Picture.

The surface hiding algorithm implemented in 3DLDF is quite primitive, and doesn't always work right. For Shapes that intersect, it can't work right. I plan to work on improving the surface hiding algorithm soon. This is not a trivial problem. To solve it properly, each Shape on a Picture must be tested for intersection with every other Shape on the Picture. If two or more Shapes intersect, they must be broken up into smaller objects until there are no more intersections. I don't expect to have a proper solution soon, but I expect that I will be able to make some improvements. See Surface Hiding.

const bool do_warnings
Default: true. If true, output() issues warnings to stderr (standard error output) if a Shape cannot be output because it lies outside the limits set by the following arguments. Sometimes, a user may only want to project a portion of a Picture, in which case such warnings would not be helpful. In this case, do_warnings should be false.
const real min_x_proj
Default: -40. The minimum x-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[0] of any Point on a Shape is less than min_x_proj, the Shape will not be projected at all.
const real max_x_proj
Default: 40. The maximum x-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[0] of any Point on a Shape is greater than max_x_proj, the Shape will not be projected at all.
const real min_y_proj
Default: -40. The minimum y-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[1] of any Point on a Shape is less than min_y_proj, the Shape will not be projected at all.
const real max_y_proj
Default: 40. The maximum y-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[1] of any Point on a Shape is greater than max_y_proj, the Shape will not be projected at all.
const real min_z_proj
Default: -40. The minimum z-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[2] of any Point on a Shape is less than min_z_proj, the Shape will not be projected at all.
const real max_z_proj
Default: 40. The maximum z-coordinate of the projection of a Shape such that the Shape can be output. If projective_coordinates[2] of any Point on a Shape is greater than max_z_proj, the Shape will not be projected at all.

void suppress_labels (void) Function
Suppresses output of the Labels on a Picture when output() is called. This can be useful when a Picture is output, transformed, and output again, one or more times, in a single figure. Usually, it will not be desirable to have the Labels output more than once.

In [next figure] , current_picture is output three times, but the Labels on it are only output once. 

          Ellipse e(origin, 3, 5);
          e.label();
          e.draw();
          Point pt0(-3);
          Point pt1(3);
          pt0.draw(pt1);
          Point pt2(0, 0, -4);
          Point pt3(0, 0, 4);
          pt2.draw(pt3);
          pt0.dotlabel("0", "lft");
          pt1.dotlabel("1", "rt");
          pt2.dotlabel("2", "bot");
          pt3.dotlabel("3");
          current_picture.output(Projections::PARALLEL_X_Z);
          current_picture.rotate(0, 60);
          current_picture.suppress_labels();
          current_picture.output(Projections::PARALLEL_X_Z);
          current_picture.rotate(0, 60);
          current_picture.output(Projections::PARALLEL_X_Z);


[Figure 79. Not displayed.]

Fig. 79.

void unsuppress_labels (void) Inline function
Sets do_labels to true. If a Picture contains Labels, unsuppress_labels() ensures that they will be output, when Picture::output() is called, so long as there is no intervening call to suppress_labels() or kill_labels().