NAME

Rinchi::CIGIPP::ShortSymbolControl - Perl extension for the Common Image Generator Interface - Short Symbol Control data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::ShortSymbolControl;
my $ssym_ctl = Rinchi::CIGIPP::ShortSymbolControl->new();

$packet_type = $ssym_ctl->packet_type();
$packet_size = $ssym_ctl->packet_size();
$symbol_ident = $ssym_ctl->symbol_ident(48088);
$inherit_color = $ssym_ctl->inherit_color(Rinchi::CIGIPP->NotInherited);
$flash_control = $ssym_ctl->flash_control(Rinchi::CIGIPP->RestartFlash);
$attach_state = $ssym_ctl->attach_state(Rinchi::CIGIPP->Detach);
$symbol_state = $ssym_ctl->symbol_state(Rinchi::CIGIPP->Hidden);
$attribute_select1 = $ssym_ctl->attribute_select1(Rinchi::CIGIPP->None);
$attribute_select2 = $ssym_ctl->attribute_select2(Rinchi::CIGIPP->None);
$attribute_value1 = $ssym_ctl->attribute_value1(8789);
$attribute_value2 = $ssym_ctl->attribute_value2(27011);

DESCRIPTION

The Short Symbol Control packet is provided as a lower-bandwidth alternative to the Symbol Control packet (CIGI ICD Section 4.1.33). It can be used when manipulation of only one or two symbol attributes of a symbol are necessary.

This packet allows for up to two symbol attributes to be modified. The attributes are specified by the Attribute Select 1 and Attribute Select 2 attributes. The values of these attributes determine what data types are used to interpret the Attribute Value 1 and Attribute Value 2 attributes, respectively. A symbol must be defined before the Host sends a Short Symbol Control packet referencing that symbol. Symbols may be predefined by the IG or may be created by the Host sending any one of the symbol definition packets.

Before the Host can send a Short Symbol Control referencing a symbol, the Host must first send a Symbol Control packet referencing that symbol so that all of the symbol's attributes can be set.

EXPORT

None by default.

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

new $ssym_ctl = Rinchi::CIGIPP::ShortSymbolControl->new()

Constructor for Rinchi::ShortSymbolControl.

sub packet_type()

$value = $ssym_ctl->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the Short Symbol Control packet. The value of this attribute must be 35.

sub packet_size()

$value = $ssym_ctl->packet_size();

Data Packet Size.

This attribute indicates the number of bytes in this data packet. The value of this attribute must be 32.

sub symbol_ident([$newValue])

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

Symbol ID.

This attribute specifies the symbol to which this packet is applied. This value must be unique for each active symbol.

sub inherit_color([$newValue])

$value = $ssym_ctl->inherit_color($newValue);

Inherit Color.

This attribute specifies whether this symbol inherits its color from the symbol to which it is attached. If color is inherited, then this symbol's color, including the alpha component, is identical to the current color of the parent symbol. Note that the current color of the parent symbol may be inherited from another symbol.

If Attach State is set to Detach (0), this attribute is ignored.

NotInherited   0
Inherited      1

sub flash_control([$newValue])

$value = $ssym_ctl->flash_control($newValue);

Flash Control.

This attribute specifies whether the flash cycle is continued from its present point or whether it is restarted at the beginning.

This attribute is ignored if either Flash Duty Cycle Percentage or Flash Period is changed. This attribute may also be ignored if Flash Duty Cycle Percentage is set to 0 or 100.

ContinueFlash   0
RestartFlash    1

sub attach_state([$newValue])

$value = $ssym_ctl->attach_state($newValue);

Attach State.

This attribute specifies whether the symbol should be attached as a child to a parent symbol.

If this attribute is set to Detach (0), then the symbol becomes or remains a top-level (non-child) symbol. The Parent Symbol attribute is ignored. The U Position, V Position, and Rotation attributes specify the symbol's position and rotation relative to the symbol surface's local coordinate system (see Section 3.4.5.1). If this attribute is set to Attach (1), then the symbol becomes or remains attached to the symbol specified by the Parent Symbol ID attribute. The U Position, V Position, and Rotation attributes specify the symbol's position and rotation relative to the parent symbol's local coordinate system (see Section 3.4.5.2). The attach state of a symbol may be changed at any time. The attachment or detachment takes place immediately and remains in effect until changed with another Symbol Control packet or Short Symbol Control packet.

Detach   0
Attach   1

sub symbol_state([$newValue])

$value = $ssym_ctl->symbol_state($newValue);

Symbol State.

This attribute specifies whether the symbol should be hidden, visible, or destroyed. This attribute may be set to one of the following values:

Hidden – The symbol is hidden from view; however, it can be positioned, rotated, and scaled. It can also be attached to another symbol as a child. It can also be used as a parent by other symbols, although any children are also hidden. Visible – The symbol is drawn on the surface. It can be positioned, rotated, and scaled. It can also be attached to another symbol as a child. It can also be used as a parent by other symbols.

Destroyed – The symbol is deleted and any system resources are freed. Any children are also destroyed. All other attributes in this packet are ignored.

Note: Although the Symbol Control packet supports destruction of symbols, it is recommended that the Short Symbol Control packet be used for this purpose since all other attributes are ignored.

Hidden      0
Visible     1
Destroyed   2

sub attribute_select1([$newValue])

$value = $ssym_ctl->attribute_select1($newValue);

Attribute Select 1.

This attribute identifies the attribute whose value is specified in the Attribute Value 1 field.

If this attribute is set to None (0), then Attribute Value 1 is ignored.

None                0
SurfaceIdent        1
ParentSymbolIdent   2
Layer               3
FlashDutyCycle      4
FlashPeriod         5
PositionU           6
PositionV           7
Rotation            8
Color               9
ScaleU              10
ScaleV              11

sub attribute_select2([$newValue])

$value = $ssym_ctl->attribute_select2($newValue);

Attribute Select 2.

This attribute identifies the attribute whose value is specified in the Attribute Value 2 field.

If this attribute is set to None (0), then Attribute Value 2 is ignored.

None                0
SurfaceIdent        1
ParentSymbolIdent   2
Layer               3
FlashDutyCycle      4
FlashPeriod         5
PositionU           6
PositionV           7
Rotation            8
Color               9
ScaleU              10
ScaleV              11

sub attribute_value1([$newValue])

$value = $ssym_ctl->attribute_value1($newValue);

Attribute Value 1.

This attribute specifies the value of the attribute identified by the Attribute Select 1 field.

If Attribute Select 1 is set to Surface ID (1), Parent Symbol ID (2), Layer (3), or Flash Duty Cycle Percentage (4), then Attribute Value 1 is treated as a 32-bit integer.

If Attribute Select 1 is set to Flash Period (5), Position U (6), Position V (7), Rotation (8), Scale V (10), or Scale V (11), then Attribute Value 1 is treated as a 32-bit single-precision floating-point number.

If Attribute Select 1 is Color (9), then Attribute Value 1 is treated as four 8-bit integers specifying each of the four color components. The most significant byte specifies the red component, followed by the blue component, then green, and finally alpha.

Regardless of the attribute, the IG will byte-swap this attribute as a 32-bit value if byte-swapping is required.

sub attribute_value2([$newValue])

$value = $ssym_ctl->attribute_value2($newValue);

Attribute Value 2.

This attribute specifies the value of the attribute identified by the Attribute Select 2 field.

If Attribute Select 2 is set to Surface ID (1), Parent Symbol ID (2), Layer (3), or Flash Duty Cycle Percentage (4), then Attribute Value 2 is treated as a 32-bit integer.

If Attribute Select 2 is set to Flash Period (5), Position U (6), Position V (7), Rotation (8), Scale V (10), or Scale V (11), then Attribute Value 2 is treated as a 32-bit single-precision floating-point number.

If Attribute Select 2 is Color (9), then Attribute Value 2 is treated as four 8-bit integers specifying each of the four color components. The most significant byte specifies the red component, followed by the blue component, then green, and finally alpha.

Regardless of the attribute, the IG will byte-swap this attribute as a 32-bit value if byte-swapping is required.

sub pack()

$value = $ssym_ctl->pack();

Returns the packed data packet.

sub unpack()

$value = $ssym_ctl->unpack();

Unpacks the packed data packet.

sub byte_swap()

$obj_name->byte_swap();

Byte swaps the packed data packet.

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.