CVEL

From OrbiterWiki
Revision as of 22:14, 28 February 2007 by Urwumpe (talk | contribs) (added the GPDS description and examples to this article. Thats IMHO easier to understand as placing this information to the GPDS article)
Jump to navigation Jump to search
Building a payload hierarchy with CVEL/GPDS

CVE-lite (abridged Common Vessel Extensions) is a programming library to aid developers of add-on vessels for Orbiter. It extends the native Orbiter VESSEL class with additional functionality for multiple payloads, enhanced mesh handling or scenario-file based multistage support. It evolved from Dave Rowbotham's CVE library, cutting down on some of the internal complexity to allow for easier maintenance, and adding some new functionality.

CVEL implements the Generic Payload Description System (GPDS) to allow the end user to express via simple lines in the scenario file any payload and, if using another CVEL vessel, any additional upper stages. Version-independent inter-vessel communication, as used by the library internally, is also extended to programmers by a companion library, cvelmessage.dll.

History

GPDS was conceived as a way to mount a payload of the end user's choice atop the Ariane 5 as it was developed from a Vinka Multistage vessel to a standalone DLL.

It quickly became clear that combinations of payloads couldn't be specified. That is to say one couldn't mount an upper stage (eg. a Fregat) with a Probe on top of it. The two would necessarily have to jettison as separate vessels. This was not ideal and so an Inter-Vessel Payload Description interface was developed to allow communication between 'active' vessels (ie. to allow the Ariane 5 to tell the Fregat it should have a Probe attached).

The problem with this system (based on Rob Conley's COMMON_VESSEL class) was that, using C++ callbacks, calls between vessels compiled with different libraries would cause a crash. Something needed to be done.

Dave Rowbotham proposed extending the COMMON_VESSEL class to provide even more functionality. This included standardised mesh handling classes and an extensible GPDS handler. So was born COMMON_VESSEL_EX (CVE) which iterated through several beta variations building up an impressive array of supported vessels.

Unfortunately, CVE was also limited to interacting successfully only with other CVE vessels of the same library vintage, and the impressively complex library was slow to debug. CVE-lite was an attempt to distill CVE into a lighter, more easily integratable system. Dropping some of the features of CVE for a closer release date and quicker debugging.

Crucially, CVEL also removed the need for vessels to all be compiled with the same library by introducing the messenger DLL cvelmessage.dll. This enabled CVEL vessels to communicate not only with other CVEL vessels for the purposes of exchanging payload information, but to any other vessel about any information without requiring crash protection. Vessels that didn't support CVELmessage simply never receive the information.

Since the release of CVEL v1.0, there have been a large number of vessels released that support the system including, of course, the original Ariane 5 updated to version 2.

A beta library, including the Orbiter 2005 VESSEL2 class updates was compiled and added to the downloads section of the CVEL website, and is considered by most to be stable for the current implementation of Orbiter.

How to use GPDS2

The PAYLOAD tag

Put simply GPDS allows users of CVE-lite compatible vessels to describe multiple payloads quickly and easily using the PAYLOAD tag in the scenario file.

PAYLOAD payloadname mesh class x y z mass xrot fuellevel

Here, "payloadname" is simply the alphanumeric name you wish the created payload to have.

"Mesh" is the name of the mesh file, including any paths off ~/Mesh that will represent the payload on the stack before it is separated, minus the ".msh"

"Class" is the payload's classname, such as "deltaglider" or "module1".

"x", "y" and "z" represent floating point offsets from the launching vessel's reference point (normally the centre of mass) that the mesh should be drawn. An example would be "0 0 4" for four metres along the centreline of the vessel.

"Mass" is the all-up-mass of the vessel that is to be created, INCLUDING fuel load. If you vary the loaded fuel (see later), you really ought to change this value here to be consistent.

"Xrot" is now sadly abandoned due to a limitation in Orbiter's current API, simply put a zero (0) here.

"Fuellevel" is the level (0->1) of fuel you wish the spawned payload to be equipped with. Not all vessels support the changing of their fuel state at creation, however. Most DLL-based craft won't unless they too are CVE-lite compatible, but most CFG-based vessels will quite happily.

The STAGE tag

STAGEs are broadly similar to PAYLOAD *except* they constitute additional stages to your vessel. That is to say, if you mount a payload above a stage (and before and ENDSTAGE -- see below) it will separate WITH that "stage" vehicle and you may continue to loft the payload(s) before jettionning it later. An example would be the Soyuz launch vessel may configure a Fregat as a STAGE with the MarsExpress as a PAYLOAD above it.

STAGE payloadname mesh class x y z mass xrot fuellevel

(definitions as for PAYLOAD)

The ENDSTAGE tag

Differing to GPDS1 and GPDS2 here, the ENDSTAGE tag allows the user to close-off a substage and continue stacking payloads or more stages onto the launch vessel directly. It takes no parameters.

An example would be an Ariane 5 launching two fregats, both containing MarsExpress orbiters as PAYLOADs.


ENDSTAGE

Examples

Some basic (and not so basic!) examples.


One Module-1 aboard a Proton-K from Baikonur.

Proton1:protonk
  STATUS Landed Earth
  BASE Baikonur:5
  HEADING 90.00
  FUEL 1.000
  CONFIGURATION 0
  PAYLOAD UserModule module1 module1 0 0 30 15000 0 1
END

Here the module1 mesh is loaded on the launcher 30 metres above its centre of mass. It weighs 15000. When it is jettisoned it will be of class "module1", fully fuelled (the 1 on the end) and be called "UserModule"

Two Module-2s

  PAYLOAD UserModule1 module2 module2 0 0 27 8000 0 1
  PAYLOAD UserModule2 module2 module2 0 0 31 8000 0 1

Two Module-2s, each with their own CVE-lite fregat

  STAGE Fregat1 fregat cvelfregat 0 0 27 7000 0 1
    PAYLOAD UserModule1 module2 module2 0 0 31 8000 0 1
  ENDSTAGE
  STAGE Fregat2 fregat cvelfregat 0 0 35 7000 0 1
    PAYLOAD UserModule2 module2 module2 0 0 39 8000 0 1
  ENDSTAGE


MarsExpress probe on a fregat and star48 upper stages

  STAGE Fregat1 fregat cvelfregat 0 0 27 7000 0 1
    STAGE Star1 star48 star48 0 0 30 5000 0 1
      PAYLOAD MarsExpress mars_express_stowed mars_express_deployed 0 0 33 600 0 1
    ENDSTAGE
  ENDSTAGE


See also

incomplete list of CVEL-compatible vessels

CVEL programming tutorial

GPDS

Links

The CCCP Fleet

The official CVEL homepage

CCCP-Team CVE-Lite vessels

CVE Search at Orbithangar

Precis

This article has a precis and appears in the Random addon or Random article section on the Main Page. The precis can be found at CVEL/precis and is displayed below.

Building a payload hierarchy with CVEL/GPDS

CVE-lite (abridged Common Vessel Extensions) is a programming library to aid developers of add-on vessels for Orbiter 2003-2006. It extends the native Orbiter VESSEL class with additional functionality for multiple payloads, enhanced mesh handling or scenario-file based multistage support. It implements the Generic Payload Description System (GPDS) scenario syntax to allow the end user to express via simple lines in the scenario file any payload and, if using another CVEL vessel, any additional upper stages. (More...)