NAME

Rinchi::CIGIPP::EntityControl - Perl extension for the Common Image Generator Interface - Entity Control data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::EntityControl;
my $ent_ctl = Rinchi::CIGIPP::EntityControl->new();

$packet_type = $ent_ctl->packet_type();
$packet_size = $ent_ctl->packet_size();
$entity_ident = $ent_ctl->entity_ident(18430);
$ground_clamp = $ent_ctl->ground_clamp(0);
$inherit_alpha = $ent_ctl->inherit_alpha(1);
$collision_detection = $ent_ctl->collision_detection(1);
$attach_state = $ent_ctl->attach_state(Rinchi::CIGIPP->Attach);
$entity_state = $ent_ctl->entity_state(Rinchi::CIGIPP->EntityInactive);
$extrapolation_enable = $ent_ctl->extrapolation_enable(Rinchi::CIGIPP->Disable);
$animation_state = $ent_ctl->animation_state(Rinchi::CIGIPP->Stop);
$animation_loop = $ent_ctl->animation_loop(Rinchi::CIGIPP->Continuous);
$animation_direction = $ent_ctl->animation_direction(Rinchi::CIGIPP->Backward);
$alpha = $ent_ctl->alpha(249);
$entity_type = $ent_ctl->entity_type(54457);
$parent_ident = $ent_ctl->parent_ident(38194);
$roll = $ent_ctl->roll(36.539);
$pitch = $ent_ctl->pitch(15.394);
$yaw = $ent_ctl->yaw(53.214);
$latitude = $ent_ctl->latitude(4.828);
$x_offset = $ent_ctl->x_offset(22.092);
$longitude = $ent_ctl->longitude(33.727);
$y_offset = $ent_ctl->y_offset(71.648);
$altitude = $ent_ctl->altitude(20.674);
$z_offset = $ent_ctl->z_offset(81.962);

DESCRIPTION

The Entity Control packet is used to control position, attitude, and other attributes describing an entity's state. This packet may be applied to any entity in the simulation, including the Ownship.

Each entity is identified by a unique identifier called the Entity ID. When the Host sends an Entity Control packet to the IG, the IG sets the state of the entity object corresponding to the value of the Entity ID attribute. If the specified entity does not exist, the IG will create it.

When the IG creates an entity, it makes a copy of the geometry corresponding to the value of the Entity Type attribute. This copy exists as a unique and independent tree within the scene graph; therefore, any operations that modify an entity's tree (e.g., part articulations) affect only that entity and its children. Entities can be attached to one another in a hierarchical relationship. In such a hierarchy, a child entity's position is specified relative to its parent's coordinate system. The Host needs only to control the parent entity in order to move all lower entities in the hierarchy as a group. No explicit manipulation of a child entity is necessary unless its position and attitude change with respect to its parent.

The Attach State attribute of the Entity Control packet determines whether an entity is attached to a parent. If this attribute is set to Attach (1), the entity is attached to the entity specified by the Parent ID attribute. The Entity State attribute is used to control when an entity is visible and when its geometry is loaded and unloaded. When an entity is created, the Entity State attribute can be set to Active to specify that the entity should be added to the scene as soon as the model geometry is loaded. The entity and any children can be made invisible at any time by setting Entity State to Inactive/Standby. When the entity is no longer needed, Entity State can be set to Destroyed to direct the IG to unload the geometry and free any memory allocated for the entity. Any children attached to the entity are also destroyed. Models can be preloaded to increase the speed at which they can be initially displayed. For example, when an aircraft fires a missile, a new entity would need to be created for that missile. Unless the missile geometry is cached, the IG must load the model from its hard disk. Because of its tremendous speed, the missile might fly a significant distance (and possibly beyond visual range) before the disk I/O can be completed. By preloading the entity, the geometry can already exist in memory and be instantly activated within the scene graph when needed. To accomplish this, the Entity State flag could be set to Inactive/Standby when the missile is created. Later, when the missile is needed, an Entity Control packet for that entity would be sent containing the proper positional data and with the Entity State flag set to Active.

An entity can also be made invisible by setting the Alpha attribute to zero (0). This attribute specifies an alpha value to be applied to the entity's geometry. The Inherit Alpha attribute indicates whether a child entity's alpha value is combined with that of its parent. For example, a missile attached to the wing of an aircraft would typically be made invisible when the aircraft is destroyed, so its Inherit Alpha attribute would be set to Inherited (1). An explosion or similar animation attached to that aircraft, however, would typically linger after the aircraft's destruction, so its Inherit Alpha attribute would be set to Not Inherited (0).

Note that setting the Entity State attribute to Inactive/Standby is not equivalent to setting the Alpha attribute to zero (0). The Entity State attribute enables or disables the entity geometry in the scene graph. The entity would not be included in line of sight and collision testing, nor would any transformations be applied. Any children would also be disabled. The Alpha attribute, on the other hand, merely affects the opacity of the specified entity. The positions of top-level entities (i.e., those entities that are not children) are always specified as a geodetic latitude, longitude, and altitude. The positions of child entities are always specified with respect to the parents' NED body coordinate system.

In certain instances, it is desirable for the IG to "clamp" the entity to the surface of the terrain. This can be used as an alternative to using HOT requests and responses to determine ground elevation and slope below the entity. If the Ground/Ocean Clamp attribute is set to Non-Conformal (1) or Conformal (2), the Altitude attribute specifies an offset above the ground or sea surface height. This is useful for specifying the vertical distance from an automobile's reference point to its wheels, for instance, or from a ship's reference point to its waterline. Similarly, Roll and Pitch specify rotational offsets if ground or ocean clamping is enabled.

The Animation State attribute is used to control the playback state of animation entities. To start the animation sequence, the Host will send an Entity Control packet with its Entity State set to Active and its Animation State attribute to either Play or Resume. The Host may explicitly stop the animation at any time by setting the Animation State to Stop. Setting the attribute to Pause freezes the animation sequence at the current frame. Setting the attribute to Resume in a subsequent frame will resume the animation from its paused state; setting it to Play will play the animation again from its initial state. Setting Animation State to Play during playback will restart the animation. Note that setting the Animation State attribute to Stop will have different effects on different types of animations. Frame-based animations may simply stop, or begin a termination sequence if such a sequence has been defined, at the current frame. Emitter-based animations (e.g, missile trails and particle systems) will stop producing new particles or segments; however, existing particles or segments will continue to decay normally. Stopping an animation does not implicitly remove it from the scene unless the Entity State attribute is set to Inactive/Standby or Destroyed.

If an animation has been built with a limited duration, and if the Animation Loop Mode attribute is set to One-Shot, the animation will stop automatically upon its completion. The IG will indicate this condition by sending an Animation Stop Notification packet to the Host. If the Animation Loop Mode attribute is set to Loop, the animation will immediately restart from the beginning and no Animation Stop Notification packet will be sent.

Once an Entity Control packet describing an entity is sent to the IG, the state of that entity will not change until another Entity Control packet specifying that entity ID is received. For example, packets describing the Ownship and a wingman may be sent every frame to indicate continuous positional changes, while a packet describing an inactive SAM site may be sent once during mission initialization.

EXPORT

None by default.

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

new $ent_ctl = Rinchi::CIGIPP::EntityControl->new()

Constructor for Rinchi::EntityControl.

sub packet_type()

$value = $ent_ctl->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the Entity Control packet. The value of this attribute must be 2.

sub packet_size()

$value = $ent_ctl->packet_size();

Data Packet Size.

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

sub entity_ident([$newValue])

$value = $ent_ctl->entity_ident($newValue);

Entity ID.

This attribute specifies the entity to which this packet will be applied. A value of zero (0) corresponds to the Ownship.

sub ground_clamp([$newValue])

$value = $ent_ctl->ground_clamp($newValue);

Ground/Ocean Clamp.

This attribute specifies whether the entity should be clamped to the ground or water surface. If Attach State is set to Attach (1), this attribute is ignored.

No Clamp – The entity is not clamped. The Altitude attribute specifies the entity's height above Mean Sea Level. The Pitch and Roll attributes specify the entity's pitch and roll relative to the geodetic reference plane.

Non-Conformal – The entity is clamped. The Altitude attribute specifies an offset above the terrain or sea level. The Pitch and Roll attributes specify the entity's pitch and roll relative to the geodetic reference plane. Conformal – The entity is clamped and its attitude conforms to the terrain. The Altitude attribute specifies an offset above the terrain or sea level. The Pitch and Roll attributes specify the entity's pitch and roll relative to the slope of the terrain or water.

sub inherit_alpha([$newValue])

$value = $ent_ctl->inherit_alpha($newValue);

Inherit Alpha

This attribute specifies whether the entity's alpha is combined with the apparent alpha of its parent.

Note that a change in an entity's alpha affects the entities below it in the hierarchy if those entities inherit their parents' alphas.

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

sub collision_detection_enable([$newValue])

$value = $ent_ctl->collision_detection_enable($newValue);

Collision Detection Enable.

This attribute determines whether any collision detection segments and volumes associated with this entity are used as the source in collision testing.

If this attribute is set to Enabled (1), every frame each collision detection segment is tested for intersections with polygons not associated with this entity and each collision detection volume is tested pair-wise with every other volume that is not associated with the entity.

If this attribute is set to Disabled (0), any collision detection segments defined for the entity are ignored and any collision detection volumes are only tested (as the destination) against volumes defined for entities whose collision detection is enabled.

Disable   0
Enable    1

sub attach_state([$newValue])

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

Attach State.

This attribute specifies whether the entity should be attached as a child to a parent. If this attribute is set to Detach (0), the entity becomes or remains a top-level (non-child) entity. The Parent ID attribute is ignored. The Yaw, Pitch, Roll, Latitude, Longitude, and Altitude attributes all specify the entity's position relative to the geodetic coordinate system.

If this attribute is set to Attach (1), the entity becomes or remains attached to the entity specified by the Parent ID attribute. The parent must already exist, having been created in a prior frame or earlier in the current frame. The Yaw, Pitch, Roll, X Offset, Y Offset, and Z Offset attributes all specify the entity's position relative to the parent's coordinate system.

This attribute may be changed for a given entity at any time. The attachment or detachment takes place immediately and remains in effect until changed with another Entity Control packet.

Detach   0
Attach   1

sub entity_state([$newValue])

$value = $ent_ctl->entity_state($newValue);

Entity State.

This attribute specifies whether the entity should be active or destroyed. It may be set to one of the following values:

Inactive/Standby – The entity is loaded, but its tree is not enabled in the scene graph. The entity is invisible, and no transformations are applied. Additionally, the entity is excluded from line of sight and collision testing.

Active – The entity's tree is enabled in the scene graph. Transformations are applied to the entity and it is included in line of sight and collision testing. Destroyed – The entity's tree is removed from the scene graph. Any children are also destroyed. All other attributes in this packet are ignored.

EntityInactive    0
EntityStandby     1
EntityActive      1
EntityDestroyed   2

sub extrapolation_enable([$newValue])

$value = $ent_ctl->extrapolation_enable($newValue);

Linear Extrapolation/Interpolation Enable

This attribute specifies whether the entity's motion may be smoothed by extrapolation or interpolation algorithms on the IG. Such smoothing may be useful for compensating for lost CIGI messages, irregular frame rates, asynchronous operation, etc.

If extrapolation or interpolation is disabled globally through the Extrapolation/Interpolation Enable flag of the IG Control packet, then smoothing will not be applied to the entity.

Disable   0
Enable    1

sub animation_state([$newValue])

$value = $ent_ctl->animation_state($newValue);

Animation State.

This attribute specifies the state of an animation. This attribute applies only when the value of the Entity Type attribute corresponds to an animation.

Stop - Stops the animation sequence. If the animation has a termination sequence or decay behavior, the animation will switch to that behavior. Has no effect if the animation is currently stopped.

Pause - Pauses playback of an animation. The entity's geometry will remain visible, provided Entity State is set to Active.

Play - Begins or restarts playback from the first animation frame.

Continue - Continues a playing animation from the current frame of the animation sequence. If the animation is paused, playback is resumed from the current frame. If the animation is stopped, playback is restarted from the first frame of the sequence.

Stop       0
Pause      1
Play       2
Continue   3

sub animation_loop([$newValue])

$value = $ent_ctl->animation_loop($newValue);

Animation Loop Mode.

This attribute specifies whether an animation should be a one-shot (i.e., should play once and stop) or should loop continuously.

OneShot      0
Continuous   1

sub animation_direction([$newValue])

$value = $ent_ctl->animation_direction($newValue);

Animation Direction.

This attribute specifies the direction in which an animation plays. This attribute applies only when the value of the Entity Type attribute corresponds to an animation.

Forward    0
Backward   1

sub alpha([$newValue])

$value = $ent_ctl->alpha($newValue);

Alpha.

This attribute specifies the explicit alpha to be applied to the entity's geometry. A value of zero (0) corresponds to fully transparent; a value of 255 corresponds to fully opaque.

sub entity_type([$newValue])

$value = $ent_ctl->entity_type($newValue);

Entity Type.

This attribute specifies the type of the entity. A value of zero (0) indicates a “null” type with no associated geometry. Such an entity might be used to represent the Ownship or a floating camera.

When changing entity types, the Host should first delete the entity by setting the Entity State attribute to Deactivate (2) and then recreate the entity and any children during a subsequent frame. If the specified type is undefined, the data packet will be disregarded.

sub parent_ident([$newValue])

$value = $ent_ctl->parent_ident($newValue);

Parent ID.

This attribute specifies the parent for the entity. If the Attach State attribute is set to Detach (0), this attribute is ignored.

The value of this attribute may be changed without first detaching the entity from its existing parent.If the specified parent entity is invalid, no change in the attachment will be made.

sub roll([$newValue])

$value = $ent_ctl->roll($newValue);

Roll.

This attribute specifies the roll angle of the entity.

For child entities, roll is measured from the entity's reference plane after yaw and pitch rotations have been applied.

For top-level entities for which Ground/Ocean Clamp is set to No Clamp (0) or Non-Conformal (1), this angle is measured from the reference plane.

For top-level entities for which Ground/Ocean Clamp is enabled, this angle specifies an angular offset from the terrain surface polygon's orientation.

sub pitch([$newValue])

$value = $ent_ctl->pitch($newValue);

Pitch.

This attribute specifies the pitch angle of the entity.

For child entities, pitch is measured with respect to the entity's reference plane after the yaw rotation has been applied.

For top-level entities for which Ground/Ocean Clamp is set to No Clamp (0) or Non-Conformal (1), this angle is measured from the reference plane.

For top-level entities for which Ground/Ocean Clamp is enabled, this angle specifies an angular offset from the terrain surface polygon's orientation.

sub yaw([$newValue])

$value = $ent_ctl->yaw($newValue);

Yaw.

For child entities, this attribute specifies a rotation about the child entity's Z axis when the child's X axis is parallel to the parent's X axis.

For top-level (non-child) entities, this attribute specifies the instantaneous heading of the entity. This angle is measured from a line parallel to the Prime Meridian.

sub latitude([$newValue])

$value = $ent_ctl->latitude($newValue);

Latitude.

For top-level (non-child) entities, this attribute specifies the entity's geodetic latitude.

sub x_offset([$newValue])

$value = $ent_ctl->x_offset($newValue);

X Offset.

For child entities, this attribute represents the distance in meters from the parent's reference point along its parent's X axis.

sub longitude([$newValue])

$value = $ent_ctl->longitude($newValue);

Longitude.

For top-level (non-child) entities, this attribute specifies the entity's geodetic longitude.

sub y_offset([$newValue])

$value = $ent_ctl->y_offset($newValue);

Y Offset.

For child entities, this attribute represents the distance in meters from the parent's reference point along its parent's Y axis.

sub altitude([$newValue])

$value = $ent_ctl->altitude($newValue);

Altitude.

For top-level (non-child) entities, this attribute specifies the entity's geodetic altitude.

sub z_offset([$newValue])

$value = $ent_ctl->z_offset($newValue);

Z Offset.

For child entities, this attribute represents the distance in meters from the parent's reference point along its parent's Z axis.

sub pack()

$value = $ent_ctl->pack();

Returns the packed data packet.

sub unpack()

$value = $ent_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.