NAME

Rinchi::CIGIPP::SymbolLineDefinition - Perl extension for the Common Image Generator Interface - Symbol Line Definition data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::SymbolLineDefinition;
my $sym_line = Rinchi::CIGIPP::SymbolLineDefinition->new();

$packet_type = $sym_line->packet_type();
$packet_size = $sym_line->packet_size(191);
$symbol_ident = $sym_line->symbol_ident(19346);
$primitive_type = $sym_line->primitive_type(Rinchi::CIGIPP->Point);
$stipple_pattern = $sym_line->stipple_pattern(36348);
$line_width = $sym_line->line_width(49.086);
$stipple_pattern_length = $sym_line->stipple_pattern_length(16.425);

my $vertex0 = Rinchi::CIGIPP::SymbolVertex->new();
$sym_line->vertex(0, $vertex0);
$vertex0->vertex_u(0.0);
$vertex0->vertex_v(0.0);

my $vertex1 = Rinchi::CIGIPP::SymbolVertex->new();
$sym_line->vertex(1, $vertex1);
$vertex1->vertex_u(10.0);
$vertex1->vertex_v(0.0);

my $vertex2 = Rinchi::CIGIPP::SymbolVertex->new();
$sym_line->vertex(2, $vertex2);
$vertex2->vertex_u(10.0);
$vertex2->vertex_v(10.0);

my $vertex3 = Rinchi::CIGIPP::SymbolVertex->new();
$sym_line->vertex(3, $vertex3);
$vertex3->vertex_u(20.0);
$vertex3->vertex_v(10.0);

DESCRIPTION

The Symbol Line Definition packet is used to define a set of line segments or points. This packet can be used to create points, lines, a line strip, a line loop, triangles, a triangle strip, or a triangle fan. Note that this section includes all of these primitives when referring to "line symbols."

Each line symbol is identified by a Symbol ID value that is unique from all other symbols (including text and circle symbols). Every symbol must be created independently with its own unique Symbol ID, even if two or more symbols are visually identical.

Once a Symbol Line Definition packet describing a circle or composite symbol is sent to the IG, the definition of that symbol will not change. If any Symbol Text Definition, Symbol Circle Definition, Symbol Line Definition, or Symbol Clone packet specifying the same Symbol ID is then received, the existing symbol will be destroyed along with any children and a new symbol will be created using the new definition packet.

Every line symbol is defined as an ordered set of zero or more points. Each point is defined with respect to the symbol's 2D coordinate system (see CIGI ICD Section 3.4.5.2) by a pair of coordinates specified in the Vertex U and Vertex V attributes

The method and order by which the points are connected is determined by the Primitive Type attribute.

The pen attributes of each line comprising a line symbol are defined by the Line Width, Stipple Pattern, and Stipple Pattern Length attributes.

Line Width specifies the thickness of the line in scaled symbol surface units. Note that if the surface's horizontal and vertical units are not equal in size, then horizontal, diagonal, and vertical lines will not appear to be the same thickness. The Stipple Pattern attribute defines a bit mask to be applied to the line: if a bit is set (1) then the section of the line corresponding to that bit will be drawn; if the bit is cleared (0) then the corresponding section will not be drawn. If the value of this attribute is 0xFFFF, then the line is solid.

The length of each section is equal to 1/32 of the length specified by the Stipple Pattern Length attribute. This attribute defines the length of the stipple pattern in terms of scaled symbol surface units. If the curved line is longer than the stipple pattern length, then the pattern is repeated.

The pen attributes are ignored for triangles, triangle strips, and triangle fans.

EXPORT

None by default.

#==============================================================================

new $sym_line = Rinchi::CIGIPP::SymbolLineDefinition->new()

Constructor for Rinchi::SymbolLineDefinition.

sub packet_type()

$value = $sym_line->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the Symbol Line Definition packet. The value of this attribute must be 32.

sub packet_size([$newValue])

$value = $sym_line->packet_size($newValue);

Data Packet Size.

This attribute indicates the number of bytes in this data packet. The value of this attribute must be an even multiple of 8 ranging from 16 to 248.

sub symbol_ident([$newValue])

$value = $sym_line->symbol_ident($newValue);

Symbol ID.

This attribute specifies the identifier of the symbol that is being defined.

This identifier must be unique among all existing symbols. If a symbol with the specified identifier already exists, then that symbol and any children will be destroyed and a new symbol created.

sub primitive_type([$newValue])

$value = $sym_line->primitive_type($newValue);

Primitive Type.

This attribute specifies the type of point or line primitive used in this symbol. The possible primitives are described in enumeration LinePrimitiveType.

Point           0
Line            1
LineStrip       2
LineLoop        3
Triangle        4
TriangleStrip   5
TriangleFan     6

sub stipple_pattern([$newValue])

$value = $sym_line->stipple_pattern($newValue);

Stipple Pattern.This attribute specifies the dash pattern used when drawing lines. Each line is divided into sections that are 1/32 of the length specified by the Stipple Pattern Length attribute. The stipple pattern is a bit mask that is used when drawing the sections. If a bit is set (1) then section corresponding to that bit will be drawn; if the bit is cleared (0) then the corresponding section will not be drawn.

If the value of this attribute is 0xFFFF, then the line will be solid.

If the line is longer than the stipple pattern length, the pattern is repeated.

This value is ignored if the Primitive Type attribute is set to Point (0), Triangle (4), Triangle Strip (5), or Triangle Fan (6).

sub line_width([$newValue])

$value = $sym_line->line_width($newValue);

Line Width.

For point primitives, this attribute specifies the diameter of each point in the symbol.

For line, line strip, and line loop primitives, this attribute specifies the thickness of each line in the symbol.

The value of this attribute is measured in symbol surface units and will be scaled if the symbol is scaled (see CIGI ICD Section 3.4.5.2).

Note that if the symbol surface's horizontal and vertical units are not the same size, then horizontal, diagonal, and vertical lines will not appear to be the same thickness.

This value is ignored if the Primitive Type attribute is set to Triangle (4), Triangle Strip (5), or Triangle Fan (6).

sub stipple_pattern_length([$newValue])

$value = $sym_line->stipple_pattern_length($newValue);

Stipple Pattern Length.

This attribute specifies the length of one complete repetition of the stipple pattern. This length is measured in symbol surface units and will be scaled if the symbol is scaled (see CIGI ICD Section 3.4.5.2).

If a line is longer than the stipple pattern length, then the pattern is repeated along that line.

This attribute is ignored if the Drawing Style attribute is set to Fill (1).

sub vertex($index,[$newValue])

$value = $sym_line->vertex($index,$newValue);

Vertex Array.

sub pack()

$value = $sym_line->pack();

Returns the packed data packet.

sub unpack()

$value = $sym_line->unpack();

Unpacks the packed data packet.

sub byte_swap()

$obj_name->byte_swap();

Byte swaps the packed data packet.

new $vertex = Rinchi::CIGIPP::SymbolVertex->new()

Constructor for Rinchi::SymbolVertex.

sub vertex_u([$newValue])

$value = $vertex->vertex_u($newValue);

Vertex U.

This attribute specifies the u position of a vertex with respect to the symbol's local coordinate system. This position is measured in scaled symbol surface units (see CIGI ICD Section 3.4.5.2).

sub vertex_v([$newValue])

$value = $vertex->vertex_v($newValue);

Vertex V.

This attribute specifies the v position of a vertex with respect to the symbol's local coordinate system. This position is measured in scaled symbol surface units (see CIGI ICD Section 3.4.5.2).

sub pack()

$value = $vertex->pack();

Returns the packed data packet.

sub unpack()

$value = $vertex->unpack();

Unpacks the packed data packet.

sub byte_swap()

$vertex->byte_swap();

Byte swaps the packed circle data.

SEE ALSO

Refer the the Common Image Generator Interface ICD which may be had at this URL: http://cigi.sourceforge.net/specification.php

AUTHOR

Brian M. Ames, <bmames@apk.net>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Brian M. Ames

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6 or, at your option, any later version of Perl 5 you may have available.