Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Define_Line_Style

Functions

void Define_Line_Style (const char *name, const char *definition)
 Allows the user to create a custom line style using a combination of lines, blanks, glyphs, and attributes. More...
 
void UnDefine_Line_Style (const char *name)
 Removes a custom line style established by a previous call to Define_Line_Style(). More...
 

Detailed Description

Function Documentation

void Define_Line_Style ( const char *  name,
const char *  definition 
)

Allows the user to create a custom line style using a combination of lines, blanks, glyphs, and attributes.

Parameters
nameName of the custom line style.
definitionLine style definition described below.

DETAILS

Define_Line_Style allows users to create custom line styles using combinations of user-defined glyphs and a number of pre-arranged glyphs, lines, and modifiers. These are the basic ingredients for Parallels, which in turn make up the style definition:

    definition = "[ Parallel ] [, Parallel ] [, Parallel ] [, Transformed ]"

Parallels

The definition string, or line style definition, is a comma-separated list of "parallels" that have optional parameters and/or modifiers, as follows:

    Parallel = [Caps-n-Arrows]
               [+/-ddd gsu [fixed] offset,]
               [+ddd gsu [fixed] weight,] [fit,]
               [segmented,] [,absolute[weight|length]] [join,]
               [Element] [,Element]...

  • Caps-n-Arrows See section below on Caps and Arrows.
  • +-ddd gsu Generic size units (.05 oru, 12 pixel, etc). For valid options see Set_Text_Font().
  • "fit = center / stretch" Specifies the method by which line patterns can be made to fit evenly between endpoints. The first method, "fit = center", attempts to center the pattern between endpoints so that the first element occurs both at the beginning and the end. This method assumes that the first element makes up at least half of the total length of all elements combined. If this assumption is not met, the method loses effectiveness. The second method, "fit = stretch", stretches the pattern between two line segments by making adjustements to the length of the elements and therefore honors the endpoints at the expense of the pattern's definition.
  • "fixed" If the element is a glyph, it will have a fixed orientation and will not be affected by the direction of the underlying line.
  • offset Defines the distance between parallel lines. This modifier should immediately follow the "parallel" setting. If fixed, then the local segment's line weight does not scale the offset.
  • weight Sets line weight for a parallel. This should immediately follow the parallel setting. If fixed, then the local segment's line weight does not scale the weight.
  • "segmented" Makes the pattern reset for each segment of a polyline
  • "absolute [weight | length]" Prevents device- or driver-dependent scaling from affecting element attributes that have been specified in pixels. In other words, "absolute" pixel sizes, weights, etc. will be honored. Specifying "absolute" will set "absolute length" and "absolute weight".
  • "join" Makes the current parallel follow the visibility rules of middle glyphs. This can be useful for drawing arcs and curves.
  • "parallel" Signifies the beginning of a new parallel within this line style.

Elements

In the examples above, "dash" is an Element that is modified by the properties of the parallel. Elements consist of a shape (line or glyph) with a modifier (length or size), as follows:

    Element = [+ddd gsu] dash  or
              [+ddd gsu] blank or
              [+ddd gsu] contrast or
              [+ddd gsu] glyph_name [,inline|inset] [,mirror] [,rotation=x] [fixed]

  • +ddd gsu Length or size of the element in generic size units (.05 oru, 12 pixel, 20%, etc). For valid gsu options see Set_Text_Font().
  • "blank" An invisible line. If no length specified then the blank will be infinite and stretchable.
  • "contrast" A visible line colored according to the current line-contrast or edge-contrast color settings (see Set_Color()). If no length specified then the contrast will be infinite and stretchable.
  • "dash" A visible line. If no length specified then the dash will be infinite and stretchable. The color of the dash will be specified by the current line/edge settings.
  • glyph_name A user-defined glyph or build-in marker. If no size is specified, the glyph uses the current marker size setting. The following settings are specific to glyphs:

  • "inline" - The line pattern is resumed after leaving space for the glyph
  • "inset" - The line pattern is snipped to the glyph's nominal radius
  • "mirror" - Flips the glyph about its X-axis before applying any rotation element.
  • "rotation = x" - The additional angle in degrees the glyph is rotated about the line vector.
  • "fixed" - The angle of rotation of the glyph will not be affected by the line vector.
  • "weighted = [+ddd gsu]" - This sets the line weight for the strokes used to draw the glyph. For example, "arrow = X, weighted=3 pixels" will draw a solid line with a heavy X at each end.
  • Caps and Arrows

    The endpoints of custom linestyles may be controlled with a number of settings that come first in the definition of a parallel. Individual parallels in a definition can have unique cap and arrow settings. See the examples in the NOTES section for usage.

    • start cap = glyph_name The glyph to be used at the start of the polyline
    • end cap = glyph_name The glyph to be used at the end of the polyline
    • caps = glyph_name The glyph to be used for both the start and end caps.
    • start arrow = glyph_name The glyph to be used at the start of the polyline
    • end arrow = glyph_name The glyph to be used at the end of the polyline. This glyph will be rotated by an additional 180 degrees.
    • arrows = glyph_name The glyph to be used for both the start and end of the line.
    • middle = glyph_name The glyph at the mid-point of the polyline line segments.
    • glyph = glyph_name The glyph to be used for the start, end, and middle of the line.

    Transformed Option

    By default, user-defined line styles are screen-oriented (2D space). If the "transformed" key word is used in the style definition, HOOPS will draw the pattern in 3d space. Users can set the orientation vectors for the pattern via the "orientation" setting of Set_Geometry_Options(). The "transformed" setting can only be used on polyline primitives. See example #7 below for usage.

    Please note that since line patterns are projected on an arbitrary plane, transformed line patterns can lead to some surprises. For one, segments of polylines will have non-uniform dash/blank lengths if they are at different angles to the projection plane. This is most noticeable when a blank eats up an entire segment. This is also true for glyph spacing.

    NOTES

    • Custom line styles are local attributes of a segment and inherit as such.
    • When a glyph is applied to a line style, by default it is positioned so that it is perpendicular to the line normal. Additionally, the "hot spot" for the glyph is honored and a "12 O'Clock" orientation is assumed.
    • If a glyph follows another glyph in a line style definition there is an implicit blank the length of the sum of their two radii between them.
    • Pixel-based patterns that will not divide evenly by 16 will draw more slowly under OpenGL than patterns that will divide evenly.

    EXAMPLES

    Example 1: A solid line (actually a dash without blanks) of weight=1 is the default parallel. Therefore the line style resulting from an empty string passed as the definition will be a single, solid line of weight one (1 pixel). However, let's say we want to create the default solid line style with double weight:

        HC_Define_Line_Style
        (
          "solid_line",
          "2 pixel weight,"
          "dash"
        );
    

    Note that the example does not use the world 'parallel' as the first directive in the definition. This is because 'parallel' is implicit at the beginning of a definition.

    Example 2: The double-line version of the above example, with a 20 pixel separation, would look like this:

        HC_Define_Line_Style
        (
          "double_solid_line",
          "2 pixel weight,"
          "dash,"
          "parallel, 20 pixel offset, 2 pixel weight,"
          "dash"
        );
    

    Note that in this example, the second instance of "dash" (the second parallel) must be preceded by "parallel" to identify the beginning of a new parallel, whereas in the first instance this is implied.

    Example 3: The following example creates and sets a scalable line pattern that alternates between a line segment, a blank, and a line segment in the segment's contrast line color:

        HC_Define_Line_Style
        (
          "myLineStyle",
          "0.1 oru dash,"
          "0.1 oru blank,"
          "0.1 oru contrast"
        );
    
        HC_Set_Color ( "lines=red, line contrast=blue");
        HC_Set_Line_Pattern("myLineStyle");
    

    Example 4: Another example creates a line which has arrow heads at either end:

        const char Arrow[] =
        {
          10, 0, 0, -1, 4,
          -10, 0, 0, 10, 10,
          0, -10, 0, -3, 0
        };
    
        HC_Define_Glyph
        (
          "triangle",
          sizeof(Arrow),
          Arrow
        );
    
        HC_Define_Line_Style
        (
          "myLineStyle",
          "arrows = 0.1 oru triangle,"
          "dash"
        );
    
        HC_Set_Line_Pattern("myLineStyle");
    

    Example 5: Using parallels, it is very easy to create a triple-line style:

        HC_Define_Line_Style
        (
          "myLineStyle",
          "dash,"
          "parallel, 0.05 oru offset,"
          "contrast,"
          "parallel, -0.05 oru offset,"
          "contrast"
        );
    
        HC_Set_Color("lines=red, line contrast=blue");
        HC_Set_Line_Pattern("myLineStyle");
    

    Example 6: This example uses the "fixed" setting to force one of the parallels to be always 5 pixels from the center-line, while the other will be affected by the local line weight and consequently be 10 pixels from the center-line.

        HC_Define_Line_Style
        (
          "myLineStyle",
          "dash,"
          "parallel, 5 pixel fixed offset,"
          "contrast,"
          "parallel, -5 pixel offset,"
          "contrast"
        );
    
        HC_Set_Color("lines=red, line contrast=blue");
        HC_Set_Line_Pattern("myLineStyle");
        HC_Set_Line_Weight(2.0);
    

    Example 7: The following example defines a simple pattern that consists of 2 dashed polylines with an offset in 3D space such that both lines lie on a plane defined in Set_Geometry_Options():

        HC_Define_Line_Style("3d_parallel", "dash, parallel, 5 pixel offset, dash, transformed");
    

    RESTRICTIONS

    The names "0" - "9" are reserved for backward compatibility with the hidden line pattern specification however you can use line style names like "00", "10", "21" etc.

    See also
    Define_Glyph, Show_Glyph, Show_Line_Style
    void UnDefine_Line_Style ( const char *  name)

    Removes a custom line style established by a previous call to Define_Line_Style().

    Parameters
    nameName of the custom line style.

    DETAILS

    No additional details. See Define_Line_Style().