NAME

Rinchi::CIGIPP::StartOfFrame - Perl extension for the Common Image Generator Interface - Start Of Frame data packet. data packet. =head1 SYNOPSIS

use Rinchi::CIGIPP::StartOfFrame;
my $start_of_frame = Rinchi::CIGIPP::StartOfFrame->new();

$packet_type = $start_of_frame->packet_type();
$packet_size = $start_of_frame->packet_size();
$major_version = $start_of_frame->major_version();
$database_number = $start_of_frame->database_number(65);
$ig_status = $start_of_frame->ig_status(190);
$minor_version = $start_of_frame->minor_version();
$earth_reference_model = $start_of_frame->earth_reference_model(Rinchi::CIGIPP->HostDefined);
$timestamp_valid = $start_of_frame->timestamp_valid(Rinchi::CIGIPP->Invalid);
$ig_mode = $start_of_frame->ig_mode(Rinchi::CIGIPP->Reset);
$magic_number = $start_of_frame->magic_number();
$ig_frame_number = $start_of_frame->ig_frame_number(44786);
$timestamp = $start_of_frame->timestamp(37374);
$last_host_frame_number = $start_of_frame->last_host_frame_number(55338);

DESCRIPTION

The Start of Frame packet is used to signal the beginning of a new frame. Every IG-to-Host message must contain exactly one Start of Frame packet. This packet must be the first packet in the message.

EXPORT

None by default.

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

new $start_of_frame = Rinchi::CIGIPP::StartOfFrame->new()

Constructor for Rinchi::StartOfFrame.

sub packet_type()

$value = $start_of_frame->packet_type();

Data Packet Identifier.

This attribute identifies this data packet as the Start of Frame packet. The value of this attribute must be 101.

sub packet_size()

$value = $start_of_frame->packet_size();

Data Packet Size.

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

sub major_version()

$value = $start_of_frame->major_version();

Major Version.

This attribute indicates the major version of the CIGI interface that is currently being used by the IG. The Host can use this number to determine concurrency. The value of this attribute must be 3.

sub database_number([$newValue])

$value = $start_of_frame->database_number($newValue);

Database Number.

This attribute is used to indicate to the Host which database is currently in use and if that database is being loaded into primary memory.

The Host will set the Database Number attribute of the IG Control packet to direct the IG to begin loading the corresponding database. The IG will indicate that the database is being loaded by negating the value and placing it in the Database Number attribute of the Start of Frame packet. The Host will then acknowledge this change by setting the Database Number attribute of the IG Control packet to zero (0).

When the database load is complete and after the Host has acknowledged the database change, the IG will set this attribute to the positive database number. The IG can now be considered mission-ready.

If the Host requests a database that does not exist or cannot be loaded, the IG will set this attribute to -128.

Zero (0) is used to indicate that the IG controls the database loading.

sub ig_status([$newValue])

$value = $start_of_frame->ig_status($newValue);

IG Status Code.

This attribute indicates the error status of the IG.

Error codes are IG-specific. Refer to the appropriate IG documentation for a list of error codes.

If more than one error is detected, the IG will report the one with the highest priority. If additional error reporting must be performed, the IG should be placed in Debug mode via the IG Control packet's IG Mode attribute or the IG's user interface.

sub minor_version()

$value = $start_of_frame->minor_version();

Minor Version.

This attribute indicates the minor version of the CIGI interface that is currently being used by the IG. The Host can use this number to determine concurrency.

sub earth_reference_model([$newValue])

$value = $start_of_frame->earth_reference_model($newValue);

Earth Reference Model.

This attribute indicates whether the IG is using a custom (Host-defined) Earth Reference Model (ERM) or the default WGS 84 reference ellipsoid for coordinate conversion calculations. Host-defined ERMs are defined with the Earth Reference Model Definition packet (see Section 4.1.19).

If the Host defines an ERM that the IG cannot support, this value is set to WGS 84 (0). In such cases, the Host must redefine the ERM or use the WGS 84 reference ellipsoid.

WGS84         0
HostDefined   1

sub timestamp_valid([$newValue])

$value = $start_of_frame->timestamp_valid($newValue);

Timestamp Valid.

This attribute indicates whether the Timestamp attribute contains a valid value.

Invalid   0
Valid     1

sub ig_mode([$newValue])

$value = $start_of_frame->ig_mode($newValue);

IG Mode.

This attribute indicates the current IG mode. It may be one of the following values: Reset/Standby – This is the IG's initial state upon start-up. When set to this mode, the IG will initialize/reinitialize the simulation. All entities that were instantiated during a previous mission will be destroyed. All environmental properties, views, components, and sensors will revert to their default settings. Any Host-defined rates, trajectories, and collision detection segments and volumes will be removed. The IG will only send the Start of Frame data packet to the Host and will ignore Host inputs except for the IG Mode attribute of the IG Control data packet. The IG will remain in this mode until directed otherwise by the Host or the IG's user interface.

Operate – This is the normal real-time operating mode for the IG. All packets issued by the Host will be processed by the IG. The IG should not perform diagnostics in this mode.

Debug – This mode is similar to the Operate mode but provides data and/or error logging and other debugging features to aid integration or troubleshooting of the Host and IG interface. Because of the overhead of these debugging features, the IG may not always operate in a hard real-time fashion.

Offline Maintenance – In this mode, the IG ignores all data from the Host and sends only Start of Frame packets. This mode can be activated only from the IG. Because the IG Control packets from the Host are ignored by the IG, the IG must be placed into Reset/Standby mode before the Host can initiate further mode changes.

Reset                0
Standby              1
Operate              1
Debug                2
OfflineMaintenance   3

sub magic_number()

$value = $start_of_frame->magic_number();

Byte Swap Magic Number.

This attribute is used by the Host to determine whether it needs to byte-swap incoming data. Refer to the CIGI ICD, Section 2.1.4 for details on this mechanism.

sub ig_frame_number([$newValue])

$value = $start_of_frame->ig_frame_number($newValue);

IG Frame Number.

This attribute uniquely identifies an IG data frame. The IG should increment this value by one (1) for each successive message.

sub timestamp([$newValue])

$value = $start_of_frame->timestamp($newValue);

Timestamp.

This attribute indicates the number of 10μs “ticks” since some initial reference time. This will enable the IG to correct for latencies as described in the CIGI ICD, Section 2.1.1.1.

The 10μs unit allows the simulation to run for approximately 12 hours before a timestamp rollover occurs. The Host software should contain logic to detect and correct for rollover.

The use of this attribute is required for asynchronous operation.

The use of this attribute is optional for synchronous operation. If this attribute does not contain a valid timestamp, the Timestamp Valid attribute should be set to zero (0).

sub last_host_frame_number([$newValue])

$value = $start_of_frame->last_host_frame_number($newValue);

Last Host Frame Number.

This attribute contains the value of the Host Frame Number attribute in the last IG Control packet received from the Host. This attribute serves as an acknowledgement that the IG received the last message.

sub pack()

$value = $start_of_frame->pack();

Returns the packed data packet.

sub unpack()

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