Commit MetaInfo

Révision89b6657c2c11f0aacc54eadec541159799bbcc14 (tree)
l'heure2011-02-22 06:48:14
AuteurFace
CommiterFace

Message de Log

Packaging: upgrade to Orbiter 2010

Change Summary

Modification

diff -r e23423af0d94 -r 89b6657c2c11 Orbiter.Interfaces.dll
Binary file Orbiter.Interfaces.dll has changed
diff -r e23423af0d94 -r 89b6657c2c11 Orbiter.Wrapper.dll
Binary file Orbiter.Wrapper.dll has changed
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/include/OrbiterAPI.h
--- a/Orbitersdk/include/OrbiterAPI.h Tue Nov 03 19:38:45 2009 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1475 +0,0 @@
1-// ======================================================================
2-// ORBITER SOFTWARE DEVELOPMENT KIT
3-// Copyright (C) 2001-2006 Martin Schweiger
4-// All rights reserved
5-// OrbiterAPI.h
6-// ORBITER Application Programming Interface (OAPI)
7-// ======================================================================
8-
9-#ifndef __ORBITERAPI_H
10-#define __ORBITERAPI_H
11-
12-#if defined(_MSC_VER) && (_MSC_VER >= 1300 ) // Microsoft Visual Studio Version 2003 and higher
13-#define _CRT_SECURE_NO_DEPRECATE
14-#include <fstream>
15-#else // older MSVC++ versions
16-#include <fstream.h>
17-#endif
18-#include <windows.h>
19-#include <float.h>
20-#include <math.h>
21-#if defined(_MSC_VER) && (_MSC_VER >= 1400 ) && defined(__cplusplus_cli) // Microsoft Visual Studio Version 2005 and higher while compiling C++/CLI
22-#undef GetClassName
23-#define GetClassName GetClassNameA
24-#endif
25-
26-// Assumes MS VC++ compiler. Modify these statements for other compilers
27-#define DLLEXPORT __declspec(dllexport)
28-#define DLLIMPORT __declspec(dllimport)
29-#define DLLCLBK extern "C" __declspec(dllexport)
30-
31-#ifdef OAPI_IMPLEMENTATION
32-#define OAPIFUNC DLLEXPORT
33-#else
34-#define OAPIFUNC DLLIMPORT
35-#endif
36-
37-// ======================================================================
38-// Some useful constants
39-// ======================================================================
40-
41-const double PI = 3.14159265358979;
42-const double PI05 = 1.57079632679490;
43-const double RAD = PI/180.0;
44-const double DEG = 180.0/PI;
45-const double C0 = 299792458.0; // speed of light in vacuum [m/s]
46-const double TAUA = 499.004783806; // light time for 1 AU [s]
47-const double AU = C0*TAUA; // astronomical unit (mean geocentric distance of the sun) [m]
48-const double GGRAV = 6.67259e-11; // gravitational constant [m^3 kg^-1 s^-2]
49-const double G = 9.81; // gravitational acceleration [m/s^2] at Earth mean radius
50-const double ATMP = 101.4e3; // atmospheric pressure [Pa] at Earth sea level
51-const double ATMD = 1.293; // atmospheric density [kg/m^3] at Earth sea level
52-
53-// ======================================================================
54-// API data types
55-// ======================================================================
56-
57-class VESSEL;
58-class CELBODY;
59-class ExternMFD;
60-
61-typedef void *OBJHANDLE;
62-// Handle for objects (vessels, stations, planets)
63-
64-typedef void *VISHANDLE;
65-// Handle for visuals
66-
67-typedef void *MESHHANDLE;
68-// Handle for meshes
69-
70-typedef void *SURFHANDLE;
71-// Handle for bitmap surfaces (panels and panel items)
72-
73-typedef void *FILEHANDLE;
74-
75-typedef void *THRUSTER_HANDLE;
76-typedef void *THGROUP_HANDLE;
77-// Handle for (logical) thrusters and thruster groups
78-
79-typedef void *PROPELLANT_HANDLE;
80-// Handle for propellant resource
81-
82-typedef void *PSTREAM_HANDLE;
83-// Handle for particle streams
84-
85-typedef void *DOCKHANDLE;
86-// Handle for vessel docking ports
87-
88-typedef void *ATTACHMENTHANDLE;
89-// Handle vor vessel passive attachment points
90-
91-typedef void *AIRFOILHANDLE;
92-// Handle for vessel airfoils
93-
94-typedef void *CTRLSURFHANDLE;
95-// Handle for vessel aerodynamic control surfaces
96-
97-typedef void *NAVHANDLE;
98-// Handle for a navigation radio transmitter (VOR, ILS, IDS, XPDR)
99-
100-typedef void *ANIMATIONCOMPONENT_HANDLE;
101-
102-typedef void *LAUNCHPADITEM_HANDLE;
103-// Handle for custom items added to Launchpad "Extra" list
104-
105-typedef void *NOTEHANDLE;
106-// Handle for onscreen annotations
107-
108-typedef enum { FILE_IN, FILE_OUT, FILE_APP } FileAccessMode;
109-typedef enum { ROOT, CONFIG, SCENARIOS, TEXTURES, TEXTURES2, MESHES, MODULES } PathRoot;
110-
111-typedef union { // 3 vector
112- double data[3];
113- struct { double x, y, z; };
114-} VECTOR3;
115-
116-typedef union { // 3x3 matrix
117- double data[9];
118- struct { double m11, m12, m13, m21, m22, m23, m31, m32, m33; };
119-} MATRIX3;
120-
121-typedef union { // 4x4 matrix
122- double data[16];
123- struct { double m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44; };
124-} MATRIX4;
125-
126-typedef struct { // colour definition
127- float r, g, b, a; // red, green, blue, opacity (0..1)
128-} COLOUR4;
129-
130-typedef struct { // vertex definition including normals and texture coordinates
131- float x, y, z; // position
132- float nx, ny, nz; // normal
133- float tu, tv; // texture coordinates
134-} NTVERTEX;
135-
136-typedef struct { // mesh group definition
137- NTVERTEX *Vtx; // vertex list
138- WORD *Idx; // index list
139- DWORD nVtx; // vertex count
140- DWORD nIdx; // index count
141- DWORD MtrlIdx; // material index (>= 1, 0=none)
142- DWORD TexIdx; // texture index (>= 1, 0=none)
143- DWORD UsrFlag; // user-defined flag
144- WORD zBias; // z bias
145- WORD Flags; // internal flags
146-} MESHGROUP;
147-
148-typedef struct { // material definition
149- COLOUR4 diffuse; // diffuse component
150- COLOUR4 ambient; // ambient component
151- COLOUR4 specular; // specular component
152- COLOUR4 emissive; // emissive component
153- float power; // specular power
154-} MATERIAL;
155-
156-typedef struct { // Orbital elements
157- double a; // semi-major axis [m]
158- double e; // eccentricity
159- double i; // inclination [rad]
160- double theta; // longitude of ascending node [rad]
161- double omegab; // longitude of periapsis [rad]
162- double L; // mean longitude at epoch
163-} ELEMENTS;
164-
165-typedef struct { // additional orbital parameters
166- double SMi; // semi-minor axis
167- double PeD; // periapsis distance
168- double ApD; // apoapsis distance
169- double MnA; // mean anomaly
170- double TrA; // true anomaly
171- double MnL; // mean longitude
172- double TrL; // true longitude
173- double EcA; // eccentric anomaly
174- double Lec; // linear eccentricity
175- double T; // orbit period
176- double PeT; // time to next periapsis passage
177- double ApT; // time to next apoapsis passage
178-} ORBITPARAM;
179-
180-typedef struct { // Planetary atmospheric constants
181- double p0; // pressure at mean radius ('sea level') [Pa]
182- double rho0; // density at mean radius
183- double R; // specific gas constant [J/(K kg)]
184- double gamma; // ratio of specific heats, c_p/c_v
185- double C; // exponent for pressure equation (temporary)
186- double O2pp; // partial pressure of oxygen
187- double altlimit; // atmosphere altitude limit [m]
188- double radlimit; // radius limit (altlimit + mean radius)
189- double horizonalt; // horizon rendering altitude
190- VECTOR3 color0; // sky colour at sea level during daytime
191-} ATMCONST;
192-
193-typedef struct { // Atmospheric parameters
194- double T; // temperature [K]
195- double p; // pressure [Pa]
196- double rho; // density [kg/m^3]
197-} ATMPARAM;
198-
199-typedef struct { // Engine status
200- double main; // -1 (full retro) .. +1 (full main)
201- double hover; // 0 .. +1 (full hover)
202- int attmode; // 0=rotation, 1=translation
203-} ENGINESTATUS;
204-
205-typedef struct { // Particle stream parameters
206- DWORD flags; // streamspec bitflags
207- double srcsize; // particle size at creation [m]
208- double srcrate; // average particle creation rate [Hz]
209- double v0; // emission velocity [m/s]
210- double srcspread; // velocity spread during creation
211- double lifetime; // average particle lifetime
212- double growthrate; // particle growth rate [m/s]
213- double atmslowdown;// slowdown rate in atmosphere
214- enum LTYPE { EMISSIVE, DIFFUSE } ltype; // render lighting method
215- enum LEVELMAP { LVL_FLAT, LVL_LIN, LVL_SQRT, LVL_PLIN, LVL_PSQRT } levelmap; // mapping from level to alpha
216- double lmin, lmax; // min and max levels for level PLIN and PSQRT mapping types
217- enum ATMSMAP { ATM_FLAT, ATM_PLIN, ATM_PLOG } atmsmap; // mapping from atmospheric params to alpha
218- double amin, amax; // min and max densities for atms PLIN mapping
219- SURFHANDLE tex; // particle texture handle (NULL for default)
220-} PARTICLESTREAMSPEC;
221-
222-typedef struct { // vessel beacon light parameters
223- DWORD shape; // beacon texture identifier
224- VECTOR3 *pos; // pointer to position in vessel coordinates
225- VECTOR3 *col; // pointer to beacon RGB colour
226- double size; // beacon radius
227- double falloff; // distance falloff parameter
228- double period; // strobe period (0 for continuous)
229- double duration; // strobe duration
230- double tofs; // strobe time offset
231- bool active; // beacon lit?
232-} BEACONLIGHTSPEC;
233-
234-#define BEACONSHAPE_COMPACT 0
235-#define BEACONSHAPE_DIFFUSE 1
236-#define BEACONSHAPE_STAR 2
237-
238-typedef struct {
239- VECTOR3 rpos; // position relative to rbody (ecliptic frame)
240- VECTOR3 rvel; // velocity relative to rbody (ecliptic frame)
241- VECTOR3 vrot; // rotation velocity about principal axes
242- VECTOR3 arot; // vessel orientation against ecliptic frame
243- double fuel; // fuel level [0..1]
244- double eng_main; // main engine setting [-1..1]
245- double eng_hovr; // hover engine setting [0..1]
246- OBJHANDLE rbody; // handle of reference body
247- OBJHANDLE base; // handle of docking or landing target
248- int port; // designated docking or landing port
249- int status; // 0=freeflight, 1=landed, 2=taxiing, 3=docked, 99=undefined
250-
251- // reserved data structures for future use
252- VECTOR3 vdata[10]; // vdata[0]: contains x=long,y=lat of landing site and z=vessel orientation if status==1
253- double fdata[10];
254- DWORD flag[10];
255-} VESSELSTATUS;
256-
257-typedef struct { // vessel status: interface version 2
258- DWORD version; // version id
259- DWORD flag; // bitflags
260- OBJHANDLE rbody; // handle of reference body
261- OBJHANDLE base; // handle of docking or landing target
262- int port; // designated docking or landing port
263- int status; // 0=freeflight, 1=landed, 3=docked to station (obsolete)
264- VECTOR3 rpos; // position relative to rbody (ecliptic frame)
265- VECTOR3 rvel; // velocity relative to rbody (ecliptic frame)
266- VECTOR3 vrot; // rotation velocity about principal axes
267- VECTOR3 arot; // vessel orientation against ecliptic frame
268- double surf_lng; // longitude of landing position |
269- double surf_lat; // latitude of landing position | only used when landed
270- double surf_hdg; // heading of landed vessel |
271- DWORD nfuel; // length of propellant level list
272- struct FUELSPEC {
273- DWORD idx; // propellant index
274- double level; // propellant level
275- } *fuel; // propellant list
276- DWORD nthruster; // length of thruster level list
277- struct THRUSTSPEC {
278- DWORD idx; // thruster index
279- double level; // thruster level
280- } *thruster; // thruster list
281- DWORD ndockinfo; // length of dock info list
282- struct DOCKINFOSPEC {
283- DWORD idx; // docking port index
284- DWORD ridx; // docking port index of docked vessel
285- OBJHANDLE rvessel; // docked vessel
286- } *dockinfo; // dock info list
287- DWORD xpdr; // transponder setting (in 0.05MHz steps from 108.00)
288-} VESSELSTATUS2;
289-
290-// VESSELSTATUSx bitflags
291-#define VS_FUELRESET 0x00000001
292-#define VS_FUELLIST 0x00000002
293-#define VS_THRUSTRESET 0x00000004
294-#define VS_THRUSTLIST 0x00000008
295-#define VS_DOCKINFOLIST 0x00000010
296-
297-typedef struct {
298- char *helpfile;
299- char *topic;
300- char *toc;
301- char *index;
302-} HELPCONTEXT;
303-
304-typedef struct {
305- char *name;
306- void *parent;
307- char *desc;
308- void (*clbkFunc)(HINSTANCE,HWND);
309-} LP_EXTRAPRM;
310-
311-#pragma pack(push,1)
312-typedef struct {
313- union {
314- struct {
315- VECTOR3 ref;
316- VECTOR3 axis;
317- float angle;
318- } rotparam;
319- struct {
320- VECTOR3 shift;
321- } transparam;
322- struct {
323- VECTOR3 scale;
324- } scaleparam;
325- } P;
326- int nmesh;
327- int ngrp;
328- enum { TRANSLATE, ROTATE, SCALE } transform;
329-} MESHGROUP_TRANSFORM;
330-#pragma pack(pop)
331-
332-typedef struct {
333- UINT *grp;
334- UINT ngrp;
335- double state0;
336- double state1;
337- MESHGROUP_TRANSFORM trans;
338-} ANIMCOMP;
339-
340-// Transformation types for animations
341-
342-// Transformation base class
343-class MGROUP_TRANSFORM {
344-public:
345- MGROUP_TRANSFORM () : mesh(0), grp(0), ngrp(0) {}
346- MGROUP_TRANSFORM (UINT _mesh, UINT *_grp, UINT _ngrp)
347- : mesh(_mesh), grp(_grp), ngrp(_ngrp) {}
348- enum TYPE { NULLTRANSFORM, ROTATE, TRANSLATE, SCALE };
349- virtual TYPE Type() const { return NULLTRANSFORM; }
350-
351- UINT mesh;
352- UINT *grp;
353- UINT ngrp;
354-};
355-
356-// Rotation
357-class MGROUP_ROTATE: public MGROUP_TRANSFORM {
358-public:
359- MGROUP_ROTATE (UINT _mesh, UINT *_grp, UINT _ngrp, const VECTOR3 &_ref, const VECTOR3 &_axis, float _angle)
360- : MGROUP_TRANSFORM (_mesh, _grp, _ngrp), ref(_ref), axis(_axis), angle(_angle) {}
361- TYPE Type() const { return ROTATE; }
362-
363- VECTOR3 ref;
364- VECTOR3 axis;
365- float angle;
366-};
367-
368-// Translation
369-class MGROUP_TRANSLATE: public MGROUP_TRANSFORM {
370-public:
371- MGROUP_TRANSLATE (UINT _mesh, UINT *_grp, UINT _ngrp, const VECTOR3 &_shift)
372- : MGROUP_TRANSFORM (_mesh, _grp, _ngrp), shift(_shift) {}
373- TYPE Type() const { return TRANSLATE; }
374-
375- VECTOR3 shift;
376-};
377-
378-// Scaling
379-class MGROUP_SCALE: public MGROUP_TRANSFORM {
380-public:
381- MGROUP_SCALE (UINT _mesh, UINT *_grp, UINT _ngrp, const VECTOR3 &_ref, const VECTOR3 &_scale)
382- : MGROUP_TRANSFORM (_mesh, _grp, _ngrp), ref(_ref), scale(_scale) {}
383- TYPE Type() const { return SCALE; }
384-
385- VECTOR3 ref;
386- VECTOR3 scale;
387-};
388-
389-#define LOCALVERTEXLIST ((UINT)(-1))
390-#define MAKEGROUPARRAY(x) ((UINT*)x)
391-
392-typedef struct {
393- RECT pos;
394- int nbt_left, nbt_right;
395- int bt_yofs, bt_ydist;
396-} MFDSPEC;
397-
398-typedef struct {
399- DWORD nmesh, ngroup;
400-} VCMFDSPEC;
401-
402-#define MFD_SHOWMODELABELS 1
403-
404-typedef struct {
405- RECT pos;
406- DWORD nmesh, ngroup;
407- DWORD flag;
408- int nbt1, nbt2;
409- int bt_yofs, bt_ydist;
410-} EXTMFDSPEC;
411-
412-typedef struct {
413- DWORD nmesh, ngroup;
414- VECTOR3 hudcnt;
415- double size;
416-} VCHUDSPEC;
417-
418-typedef struct {
419- int W, H;
420- int CX, CY;
421- double Scale;
422- int Markersize;
423-} HUDPAINTSPEC;
424-
425-typedef struct {
426- char *name;
427- DWORD key;
428- int (*msgproc)(UINT,UINT,WPARAM,LPARAM);
429-} MFDMODESPEC;
430-
431-#pragma pack(push,1)
432-typedef struct {
433- const char *line1, *line2;
434- char selchar;
435-} MFDBUTTONMENU;
436-#pragma pack(pop)
437-
438-typedef enum {
439- ENGINE_MAIN,
440- ENGINE_RETRO,
441- ENGINE_HOVER,
442- ENGINE_ATTITUDE
443-} ENGINETYPE;
444-
445-typedef enum {
446- EXHAUST_MAIN,
447- EXHAUST_RETRO,
448- EXHAUST_HOVER,
449- EXHAUST_CUSTOM
450-} EXHAUSTTYPE;
451-
452-typedef enum {
453- THGROUP_MAIN,
454- THGROUP_RETRO,
455- THGROUP_HOVER,
456- THGROUP_ATT_PITCHUP,
457- THGROUP_ATT_PITCHDOWN,
458- THGROUP_ATT_YAWLEFT,
459- THGROUP_ATT_YAWRIGHT,
460- THGROUP_ATT_BANKLEFT,
461- THGROUP_ATT_BANKRIGHT,
462- THGROUP_ATT_RIGHT,
463- THGROUP_ATT_LEFT,
464- THGROUP_ATT_UP,
465- THGROUP_ATT_DOWN,
466- THGROUP_ATT_FORWARD,
467- THGROUP_ATT_BACK,
468- THGROUP_USER = 0x40
469-} THGROUP_TYPE;
470-
471-typedef enum {
472- ATTMODE_DISABLED,
473- ATTMODE_ROT,
474- ATTMODE_LIN,
475-} ATTITUDEMODE;
476-
477-typedef double (*LiftCoeffFunc)(double aoa); // obsolete
478-
479-typedef void (*AirfoilCoeffFunc)(
480- double aoa, double M, double Re,
481- double *cl, double *cm, double *cd);
482-// Template for aerodynamic coefficients callback function
483-// Used to calculate lift coefficient cl, moment coefficient
484-// cm, and drag coefficient cd as a function of angle of attack
485-// aoa, Mach number M, and Reynolds number Re
486-
487-typedef void (*AirfoilCoeffFuncEx)(
488- VESSEL *v, double aoa, double M, double Re, void *context,
489- double *cl, double *cm, double *cd);
490-// Extended version of aerodynamic coefficients callback function
491-// Contains additional parameters (calling vessel and pointer to
492-// user-defined data)
493-
494-typedef enum {
495- LIFT_VERTICAL,
496- LIFT_HORIZONTAL
497-} AIRFOIL_ORIENTATION;
498-
499-typedef enum {
500- AIRCTRL_ELEVATOR,
501- AIRCTRL_RUDDER,
502- AIRCTRL_AILERON,
503- AIRCTRL_FLAP,
504- AIRCTRL_ELEVATORTRIM,
505- AIRCTRL_RUDDERTRIM
506-} AIRCTRL_TYPE;
507-
508-#define AIRCTRL_AXIS_AUTO 0
509-#define AIRCTRL_AXIS_YPOS 1
510-#define AIRCTRL_AXIS_YNEG 2
511-#define AIRCTRL_AXIS_XPOS 3
512-#define AIRCTRL_AXIS_XNEG 4
513-
514-// Object types
515-#define OBJTP_INVALID 0
516-#define OBJTP_GENERIC 1
517-#define OBJTP_CBODY 2
518-#define OBJTP_STAR 3
519-#define OBJTP_PLANET 4
520-#define OBJTP_VESSEL 10
521-#define OBJTP_SURFBASE 20
522-
523-#define NAVMODE_KILLROT 1
524-#define NAVMODE_HLEVEL 2
525-#define NAVMODE_PROGRADE 3
526-#define NAVMODE_RETROGRADE 4
527-#define NAVMODE_NORMAL 5
528-#define NAVMODE_ANTINORMAL 6
529-#define NAVMODE_HOLDALT 7
530-
531-#define MANCTRL_ATTMODE 0
532-#define MANCTRL_REVMODE 1
533-#define MANCTRL_ROTMODE 2
534-#define MANCTRL_LINMODE 3
535-#define MANCTRL_ANYMODE 4
536-
537-#define MANCTRL_KEYBOARD 0
538-#define MANCTRL_JOYSTICK 1
539-#define MANCTRL_ANYDEVICE 2
540-
541-#define COCKPIT_GENERIC 1
542-#define COCKPIT_PANELS 2
543-#define COCKPIT_VIRTUAL 3
544-
545-#define CAM_COCKPIT 0
546-#define CAM_TARGETRELATIVE 1
547-#define CAM_ABSDIRECTION 2
548-#define CAM_GLOBALFRAME 3
549-#define CAM_TARGETTOOBJECT 4
550-#define CAM_TARGETFROMOBJECT 5
551-#define CAM_GROUNDOBSERVER 6
552-
553-// time propagation modes
554-#define PROP_ORBITAL 0x0F
555-#define PROP_ORBITAL_ELEMENTS 0x00
556-#define PROP_ORBITAL_FIXEDSTATE 0x01
557-#define PROP_ORBITAL_FIXEDSURF 0x02
558-#define PROP_SORBITAL 0xF0
559-#define PROP_SORBITAL_ELEMENTS (0x0 << 4)
560-#define PROP_SORBITAL_FIXEDSTATE (0x1 << 4)
561-#define PROP_SORBITAL_FIXEDSURF (0x2 << 4)
562-#define PROP_SORBITAL_DESTROY (0x3 << 4)
563-
564-#define RCS_NONE 0
565-#define RCS_ROT 1
566-#define RCS_LIN 2
567-
568-#define HUD_NONE 0
569-#define HUD_ORBIT 1
570-#define HUD_SURFACE 2
571-#define HUD_DOCKING 3
572-
573-#define MFD_REFRESHBUTTONS -1
574-#define MFD_NONE 0
575-#define MFD_ORBIT 1
576-#define MFD_SURFACE 2
577-#define MFD_MAP 3
578-#define MFD_HSI 4
579-#define MFD_LANDING 5
580-#define MFD_DOCKING 6
581-#define MFD_OPLANEALIGN 7
582-#define MFD_OSYNC 8
583-#define MFD_TRANSFER 9
584-#define MFD_COMMS 10
585-#define MFD_USERTYPE 64
586-#define BUILTIN_MFD_MODES 10
587-
588-#define MAXMFD 10
589-#define MFD_LEFT 0
590-#define MFD_RIGHT 1
591-#define MFD_USER1 2
592-#define MFD_USER2 3
593-#define MFD_USER3 4
594-#define MFD_USER4 5
595-#define MFD_USER5 6
596-#define MFD_USER6 7
597-#define MFD_USER7 8
598-#define MFD_USER8 9
599-
600-#define PANEL_LEFT 0
601-#define PANEL_RIGHT 1
602-#define PANEL_UP 2
603-#define PANEL_DOWN 3
604-
605-#define PANEL_REDRAW_NEVER 0x00
606-#define PANEL_REDRAW_ALWAYS 0x01
607-#define PANEL_REDRAW_MOUSE 0x02
608-#define PANEL_REDRAW_INIT 0x03
609-#define PANEL_REDRAW_USER 0x04
610-
611-#define PANEL_MOUSE_IGNORE 0x00
612-#define PANEL_MOUSE_LBDOWN 0x01
613-#define PANEL_MOUSE_RBDOWN 0x02
614-#define PANEL_MOUSE_LBUP 0x04
615-#define PANEL_MOUSE_RBUP 0x08
616-#define PANEL_MOUSE_LBPRESSED 0x10
617-#define PANEL_MOUSE_RBPRESSED 0x20
618-#define PANEL_MOUSE_DOWN 0x03
619-#define PANEL_MOUSE_UP 0x0C
620-#define PANEL_MOUSE_PRESSED 0x30
621-#define PANEL_MOUSE_ONREPLAY 0x40
622-
623-#define PANEL_MAP_NONE 0x00
624-#define PANEL_MAP_BACKGROUND 0x01
625-#define PANEL_MAP_CURRENT 0x02
626-#define PANEL_MAP_BGONREQUEST 0x03
627-
628-#define PANEL_ATTACH_BOTTOM 0x0001
629-#define PANEL_ATTACH_TOP 0x0002
630-#define PANEL_ATTACH_LEFT 0x0004
631-#define PANEL_ATTACH_RIGHT 0x0008
632-#define PANEL_MOVEOUT_BOTTOM 0x0010
633-#define PANEL_MOVEOUT_TOP 0x0020
634-#define PANEL_MOVEOUT_LEFT 0x0040
635-#define PANEL_MOVEOUT_RIGHT 0x0080
636-
637-#define SURF_NO_CK 0xFFFFFFFF
638-#define SURF_PREDEF_CK 0xFFFFFFFE
639-
640-#define SURF_NO_ROTATION ((DWORD)-1)
641-#define SURF_HMIRROR ((DWORD)-2)
642-#define SURF_VMIRROR ((DWORD)-3)
643-#define SURF_ROTATE_90 ((DWORD)-4)
644-#define SURF_ROTATE_180 ((DWORD)-5)
645-#define SURF_ROTATE_270 ((DWORD)-6)
646-
647-#define DLG_ALLOWMULTI 0x1
648-#define DLG_CAPTIONCLOSE 0x2
649-#define DLG_CAPTIONHELP 0x4
650-
651-#define DLG_CB_TWOSTATE 0x1
652-
653-// Custom MFD message identifiers
654-#define OAPI_MSG_MFD_OPENED 1
655-#define OAPI_MSG_MFD_CLOSED 2
656-#define OAPI_MSG_MFD_UPDATE 3
657-
658-#define MESHVIS_NEVER 0x00
659-#define MESHVIS_EXTERNAL 0x01
660-#define MESHVIS_COCKPIT 0x02
661-#define MESHVIS_ALWAYS (MESHVIS_EXTERNAL|MESHVIS_COCKPIT)
662-#define MESHVIS_VC 0x04
663-#define MESHVIS_EXTPASS 0x10
664-
665-#define MESHPROPERTY_MODULATEMATALPHA 1
666-
667-// navigation radio transmitter types
668-#define TRANSMITTER_NONE 0
669-#define TRANSMITTER_VOR 1
670-#define TRANSMITTER_VTOL 2
671-#define TRANSMITTER_ILS 3
672-#define TRANSMITTER_IDS 4
673-#define TRANSMITTER_XPDR 5
674-
675-const UINT ALLDOCKS = (UINT)-1;
676-
677-typedef int (*KeyFunc)(const char *keybuf);
678-
679-// ======================================================================
680-// class LaunchpadItem
681-// ======================================================================
682-
683-class DLLEXPORT LaunchpadItem {
684-public:
685- LaunchpadItem ();
686- virtual ~LaunchpadItem ();
687- virtual char *Name ();
688- virtual char *Description ();
689- virtual bool OpenDialog (HINSTANCE hInst, HWND hLaunchpad, int resId, DLGPROC pDlg);
690- virtual bool clbkOpen (HWND hLaunchpad);
691- virtual int clbkWriteConfig ();
692-
693- LAUNCHPADITEM_HANDLE hItem;
694-};
695-
696-// ======================================================================
697-// class CameraMode and subclasses
698-// ======================================================================
699-
700-class DLLEXPORT CameraMode {
701-friend class Camera;
702-public:
703- CameraMode ();
704- static CameraMode *Create (char *str);
705- virtual void Init (char *str) = 0;
706- virtual void Store (char *str) = 0;
707- enum Mode { CM_COCKPIT, CM_TRACK, CM_GROUND };
708- OBJHANDLE GetTarget() const { return target; }
709- virtual Mode GetMode() const = 0;
710- virtual void GetDescr (char *str, int len) = 0;
711- void SetTarget (OBJHANDLE hTgt);
712- void SetFOV (double FOV);
713- double GetFOV () const { return fov; }
714-
715-protected:
716- OBJHANDLE target; // camera target
717- double fov; // field of view [deg]
718-};
719-
720-class DLLEXPORT CameraMode_Cockpit: public CameraMode {
721-public:
722- CameraMode_Cockpit ();
723- void Init (char*) {}
724- void Store (char *str);
725- Mode GetMode() const { return CM_COCKPIT; }
726- void GetDescr (char *str, int len);
727-};
728-
729-class DLLEXPORT CameraMode_Track: public CameraMode {
730-public:
731- CameraMode_Track ();
732- void Init (char *str);
733- void Store (char *str);
734- Mode GetMode() const { return CM_TRACK; }
735- void GetDescr (char *str, int len);
736- enum TrackMode { TM_CURRENT, TM_RELATIVE, TM_ABSDIR, TM_GLOBAL, TM_TARGETTOREF, TM_TARGETFROMREF };
737- TrackMode GetTrackMode () const { return tmode; }
738- void SetTrackMode (TrackMode trackmode, OBJHANDLE refobj = 0);
739- OBJHANDLE GetRef() const { return ref; }
740- void SetPosition (double rd, double ph, double th);
741- void GetPosition (double *rd, double *ph, double *th) const;
742-
743-protected:
744- TrackMode tmode; // camera track mode
745- double reldist; // distance camera-targets (in units of target size)
746- double phi, theta; // camera angle [rad]
747- OBJHANDLE ref; // reference object (for TM_TARGETTOREF and TM_TARGETFROMREF only)
748-};
749-
750-class DLLEXPORT CameraMode_Ground: public CameraMode {
751-public:
752- CameraMode_Ground ();
753- void Init (char *str);
754- void Store (char *str);
755- Mode GetMode () const { return CM_GROUND; }
756- void GetDescr (char *str, int len);
757- void SetPosition (double longitude, double latitude, double altitude, OBJHANDLE hRef = 0);
758- void GetPosition (double *longitude, double *latitude, double *altitude, OBJHANDLE *hRef) const;
759- void SetOrientation (double ph, double th);
760- void GetOrientation (double *ph, double *th) const;
761- bool GetTgtLock () const { return tgtlock; }
762- OBJHANDLE GetRef() const { return ref; }
763-
764-protected:
765- OBJHANDLE ref;
766- double lng, lat; // camera position on the ground [rad]
767- double alt; // camera height over ground [m]
768- double phi, theta; // camera direction (free mode only)
769- bool tgtlock; // flag for target lock/free mode
770-};
771-
772-// ======================================================================
773-// Orbiter API interface methods
774-// ======================================================================
775-
776-OAPIFUNC int oapiGetOrbiterVersion ();
777- int oapiGetModuleVersion ();
778-OAPIFUNC HINSTANCE oapiGetOrbiterInstance ();
779-OAPIFUNC const char *oapiGetCmdLine ();
780-
781-OAPIFUNC OBJHANDLE oapiGetObjectByName (char *name);
782-OAPIFUNC OBJHANDLE oapiGetObjectByIndex (int index);
783-OAPIFUNC DWORD oapiGetObjectCount ();
784-OAPIFUNC int oapiGetObjectType (OBJHANDLE hObj);
785-
786-OAPIFUNC OBJHANDLE oapiGetVesselByName (char *name);
787-OAPIFUNC OBJHANDLE oapiGetVesselByIndex (int index);
788-OAPIFUNC DWORD oapiGetVesselCount ();
789-OAPIFUNC bool oapiIsVessel (OBJHANDLE hVessel);
790-
791-OAPIFUNC OBJHANDLE oapiGetStationByName (char *name);
792-OAPIFUNC OBJHANDLE oapiGetStationByIndex (int index);
793-OAPIFUNC DWORD oapiGetStationCount ();
794-
795-OAPIFUNC OBJHANDLE oapiGetGbodyByName (char *name);
796-OAPIFUNC OBJHANDLE oapiGetGbodyByIndex (int index);
797-OAPIFUNC DWORD oapiGetGbodyCount ();
798-
799-OAPIFUNC OBJHANDLE oapiGetBaseByName (OBJHANDLE hPlanet, char *name);
800-OAPIFUNC OBJHANDLE oapiGetBaseByIndex (OBJHANDLE hPlanet, int index);
801-OAPIFUNC DWORD oapiGetBaseCount (OBJHANDLE hPlanet);
802-
803-OAPIFUNC void oapiGetObjectName (OBJHANDLE hObj, char *name, int n);
804-
805-OAPIFUNC OBJHANDLE oapiGetFocusObject ();
806-OAPIFUNC OBJHANDLE oapiSetFocusObject (OBJHANDLE hVessel);
807-
808-OAPIFUNC VESSEL *oapiGetVesselInterface (OBJHANDLE hVessel);
809-OAPIFUNC VESSEL *oapiGetFocusInterface ();
810-OAPIFUNC CELBODY *oapiGetCelbodyInterface (OBJHANDLE hBody);
811-
812-OAPIFUNC OBJHANDLE oapiCreateVessel (const char *name, const char *classname, const VESSELSTATUS &status);
813-OAPIFUNC OBJHANDLE oapiCreateVesselEx (const char *name, const char *classname, const void *status);
814-OAPIFUNC bool oapiDeleteVessel (OBJHANDLE hVessel, OBJHANDLE hAlternativeCameraTarget = 0);
815-
816-OAPIFUNC double oapiGetSize (OBJHANDLE hObj);
817-OAPIFUNC double oapiGetMass (OBJHANDLE hObj);
818-
819-OAPIFUNC double oapiGetEmptyMass (OBJHANDLE hVessel);
820-OAPIFUNC double oapiGetFuelMass (OBJHANDLE hVessel);
821-OAPIFUNC void oapiSetEmptyMass (OBJHANDLE hVessel, double mass);
822-OAPIFUNC double oapiGetMaxFuelMass (OBJHANDLE hVessel);
823-OAPIFUNC double oapiGetPropellantMaxMass (PROPELLANT_HANDLE ph);
824-OAPIFUNC double oapiGetPropellantMass (PROPELLANT_HANDLE ph);
825-OAPIFUNC PROPELLANT_HANDLE oapiGetPropellantHandle (OBJHANDLE hVessel, DWORD idx);
826-
827-OAPIFUNC DOCKHANDLE oapiGetDockHandle (OBJHANDLE hVessel, UINT n);
828-OAPIFUNC OBJHANDLE oapiGetDockStatus (DOCKHANDLE dock);
829-
830-OAPIFUNC void oapiGetGlobalPos (OBJHANDLE hObj, VECTOR3 *pos);
831-OAPIFUNC void oapiGetGlobalVel (OBJHANDLE hObj, VECTOR3 *vel);
832-OAPIFUNC void oapiGetFocusGlobalPos (VECTOR3 *pos);
833-OAPIFUNC void oapiGetFocusGlobalVel (VECTOR3 *vel);
834-
835-OAPIFUNC void oapiGetRelativePos (OBJHANDLE hObj, OBJHANDLE hRef, VECTOR3 *pos);
836-OAPIFUNC void oapiGetRelativeVel (OBJHANDLE hObj, OBJHANDLE hRef, VECTOR3 *vel);
837-OAPIFUNC void oapiGetFocusRelativePos (OBJHANDLE hRef, VECTOR3 *pos);
838-OAPIFUNC void oapiGetFocusRelativeVel (OBJHANDLE hRef, VECTOR3 *vel);
839-
840-OAPIFUNC void oapiGetBarycentre (OBJHANDLE hObj, VECTOR3 *bary);
841-OAPIFUNC void oapiGetRotationMatrix (OBJHANDLE hObj, MATRIX3 *mat);
842-
843-OAPIFUNC BOOL oapiGetAltitude (OBJHANDLE hVessel, double *alt);
844-OAPIFUNC BOOL oapiGetPitch (OBJHANDLE hVessel, double *pitch);
845-OAPIFUNC BOOL oapiGetBank (OBJHANDLE hVessel, double *bank);
846-OAPIFUNC BOOL oapiGetHeading (OBJHANDLE hVessel, double *heading);
847-OAPIFUNC BOOL oapiGetEquPos (OBJHANDLE hVessel, double *longitude, double *latitude, double *radius);
848-OAPIFUNC BOOL oapiGetFocusAltitude (double *alt);
849-OAPIFUNC BOOL oapiGetFocusPitch (double *pitch);
850-OAPIFUNC BOOL oapiGetFocusBank (double *bank);
851-OAPIFUNC BOOL oapiGetFocusHeading (double *heading);
852-OAPIFUNC BOOL oapiGetFocusEquPos (double *longitude, double *latitude, double *radius);
853-
854-OAPIFUNC BOOL oapiGetAirspeed (OBJHANDLE hVessel, double *airspeed);
855-OAPIFUNC BOOL oapiGetAirspeedVector (OBJHANDLE hVessel, VECTOR3 *speedvec);
856-OAPIFUNC BOOL oapiGetShipAirspeedVector (OBJHANDLE hVessel, VECTOR3 *speedvec);
857-OAPIFUNC BOOL oapiGetFocusAirspeed (double *airspeed);
858-OAPIFUNC BOOL oapiGetFocusAirspeedVector (VECTOR3 *speedvec);
859-OAPIFUNC BOOL oapiGetFocusShipAirspeedVector (VECTOR3 *speedvec);
860-
861-OAPIFUNC void oapiGetAtmPressureDensity (OBJHANDLE hVessel, double *pressure, double *density);
862-OAPIFUNC void oapiGetFocusAtmPressureDensity (double *pressure, double *density);
863-
864-OAPIFUNC void oapiGetEngineStatus (OBJHANDLE hVessel, ENGINESTATUS *es);
865-OAPIFUNC void oapiGetFocusEngineStatus (ENGINESTATUS *es);
866-OAPIFUNC void oapiSetEngineLevel (OBJHANDLE hVessel, ENGINETYPE engine, double level);
867-OAPIFUNC SURFHANDLE oapiRegisterExhaustTexture (char *name);
868-OAPIFUNC SURFHANDLE oapiRegisterReentryTexture (char *name);
869-OAPIFUNC SURFHANDLE oapiRegisterParticleTexture (char *name);
870-
871-OAPIFUNC int oapiGetAttitudeMode (OBJHANDLE hVessel);
872-OAPIFUNC int oapiToggleAttitudeMode (OBJHANDLE hVessel);
873-OAPIFUNC bool oapiSetAttitudeMode (OBJHANDLE hVessel, int mode);
874-OAPIFUNC int oapiGetFocusAttitudeMode ();
875-OAPIFUNC int oapiToggleFocusAttitudeMode ();
876-OAPIFUNC bool oapiSetFocusAttitudeMode (int mode);
877-
878-OAPIFUNC void oapiSetShowGrapplePoints (bool show);
879-OAPIFUNC bool oapiGetShowGrapplePoints ();
880-
881-OAPIFUNC double oapiGetSimTime ();
882-OAPIFUNC double oapiGetSimStep ();
883-OAPIFUNC double oapiGetSysTime ();
884-OAPIFUNC double oapiGetSysStep ();
885-OAPIFUNC double oapiGetSimMJD ();
886-OAPIFUNC double oapiGetSysMJD ();
887-OAPIFUNC bool oapiSetSimMJD (double mjd, int pmode = 0);
888-OAPIFUNC double oapiGetFrameRate ();
889-OAPIFUNC double oapiTime2MJD (double t);
890-OAPIFUNC double oapiGetTimeAcceleration ();
891-OAPIFUNC void oapiSetTimeAcceleration (double warp);
892-OAPIFUNC bool oapiGetPause ();
893-OAPIFUNC void oapiSetPause (bool pause);
894-
895-OAPIFUNC bool oapiAcceptDelayedKey (char key, double interval);
896-
897-// Aerodynamics helper functions
898-OAPIFUNC double oapiGetInducedDrag (double cl, double A, double e);
899-OAPIFUNC double oapiGetWaveDrag (double M, double M1, double M2, double M3, double cmax);
900-
901-// Camera functions
902-OAPIFUNC bool oapiCameraInternal ();
903-OAPIFUNC int oapiCameraMode ();
904-OAPIFUNC int oapiCockpitMode ();
905-OAPIFUNC OBJHANDLE oapiCameraTarget ();
906-OAPIFUNC void oapiCameraGlobalPos (VECTOR3 *gpos);
907-OAPIFUNC void oapiCameraGlobalDir (VECTOR3 *gdir);
908-OAPIFUNC double oapiCameraTargetDist ();
909-OAPIFUNC double oapiCameraAzimuth ();
910-OAPIFUNC double oapiCameraPolar ();
911-OAPIFUNC double oapiCameraAperture ();
912-OAPIFUNC void oapiCameraSetAperture (double aperture);
913-OAPIFUNC void oapiCameraScaleDist (double dscale);
914-OAPIFUNC void oapiCameraRotAzimuth (double dazimuth);
915-OAPIFUNC void oapiCameraRotPolar (double dpolar);
916-OAPIFUNC void oapiCameraSetCockpitDir (double polar, double azimuth, bool transition = false);
917-OAPIFUNC void oapiCameraAttach (OBJHANDLE hObj, int mode);
918-
919-// Functions for planetary bodies
920-OAPIFUNC double oapiGetPlanetPeriod (OBJHANDLE hPlanet);
921-OAPIFUNC double oapiGetPlanetObliquity (OBJHANDLE hPlanet);
922-OAPIFUNC double oapiGetPlanetTheta (OBJHANDLE hPlanet);
923-OAPIFUNC void oapiGetPlanetObliquityMatrix (OBJHANDLE hPlanet, MATRIX3 *mat);
924-OAPIFUNC double oapiGetPlanetCurrentRotation (OBJHANDLE hPlanet);
925-OAPIFUNC bool oapiPlanetHasAtmosphere (OBJHANDLE hPlanet);
926-OAPIFUNC void oapiGetPlanetAtmParams (OBJHANDLE hPlanet, double rad, ATMPARAM *prm);
927-OAPIFUNC const ATMCONST *oapiGetPlanetAtmConstants (OBJHANDLE hPlanet);
928-OAPIFUNC DWORD oapiGetPlanetJCoeffCount (OBJHANDLE hPlanet);
929-OAPIFUNC double oapiGetPlanetJCoeff (OBJHANDLE hPlanet, DWORD n);
930-
931-// Surface base interface
932-OAPIFUNC void oapiGetBaseEquPos (OBJHANDLE hBase, double *lng, double *lat, double *rad = 0);
933-OAPIFUNC DWORD oapiGetBasePadCount (OBJHANDLE hBase);
934-OAPIFUNC bool oapiGetBasePadEquPos (OBJHANDLE hBase, DWORD pad, double *lng, double *lat, double *rad = 0);
935-OAPIFUNC bool oapiGetBasePadStatus (OBJHANDLE hBase, DWORD pad, int *status);
936-OAPIFUNC NAVHANDLE oapiGetBasePadNav (OBJHANDLE hBase, DWORD pad);
937-
938-// Navigation radio transmitter functions
939-OAPIFUNC void oapiGetNavPos (NAVHANDLE hNav, VECTOR3 *gpos);
940-OAPIFUNC DWORD oapiGetNavChannel (NAVHANDLE hNav);
941-OAPIFUNC float oapiGetNavFreq (NAVHANDLE hNav);
942-OAPIFUNC float oapiGetNavRange (NAVHANDLE hNav);
943-OAPIFUNC DWORD oapiGetNavType (NAVHANDLE hNav);
944-OAPIFUNC int oapiGetNavDescr (NAVHANDLE hNav, char *descr, int maxlen);
945-OAPIFUNC bool oapiNavInRange (NAVHANDLE hNav, const VECTOR3 &gpos);
946-
947-// Visual and mesh functions
948-OAPIFUNC VISHANDLE *oapiObjectVisualPtr (OBJHANDLE hObject);
949-OAPIFUNC MESHHANDLE oapiLoadMesh (const char *fname);
950-OAPIFUNC const MESHHANDLE oapiLoadMeshGlobal (const char *fname);
951-OAPIFUNC void oapiDeleteMesh (MESHHANDLE hMesh);
952-OAPIFUNC SURFHANDLE oapiGetTextureHandle (MESHHANDLE hMesh, DWORD texidx);
953-OAPIFUNC SURFHANDLE oapiLoadTexture (const char *fname, bool dynamic = false);
954-OAPIFUNC bool oapiSetTexture (MESHHANDLE hMesh, DWORD texidx, SURFHANDLE tex);
955-OAPIFUNC DWORD oapiMeshGroupCount (MESHHANDLE hMesh);
956-OAPIFUNC MESHGROUP *oapiMeshGroup (MESHHANDLE hMesh, DWORD idx);
957-OAPIFUNC DWORD oapiMeshMaterialCount (MESHHANDLE hMesh);
958-OAPIFUNC MATERIAL *oapiMeshMaterial (MESHHANDLE hMesh, DWORD idx);
959-OAPIFUNC DWORD oapiAddMaterial (MESHHANDLE hMesh, MATERIAL *mat);
960-OAPIFUNC bool oapiDeleteMaterial (MESHHANDLE hMesh, DWORD idx);
961-OAPIFUNC bool oapiSetMeshProperty (MESHHANDLE hMesh, DWORD property, DWORD value);
962-
963-// Particle functions
964-OAPIFUNC void oapiParticleSetLevelRef (PSTREAM_HANDLE ph, double *lvl);
965-
966-// HUD, MFD and panel functions
967-OAPIFUNC bool oapiSetHUDMode (int mode);
968-OAPIFUNC int oapiGetHUDMode ();
969-OAPIFUNC void oapiToggleHUDColour ();
970-OAPIFUNC void oapiIncHUDIntensity ();
971-OAPIFUNC void oapiDecHUDIntensity ();
972-OAPIFUNC void oapiOpenMFD (int mode, int mfd);
973-OAPIFUNC void oapiToggleMFD_on (int mfd);
974-OAPIFUNC int oapiGetMFDMode (int mfd);
975-OAPIFUNC int oapiBroadcastMFDMessage (int mode, int msg, void *data);
976-OAPIFUNC int oapiSendMFDKey (int mfd, DWORD key);
977-OAPIFUNC void oapiRefreshMFDButtons (int mfd, OBJHANDLE hVessel = 0);
978-OAPIFUNC bool oapiProcessMFDButton (int mfd, int bt, int event);
979-OAPIFUNC const char *oapiMFDButtonLabel (int mfd, int bt);
980-OAPIFUNC void oapiRegisterMFD (int mfd, const MFDSPEC &spec);
981-OAPIFUNC void oapiRegisterMFD (int mfd, const EXTMFDSPEC *spec);
982-OAPIFUNC void oapiRegisterExternMFD (ExternMFD *emfd, const MFDSPEC &spec);
983-OAPIFUNC bool oapiUnregisterExternMFD (ExternMFD *emfd);
984-OAPIFUNC void oapiRegisterPanelBackground (HBITMAP hBmp, DWORD flag = PANEL_ATTACH_BOTTOM|PANEL_MOVEOUT_BOTTOM,
985- DWORD ck = (DWORD)-1);
986-OAPIFUNC void oapiRegisterPanelArea (int id, const RECT &pos, int draw_event = PANEL_REDRAW_NEVER,
987- int mouse_event = PANEL_MOUSE_IGNORE, int bkmode = PANEL_MAP_NONE);
988-OAPIFUNC void oapiSetPanelNeighbours (int left, int right, int top, int bottom);
989-OAPIFUNC void oapiTriggerPanelRedrawArea (int panel_id, int area_id);
990-OAPIFUNC void oapiTriggerRedrawArea (int panel_id, int vc_id, int area_id);
991-OAPIFUNC bool oapiBltPanelAreaBackground (int area_id, SURFHANDLE surf);
992-OAPIFUNC void oapiSetDefNavDisplay (int mode);
993-OAPIFUNC void oapiSetDefRCSDisplay (int mode);
994-OAPIFUNC int oapiSwitchPanel (int direction);
995-OAPIFUNC int oapiSetPanel (int panel_id);
996-OAPIFUNC HDC oapiGetDC (SURFHANDLE surf);
997-OAPIFUNC void oapiReleaseDC (SURFHANDLE surf, HDC hDC);
998-OAPIFUNC DWORD oapiGetColour (DWORD red, DWORD green, DWORD blue);
999-OAPIFUNC SURFHANDLE oapiCreateSurface (int width, int height);
1000-OAPIFUNC SURFHANDLE oapiCreateSurface (HBITMAP hBmp, bool release_bmp = true);
1001-OAPIFUNC SURFHANDLE oapiCreateTextureSurface (int width, int height);
1002-OAPIFUNC void oapiDestroySurface (SURFHANDLE surf);
1003-OAPIFUNC void oapiClearSurface (SURFHANDLE surf, DWORD col = 0);
1004-OAPIFUNC void oapiSetSurfaceColourKey (SURFHANDLE surf, DWORD ck);
1005-OAPIFUNC void oapiClearSurfaceColourKey (SURFHANDLE surf);
1006-OAPIFUNC void oapiBlt (SURFHANDLE tgt, SURFHANDLE src, int tgtx, int tgty, int srcx, int srcy, int w, int h, DWORD ck = SURF_NO_CK);
1007-OAPIFUNC void oapiBlt (SURFHANDLE tgt, SURFHANDLE src, RECT *tgtr, RECT *srcr, DWORD ck = SURF_NO_CK, DWORD rotate = SURF_NO_ROTATION);
1008-OAPIFUNC void oapiColourFill (SURFHANDLE tgt, DWORD fillcolor, int tgtx = 0, int tgty = 0, int w = 0, int h = 0);
1009-
1010-// Custom MFD mode definition
1011-OAPIFUNC int oapiRegisterMFDMode (MFDMODESPEC &spec);
1012-OAPIFUNC bool oapiUnregisterMFDMode (int mode);
1013-OAPIFUNC void oapiDisableMFDMode (int mode);
1014-OAPIFUNC int oapiGetMFDModeSpec (char *name, MFDMODESPEC **spec = 0);
1015-
1016-// virtual cockpit functions
1017-OAPIFUNC void oapiVCRegisterMFD (int mfd, const VCMFDSPEC *spec);
1018-OAPIFUNC void oapiVCRegisterArea (int id, const RECT &tgtrect, int draw_event, int mouse_event, int bkmode, SURFHANDLE tgt);
1019-OAPIFUNC void oapiVCRegisterArea (int id, int draw_event, int mouse_event);
1020-OAPIFUNC void oapiVCSetAreaClickmode_Spherical (int id, const VECTOR3 &cnt, double rad);
1021-OAPIFUNC void oapiVCSetAreaClickmode_Quadrilateral (int id, const VECTOR3 &p1, const VECTOR3 &p2, const VECTOR3 &p3, const VECTOR3 &p4);
1022-OAPIFUNC void oapiVCSetNeighbours (int left, int right, int top, int bottom);
1023-OAPIFUNC void oapiVCTriggerRedrawArea (int vc_id, int area_id);
1024-OAPIFUNC void oapiVCRegisterHUD (const VCHUDSPEC *spec);
1025-
1026-// Customisation - custom menu, dialogs
1027-OAPIFUNC LAUNCHPADITEM_HANDLE oapiRegisterLaunchpadItem (LaunchpadItem *item, LAUNCHPADITEM_HANDLE parent = 0);
1028-OAPIFUNC bool oapiUnregisterLaunchpadItem (LaunchpadItem *item);
1029-OAPIFUNC LAUNCHPADITEM_HANDLE oapiFindLaunchpadItem (const char *name = 0, LAUNCHPADITEM_HANDLE parent = 0);
1030-typedef void (*CustomFunc)(void *context);
1031-OAPIFUNC DWORD oapiRegisterCustomCmd (char *label, char *desc, CustomFunc func, void *context);
1032-OAPIFUNC bool oapiUnregisterCustomCmd (int cmdId);
1033-
1034-OAPIFUNC HWND oapiOpenDialog (HINSTANCE hDLLInst, int resourceId, DLGPROC msgProc, void *context = 0);
1035-OAPIFUNC HWND oapiOpenDialogEx (HINSTANCE hDLLInst, int resourceId, DLGPROC msgProc, DWORD flag = 0, void *context = 0);
1036-OAPIFUNC HWND oapiFindDialog (HINSTANCE hDLLInst, int resourceId);
1037-OAPIFUNC void oapiCloseDialog (HWND hDlg);
1038-OAPIFUNC void *oapiGetDialogContext (HWND hDlg);
1039-OAPIFUNC bool oapiAddTitleButton (DWORD msgid, HBITMAP hBmp, DWORD flag);
1040-OAPIFUNC DWORD oapiGetTitleButtonState (HWND hDlg, DWORD msgid);
1041-OAPIFUNC bool oapiSetTitleButtonState (HWND hDlg, DWORD msgid, DWORD state);
1042-OAPIFUNC BOOL oapiDefDialogProc (HWND hDlg, UINT uMsg, WPARAM wParam, LPARAM lParam);
1043-OAPIFUNC bool oapiOpenHelp (HELPCONTEXT *hcontext);
1044-
1045-// File IO
1046-OAPIFUNC FILEHANDLE oapiOpenFile (const char *fname, FileAccessMode mode, PathRoot root = ROOT);
1047-OAPIFUNC void oapiCloseFile (FILEHANDLE file, FileAccessMode mode);
1048-OAPIFUNC bool oapiSaveScenario (const char *fname, const char *desc);
1049-OAPIFUNC void oapiWriteLine (FILEHANDLE file, char *line);
1050-OAPIFUNC void oapiWriteLog (char *line);
1051-OAPIFUNC void oapiWriteScenario_string (FILEHANDLE scn, char *item, char *string);
1052-OAPIFUNC void oapiWriteScenario_int (FILEHANDLE scn, char *item, int i);
1053-OAPIFUNC void oapiWriteScenario_float (FILEHANDLE scn, char *item, double d);
1054-OAPIFUNC void oapiWriteScenario_vec (FILEHANDLE scn, char *item, const VECTOR3 &vec);
1055-OAPIFUNC bool oapiReadScenario_nextline (FILEHANDLE scn, char *&line);
1056-OAPIFUNC bool oapiReadItem_string (FILEHANDLE f, char *item, char *string);
1057-OAPIFUNC bool oapiReadItem_float (FILEHANDLE f, char *item, double &d);
1058-OAPIFUNC bool oapiReadItem_int (FILEHANDLE f, char *item, int &i);
1059-OAPIFUNC bool oapiReadItem_bool (FILEHANDLE f, char *item, bool &b);
1060-OAPIFUNC bool oapiReadItem_vec (FILEHANDLE f, char *item, VECTOR3 &vec);
1061-OAPIFUNC void oapiWriteItem_string (FILEHANDLE f, char *item, char *string);
1062-OAPIFUNC void oapiWriteItem_float (FILEHANDLE f, char *item, double d);
1063-OAPIFUNC void oapiWriteItem_int (FILEHANDLE f, char *item, int i);
1064-OAPIFUNC void oapiWriteItem_bool (FILEHANDLE f, char *item, bool b);
1065-OAPIFUNC void oapiWriteItem_vec (FILEHANDLE f, char *item, const VECTOR3 &vec);
1066-
1067-// Utility functions
1068-OAPIFUNC double oapiRand ();
1069-
1070-// User Input
1071-OAPIFUNC void oapiOpenInputBox (char *title, bool (*Clbk)(void*,char*,void*), char *buf = 0, int vislen = 20, void *usrdata = 0);
1072-
1073-// Onscreen annotations
1074-OAPIFUNC NOTEHANDLE oapiCreateAnnotation (bool exclusive, double size, const VECTOR3 &col);
1075-OAPIFUNC bool oapiDelAnnotation (NOTEHANDLE hNote);
1076-OAPIFUNC void oapiAnnotationSetPos (NOTEHANDLE hNote, double x1, double y1, double x2, double y2);
1077-OAPIFUNC void oapiAnnotationSetText (NOTEHANDLE hNote, char *note);
1078-
1079-// Debugging functions
1080-OAPIFUNC char *oapiDebugString ();
1081-OAPIFUNC void oapiSetTimeSteppingDebug (double step);
1082-
1083-// ======================================================================
1084-// keyboard key identifiers
1085-// ======================================================================
1086-
1087-#define OAPI_KEY_ESCAPE 0x01
1088-#define OAPI_KEY_1 0x02
1089-#define OAPI_KEY_2 0x03
1090-#define OAPI_KEY_3 0x04
1091-#define OAPI_KEY_4 0x05
1092-#define OAPI_KEY_5 0x06
1093-#define OAPI_KEY_6 0x07
1094-#define OAPI_KEY_7 0x08
1095-#define OAPI_KEY_8 0x09
1096-#define OAPI_KEY_9 0x0A
1097-#define OAPI_KEY_0 0x0B
1098-#define OAPI_KEY_MINUS 0x0C // on main keyboard
1099-#define OAPI_KEY_EQUALS 0x0D
1100-#define OAPI_KEY_BACK 0x0E // backspace
1101-#define OAPI_KEY_TAB 0x0F
1102-#define OAPI_KEY_Q 0x10
1103-#define OAPI_KEY_W 0x11
1104-#define OAPI_KEY_E 0x12
1105-#define OAPI_KEY_R 0x13
1106-#define OAPI_KEY_T 0x14
1107-#define OAPI_KEY_Y 0x15
1108-#define OAPI_KEY_U 0x16
1109-#define OAPI_KEY_I 0x17
1110-#define OAPI_KEY_O 0x18
1111-#define OAPI_KEY_P 0x19
1112-#define OAPI_KEY_LBRACKET 0x1A
1113-#define OAPI_KEY_RBRACKET 0x1B
1114-#define OAPI_KEY_RETURN 0x1C // Enter on main keyboard
1115-#define OAPI_KEY_LCONTROL 0x1D
1116-#define OAPI_KEY_A 0x1E
1117-#define OAPI_KEY_S 0x1F
1118-#define OAPI_KEY_D 0x20
1119-#define OAPI_KEY_F 0x21
1120-#define OAPI_KEY_G 0x22
1121-#define OAPI_KEY_H 0x23
1122-#define OAPI_KEY_J 0x24
1123-#define OAPI_KEY_K 0x25
1124-#define OAPI_KEY_L 0x26
1125-#define OAPI_KEY_SEMICOLON 0x27
1126-#define OAPI_KEY_APOSTROPHE 0x28
1127-#define OAPI_KEY_GRAVE 0x29 // accent grave
1128-#define OAPI_KEY_LSHIFT 0x2A
1129-#define OAPI_KEY_BACKSLASH 0x2B
1130-#define OAPI_KEY_Z 0x2C
1131-#define OAPI_KEY_X 0x2D
1132-#define OAPI_KEY_C 0x2E
1133-#define OAPI_KEY_V 0x2F
1134-#define OAPI_KEY_B 0x30
1135-#define OAPI_KEY_N 0x31
1136-#define OAPI_KEY_M 0x32
1137-#define OAPI_KEY_COMMA 0x33
1138-#define OAPI_KEY_PERIOD 0x34 // . on main keyboard
1139-#define OAPI_KEY_SLASH 0x35 // / on main keyboard
1140-#define OAPI_KEY_RSHIFT 0x36
1141-#define OAPI_KEY_MULTIPLY 0x37 // * on numeric keypad
1142-#define OAPI_KEY_LALT 0x38 // left Alt
1143-#define OAPI_KEY_SPACE 0x39
1144-#define OAPI_KEY_CAPITAL 0x3A // caps lock key
1145-#define OAPI_KEY_F1 0x3B
1146-#define OAPI_KEY_F2 0x3C
1147-#define OAPI_KEY_F3 0x3D
1148-#define OAPI_KEY_F4 0x3E
1149-#define OAPI_KEY_F5 0x3F
1150-#define OAPI_KEY_F6 0x40
1151-#define OAPI_KEY_F7 0x41
1152-#define OAPI_KEY_F8 0x42
1153-#define OAPI_KEY_F9 0x43
1154-#define OAPI_KEY_F10 0x44
1155-#define OAPI_KEY_NUMLOCK 0x45
1156-#define OAPI_KEY_SCROLL 0x46 // Scroll lock
1157-#define OAPI_KEY_NUMPAD7 0x47
1158-#define OAPI_KEY_NUMPAD8 0x48
1159-#define OAPI_KEY_NUMPAD9 0x49
1160-#define OAPI_KEY_SUBTRACT 0x4A // - on numeric keypad
1161-#define OAPI_KEY_NUMPAD4 0x4B
1162-#define OAPI_KEY_NUMPAD5 0x4C
1163-#define OAPI_KEY_NUMPAD6 0x4D
1164-#define OAPI_KEY_ADD 0x4E // + on numeric keypad
1165-#define OAPI_KEY_NUMPAD1 0x4F
1166-#define OAPI_KEY_NUMPAD2 0x50
1167-#define OAPI_KEY_NUMPAD3 0x51
1168-#define OAPI_KEY_NUMPAD0 0x52
1169-#define OAPI_KEY_DECIMAL 0x53 // . on numeric keypad
1170-#define OAPI_KEY_OEM_102 0x56 // | < > on UK/German keyboards
1171-#define OAPI_KEY_F11 0x57
1172-#define OAPI_KEY_F12 0x58
1173-#define OAPI_KEY_NUMPADENTER 0x9C // Enter on numeric keypad
1174-#define OAPI_KEY_RCONTROL 0x9D // right Control key
1175-#define OAPI_KEY_DIVIDE 0xB5 // / on numeric keypad
1176-#define OAPI_KEY_RALT 0xB8 // right Alt
1177-#define OAPI_KEY_HOME 0xC7 // Home on cursor keypad
1178-#define OAPI_KEY_UP 0xC8 // up-arrow on cursor keypad
1179-#define OAPI_KEY_PRIOR 0xC9 // PgUp on cursor keypad
1180-#define OAPI_KEY_LEFT 0xCB // left-arrow on cursor keypad
1181-#define OAPI_KEY_RIGHT 0xCD // right-arrow on cursor keypad
1182-#define OAPI_KEY_END 0xCF // End on cursor keypad
1183-#define OAPI_KEY_DOWN 0xD0 // down-arrow on cursor keypad
1184-#define OAPI_KEY_NEXT 0xD1 // PgDn on cursor keypad
1185-#define OAPI_KEY_INSERT 0xD2 // Insert on cursor keypad
1186-#define OAPI_KEY_DELETE 0xD3 // Delete on cursor keypad
1187-
1188-#define KEYDOWN(buf,key) (buf[key] & 0x80)
1189-#define RESETKEY(buf,key) (buf[key] = 0)
1190-
1191-#define KEYMOD_LSHIFT(buf) (KEYDOWN(buf,OAPI_KEY_LSHIFT))
1192-#define KEYMOD_RSHIFT(buf) (KEYDOWN(buf,OAPI_KEY_RSHIFT))
1193-#define KEYMOD_SHIFT(buf) (KEYMOD_LSHIFT(buf) || KEYMOD_RSHIFT(buf))
1194-#define KEYMOD_LCONTROL(buf) (KEYDOWN(buf,OAPI_KEY_LCONTROL))
1195-#define KEYMOD_RCONTROL(buf) (KEYDOWN(buf,OAPI_KEY_RCONTROL))
1196-#define KEYMOD_CONTROL(buf) (KEYMOD_LCONTROL(buf) || KEYMOD_RCONTROL(buf))
1197-#define KEYMOD_LALT(buf) (KEYDOWN(buf,OAPI_KEY_LALT))
1198-#define KEYMOD_RALT(buf) (KEYDOWN(buf,OAPI_KEY_RALT))
1199-#define KEYMOD_ALT(buf) (KEYMOD_LALT(buf) || KEYMOD_RALT(buf))
1200-
1201-// ======================================================================
1202-// Logical key ids
1203-// ======================================================================
1204-
1205-#define OAPI_LKEY_CockpitRotateLeft 0
1206-#define OAPI_LKEY_CockpitRotateRight 1
1207-#define OAPI_LKEY_CockpitRotateUp 2
1208-#define OAPI_LKEY_CockpitRotateDown 3
1209-#define OAPI_LKEY_CockpitDontLean 4
1210-#define OAPI_LKEY_CockpitLeanForward 5
1211-#define OAPI_LKEY_CockpitLeanLeft 6
1212-#define OAPI_LKEY_CockpitLeanRight 7
1213-#define OAPI_LKEY_CockpitResetCam 8
1214-#define OAPI_LKEY_PanelShiftLeft 9
1215-#define OAPI_LKEY_PanelShiftRight 10
1216-#define OAPI_LKEY_PanelShiftUp 11
1217-#define OAPI_LKEY_PanelShiftDown 12
1218-#define OAPI_LKEY_PanelSwitchLeft 13
1219-#define OAPI_LKEY_PanelSwitchRight 14
1220-#define OAPI_LKEY_PanelSwitchUp 15
1221-#define OAPI_LKEY_PanelSwitchDown 16
1222-#define OAPI_LKEY_TrackRotateLeft 17
1223-#define OAPI_LKEY_TrackRotateRight 18
1224-#define OAPI_LKEY_TrackRotateUp 19
1225-#define OAPI_LKEY_TrackRotateDown 20
1226-#define OAPI_LKEY_TrackAdvance 21
1227-#define OAPI_LKEY_TrackRetreat 22
1228-#define OAPI_LKEY_GroundTiltLeft 23
1229-#define OAPI_LKEY_GroundTiltRight 24
1230-#define OAPI_LKEY_GroundTiltUp 25
1231-#define OAPI_LKEY_GroundTiltDown 26
1232-#define OAPI_LKEY_IncMainThrust 27 // +-
1233-#define OAPI_LKEY_DecMainThrust 28 // |
1234-#define OAPI_LKEY_KillMainRetro 29 // |
1235-#define OAPI_LKEY_FullMainThrust 30 // | Main/retro/hover engine control
1236-#define OAPI_LKEY_FullRetroThrust 31 // |
1237-#define OAPI_LKEY_IncHoverThrust 32 // |
1238-#define OAPI_LKEY_DecHoverThrust 33 // +-
1239-#define OAPI_LKEY_RCSEnable 34
1240-#define OAPI_LKEY_RCSMode 35
1241-#define OAPI_LKEY_RCSPitchUp 36 // +-
1242-#define OAPI_LKEY_RCSPitchDown 37 // |
1243-#define OAPI_LKEY_RCSYawLeft 38 // | Reaction control
1244-#define OAPI_LKEY_RCSYawRight 39 // | (rotational mode)
1245-#define OAPI_LKEY_RCSBankLeft 40 // |
1246-#define OAPI_LKEY_RCSBankRight 41 // +-
1247-#define OAPI_LKEY_RCSUp 42 // +-
1248-#define OAPI_LKEY_RCSDown 43 // |
1249-#define OAPI_LKEY_RCSLeft 44 // | Reaction control
1250-#define OAPI_LKEY_RCSRight 45 // | (linear mode)
1251-#define OAPI_LKEY_RCSForward 46 // |
1252-#define OAPI_LKEY_RCSBack 47 // +-
1253-#define OAPI_LKEY_LPRCSPitchUp 48 // +-
1254-#define OAPI_LKEY_LPRCSPitchDown 49 // |
1255-#define OAPI_LKEY_LPRCSYawLeft 50 // | Reaction control - low power
1256-#define OAPI_LKEY_LPRCSYawRight 51 // | (rotational mode)
1257-#define OAPI_LKEY_LPRCSBankLeft 52 // |
1258-#define OAPI_LKEY_LPRCSBankRight 53 // +-
1259-#define OAPI_LKEY_LPRCSUp 54 // +-
1260-#define OAPI_LKEY_LPRCSDown 55 // |
1261-#define OAPI_LKEY_LPRCSLeft 56 // | Reaction control - low power
1262-#define OAPI_LKEY_LPRCSRight 57 // | (linear mode)
1263-#define OAPI_LKEY_LPRCSForward 58 // |
1264-#define OAPI_LKEY_LPRCSBack 59 // +-
1265-#define OAPI_LKEY_NMHoldAltitude 60 // +-
1266-#define OAPI_LKEY_NMHLevel 61 // |
1267-#define OAPI_LKEY_NMPrograde 62 // |
1268-#define OAPI_LKEY_NMRetrograde 63 // | Navigation computer modes
1269-#define OAPI_LKEY_NMNormal 64 // |
1270-#define OAPI_LKEY_NMAntinormal 65 // |
1271-#define OAPI_LKEY_NMKillrot 66 // +-
1272-#define OAPI_LKEY_Undock 67
1273-#define OAPI_LKEY_IncElevatorTrim 68
1274-#define OAPI_LKEY_DecElevatorTrim 69
1275-#define OAPI_LKEY_WheelbrakeLeft 70
1276-#define OAPI_LKEY_WheelbrakeRight 71
1277-#define OAPI_LKEY_HUD 72
1278-#define OAPI_LKEY_HUDMode 73
1279-#define OAPI_LKEY_HUDReference 74
1280-#define OAPI_LKEY_HUDTarget 75
1281-#define OAPI_LKEY_HUDColour 76
1282-#define OAPI_LKEY_IncSimSpeed 77
1283-#define OAPI_LKEY_DecSimSpeed 78
1284-#define OAPI_LKEY_IncFOV 79
1285-#define OAPI_LKEY_DecFOV 80
1286-#define OAPI_LKEY_MainMenu 81
1287-#define OAPI_LKEY_DlgHelp 82
1288-#define OAPI_LKEY_DlgCamera 83
1289-#define OAPI_LKEY_DlgSimspeed 84
1290-#define OAPI_LKEY_DlgCustomCmd 85
1291-#define OAPI_LKEY_DlgVisHelper 86
1292-#define OAPI_LKEY_DlgRecorder 87
1293-#define OAPI_LKEY_DlgInfo 88
1294-#define OAPI_LKEY_DlgMap 89
1295-#define OAPI_LKEY_DlgNavaid 90
1296-#define OAPI_LKEY_ToggleInfo 91
1297-#define OAPI_LKEY_ToggleFPS 92
1298-#define OAPI_LKEY_ToggleCamInternal 93
1299-#define OAPI_LKEY_ToggleTrackMode 94
1300-#define OAPI_LKEY_TogglePanelMode 95
1301-#define OAPI_LKEY_TogglePlanetarium 96
1302-#define OAPI_LKEY_ToggleRecPlay 97
1303-#define LKEY_COUNT 98
1304-
1305-// ======================================================================
1306-// Some helper functions
1307-// ======================================================================
1308-
1309-inline VECTOR3 _V(double x, double y, double z)
1310-{
1311- VECTOR3 vec = {x,y,z}; return vec;
1312-}
1313-
1314-inline void veccpy (VECTOR3 &a, const VECTOR3 &b)
1315-{
1316- a.x = b.x;
1317- a.y = b.y;
1318- a.z = b.z;
1319-}
1320-
1321-inline VECTOR3 operator+ (const VECTOR3 &a, const VECTOR3 &b)
1322-{
1323- VECTOR3 c;
1324- c.x = a.x+b.x;
1325- c.y = a.y+b.y;
1326- c.z = a.z+b.z;
1327- return c;
1328-}
1329-
1330-inline VECTOR3 operator- (const VECTOR3 &a, const VECTOR3 &b)
1331-{
1332- VECTOR3 c;
1333- c.x = a.x-b.x;
1334- c.y = a.y-b.y;
1335- c.z = a.z-b.z;
1336- return c;
1337-}
1338-
1339-inline VECTOR3 operator* (const VECTOR3 &a, const double f)
1340-{
1341- VECTOR3 c;
1342- c.x = a.x*f;
1343- c.y = a.y*f;
1344- c.z = a.z*f;
1345- return c;
1346-}
1347-
1348-inline VECTOR3 operator/ (const VECTOR3 &a, const double f)
1349-{
1350- VECTOR3 c;
1351- c.x = a.x/f;
1352- c.y = a.y/f;
1353- c.z = a.z/f;
1354- return c;
1355-}
1356-
1357-inline VECTOR3 &operator+= (VECTOR3 &a, const VECTOR3 &b)
1358-{
1359- a.x += b.x;
1360- a.y += b.y;
1361- a.z += b.z;
1362- return a;
1363-}
1364-
1365-inline VECTOR3 &operator-= (VECTOR3 &a, const VECTOR3 &b)
1366-{
1367- a.x -= b.x;
1368- a.y -= b.y;
1369- a.z -= b.z;
1370- return a;
1371-}
1372-
1373-inline VECTOR3 &operator*= (VECTOR3 &a, const double f)
1374-{
1375- a.x *= f;
1376- a.y *= f;
1377- a.z *= f;
1378- return a;
1379-}
1380-
1381-inline VECTOR3 &operator/= (VECTOR3 &a, const double f)
1382-{
1383- a.x /= f;
1384- a.y /= f;
1385- a.z /= f;
1386- return a;
1387-}
1388-
1389-inline VECTOR3 operator- (const VECTOR3 &a)
1390-{
1391- VECTOR3 c;
1392- c.x = -a.x;
1393- c.y = -a.y;
1394- c.z = -a.z;
1395- return c;
1396-}
1397-
1398-inline double dotp (const VECTOR3 &a, const VECTOR3 &b)
1399-{
1400- return a.x*b.x + a.y*b.y + a.z*b.z;
1401-}
1402-
1403-inline VECTOR3 crossp (const VECTOR3 &a, const VECTOR3 &b)
1404-{
1405- return _V(a.y*b.z - b.y*a.z, a.z*b.x - b.z*a.x, a.x*b.y - b.x*a.y);
1406-}
1407-
1408-inline double length (const VECTOR3 &a)
1409-{
1410- return sqrt (a.x*a.x + a.y*a.y + a.z*a.z);
1411-}
1412-
1413-inline double dist (const VECTOR3 &a, const VECTOR3 &b)
1414-{
1415- return length (a-b);
1416-}
1417-
1418-inline MATRIX3 _M(double m11, double m12, double m13,
1419- double m21, double m22, double m23,
1420- double m31, double m32, double m33)
1421-{
1422- MATRIX3 mat = {m11,m12,m13, m21,m22,m23, m31,m32,m33};
1423- return mat;
1424-}
1425-
1426-inline VECTOR3 mul (const MATRIX3 &A, const VECTOR3 &b)
1427-{
1428- return _V (
1429- A.m11*b.x + A.m12*b.y + A.m13*b.z,
1430- A.m21*b.x + A.m22*b.y + A.m23*b.z,
1431- A.m31*b.x + A.m32*b.y + A.m33*b.z);
1432-}
1433-
1434-inline VECTOR3 tmul (const MATRIX3 &A, const VECTOR3 &b)
1435-{
1436- return _V (
1437- A.m11*b.x + A.m21*b.y + A.m31*b.z,
1438- A.m12*b.x + A.m22*b.y + A.m32*b.z,
1439- A.m13*b.x + A.m23*b.y + A.m33*b.z);
1440-}
1441-
1442-inline MATRIX3 mul (const MATRIX3 &A, const MATRIX3 &B)
1443-{
1444- MATRIX3 mat = {
1445- A.m11*B.m11 + A.m12*B.m21 + A.m13*B.m31, A.m11*B.m12 + A.m12*B.m22 + A.m13*B.m32, A.m11*B.m13 + A.m12*B.m23 + A.m13*B.m33,
1446- A.m21*B.m11 + A.m22*B.m21 + A.m23*B.m31, A.m21*B.m12 + A.m22*B.m22 + A.m23*B.m32, A.m21*B.m13 + A.m22*B.m23 + A.m23*B.m33,
1447- A.m31*B.m11 + A.m32*B.m21 + A.m33*B.m31, A.m31*B.m12 + A.m32*B.m22 + A.m33*B.m32, A.m31*B.m13 + A.m32*B.m23 + A.m33*B.m33
1448- };
1449- return mat;
1450-}
1451-
1452-inline RECT _R (int left, int top, int right, int bottom)
1453-{
1454- RECT r = { left, top, right, bottom }; return r;
1455-}
1456-
1457-inline VECTOR3 POINTERTOREF (VECTOR3 *p)
1458-{
1459- VECTOR3 v;
1460- v.x = DBL_MAX; // flag
1461- *((VECTOR3**)&v.z) = p; // address
1462- v.z = 0.0;
1463- return v;
1464-}
1465-
1466-// ======================================================================
1467-// Internal data structures
1468-// ======================================================================
1469-
1470-#ifdef ORBITER_MODULE
1471-void dummy();
1472-void calldummy () { dummy(); }
1473-#endif
1474-
1475-#endif // !__ORBITERAPI_H
\ No newline at end of file
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/include/VesselAPI.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Orbitersdk/include/VesselAPI.h Mon Feb 21 22:48:14 2011 +0100
@@ -0,0 +1,6007 @@
1+// ======================================================================
2+// ORBITER SOFTWARE DEVELOPMENT KIT
3+// Copyright (C) 2001-2010 Martin Schweiger
4+// All rights reserved
5+// VesselAPI.h
6+// - VESSEL class interface
7+// - VESSEL2 class extensions
8+// - VESSEL3 class extensions
9+// ======================================================================
10+
11+/**
12+ * \file VesselAPI.h
13+ * \brief Contains the class interfaces for vessel objects
14+ * (VESSEL, VESSEL2, VESSEL3).
15+ */
16+
17+#ifndef __VESSELAPI_H
18+#define __VESSELAPI_H
19+
20+// reference frame flags
21+#define FRAME_ECL 0
22+#define FRAME_EQU 1
23+
24+class Vessel; // Orbiter internal vessel class
25+
26+// ======================================================================
27+/**
28+ * \brief Base class for objects of vessel type (spacecraft and similar)
29+
30+ * %VESSEL is the base class for addon modules of 'vessel' type (spacecraft,
31+ * space stations, satellites, deep space probes, etc.)
32+ * This class defines the interface between the module's vessel definition
33+ * and the parameters maintained internally by Orbiter to define the vessel
34+ * state.
35+ * It provides access to the various status parameters and methods of
36+ * individual spacecraft.
37+ *
38+ * It is important to note that a %VESSEL instance represents an \e interface
39+ * to an existing vessel in Orbiter, rather than the vessel itself. Vessels
40+ * can exist without a corresponding %VESSEL instance, and deleting a
41+ * %VESSEL instance does not delete the vessel.
42+ *
43+ * Most of the methods provided by the %VESSEL class are of 'get' and 'set'
44+ * type, i.e. for retrieving vessel parameter states, or modifying them.
45+ * It does \e not define any callback functions that Orbiter uses to notify
46+ * the vessel of events. These are implemented in the VESSEL2 class (derived
47+ * from %VESSEL). The latest version of the interface is VESSEL3, which
48+ * implements additional functions. User-defined vessel casses should therefore
49+ * be derived from %VESSEL3 instead of %VESSEL.
50+ *
51+ * For complete vessel module implementations, see the examples in
52+ * Orbitersdk\\samples, for example Orbitersdk\\samples\\ShuttlePB.
53+ * \nosubgrouping
54+ */
55+// ======================================================================
56+
57+class OAPIFUNC VESSEL {
58+public:
59+ /// \name Construction/creation, handles and interfaces
60+ //@{
61+ /**
62+ * \brief Creates a %VESSEL interface instance from a vessel handle.
63+ * \param hVessel vessel handle
64+ * \param fmodel level of realism requested (0=simple, 1=realistic)
65+ * \note This function creates an interface to an \e existing vessel. It
66+ * does not create a new vessel. New vessels are created with the
67+ * \ref oapiCreateVessel and \ref oapiCreateVesselEx functions.
68+ * \note The %VESSEL constructor (or the constructor of a derived
69+ * specialised vessel class) will normally be invoked in the ovcInit
70+ * callback function of a vessel module:
71+ * \code
72+ * class MyVessel: public VESSEL
73+ * {
74+ * // MyVessel interface definition
75+ * };
76+ *
77+ * DLLCLBK VESSEL *ovcInit (OBJHANDLE hvessel, int flightmodel)
78+ * {
79+ * return new MyVessel (hvessel, flightmodel);
80+ * }
81+ *
82+ * DLLCLBK void ovcExit (VESSEL *vessel)
83+ * {
84+ * delete (MyVessel*)vessel;
85+ * }
86+ * \endcode
87+ * \note The %VESSEL interface instance created in ovcInit should be
88+ * deleted in ovcExit.
89+ * \sa oapiCreateVessel, oapiCreateVesselEx, ovcInit
90+ */
91+ VESSEL (OBJHANDLE hVessel, int fmodel = 1);
92+
93+ /**
94+ * \brief Returns the version number of the vessel interface class.
95+ * \return version number
96+ * \note The following interface versions are currently in use:
97+ * - class VESSEL: version 0
98+ * - class VESSEL2: version 1
99+ * - class VESSEL3: version 2
100+ * \sa VESSEL2, VESSEL3
101+ */
102+ inline int Version () const { return version; }
103+
104+ /**
105+ * \brief Returns a handle to the vessel object.
106+ * \return vessel handle, as passed to the VESSEL constructor.
107+ * \note The handle is useful for various vessel-related API function calls.
108+ */
109+ const OBJHANDLE GetHandle () const;
110+
111+ /**
112+ * \brief Returns the file name of the DLL containing the vessel's
113+ * scenario editor extensions.
114+ * \param [out] fname module file name
115+ * \return \e true if the vessel defines an editor module,
116+ * \e false otherwise.
117+ * \note The vessel's editor module, if it exists, contains extensions
118+ * for the <i>Scenario editor</i> module that allows the user to
119+ * set vessel-specific parameters (see Doc\ScenarioEditor.pdf).
120+ * \note The string returned by this method is identical to the
121+ * \e EditorModule entry in the vessel's configuration file.
122+ * \note If the \e EditorModule entry is not found in the configuration
123+ * file, this method returns \e false.
124+ */
125+ bool GetEditorModule (char *fname) const;
126+ //@}
127+
128+ /// \name General vessel properties
129+ //@{
130+ /**
131+ * \brief Returns the vessel's name.
132+ * \return Pointer to vessel's name
133+ * \sa GetClassName
134+ */
135+ char *GetName () const;
136+
137+ /**
138+ * \brief Returns the vessel's class name.
139+ * \return Pointer to vessel's class name.
140+ * \sa GetName
141+ */
142+#ifdef USESDOTNETWORKAROUNDS
143+ char *GetClassNameA (void) const;
144+#else
145+ char *GetClassName (void) const;
146+#endif
147+
148+ /**
149+ * \brief Returns the requested realism level for the flight model.
150+ * \return Flight model realism level. These values are currently
151+ * supported:
152+ * - 0 = simple
153+ * - 1 = realistic
154+ * \note The returned value corresponds to that passed to the VESSEL
155+ * constructor. This will normally be the same as the argument of the
156+ * ovcInit callback function.
157+ * \note The module can use this method to implement different flavours of
158+ * the flight model (e.g. simplified and realistic), by defining
159+ * separate sets of parameters (possibly higher fuel-specific impulse
160+ * and higher thrust ratings in the simplified model, less severe
161+ * damage limits, etc.)
162+ * \sa ovcInit, GetDamageModel
163+ */
164+ int GetFlightModel () const;
165+
166+ /**
167+ * \brief Returns the current user setting for damage and systems
168+ * failure simulation.
169+ * \return Damage modelling flags. The following settings are currently
170+ * supported:
171+ * - 0 = no damage or failures
172+ * - 1 = simulate vessel damage and system failures
173+ * \note The return value depends on the user parameter selection in the
174+ * Launchpad dialog. It does not change during a simulation session
175+ * and will be the same for all vessels.
176+ * \note Future versions may support more differentiated bit flags to
177+ * indicate different types of damage and failure simulation.
178+ * \note A vessel implementation should query the damage flag to decide
179+ * whether to simulate failures.
180+ * \sa GetFlightModel
181+ */
182+ int GetDamageModel () const;
183+
184+ /**
185+ * \brief Returns true if the vessel can receive the input focus, false
186+ * otherwise.
187+ * \return Focus enabled status.
188+ * \note The vessel can be allowed or prohibited to receive the input focus
189+ * by using the SetEnableFocus method.
190+ * \note The initial state is defined by the EnableFocus setting in the
191+ * vessel's configuration file. If the entry is missing, the default
192+ * is true.
193+ * \note Focus-enabled vessels can be selected by the user via the jump
194+ * vessel dialog (F3).
195+ * \note Once a vessel has received the input focus, all user input via
196+ * keyboard, mouse and joystick is directed to this vessel.
197+ * \note For some object types, such as jettisoned rocket stages, enabling
198+ * input focus may not be useful.
199+ * \sa SetEnableFocus, clbkFocusChanged, oapiGetFocusObject,
200+ * oapiSetFocusObject
201+ */
202+ bool GetEnableFocus () const;
203+
204+ /**
205+ * \brief Enable or disable the vessel's ability to receive the input
206+ * focus.
207+ * \param enable focus enabled status: true to to allow the vessel to
208+ * receive input focus, false otherwise.
209+ * \note The initial state is defined by the EnableFocus setting in the
210+ * vessel's configuration file. If the entry is missing, the default
211+ * is true.
212+ * \note If the input focus of the current focus vessel is disabled, it
213+ * will continue to receive user input, until the focus is switched
214+ * to another vessel.
215+ * \note Focus-enabled vessels can be selected by the user via the jump
216+ * vessel dialog (F3).
217+ * \note Once a vessel has received the input focus, all user input via
218+ * keyboard, mouse and joystick is directed to this vessel.
219+ * \note For some object types, such as jettisoned rocket stages, enabling
220+ * input focus may not be useful.
221+ * \sa GetEnableFocus, clbkFocusChanged, oapiGetFocusObject,
222+ * oapiSetFocusObject
223+ */
224+ void SetEnableFocus (bool enable) const;
225+
226+ /**
227+ * \brief Returns the vessel's mean radius.
228+ * \return Vessel mean radius [m].
229+ * \note The value returned is that set by a previous call to SetSize or
230+ * from the Size entry in the vessel's configuration file.
231+ * \note There is no guarantee that the return value is correlated to the
232+ * vessel's visual representation. In particular, the size parameter
233+ * does not change (scale) the visual appearance.
234+ * \sa SetSize
235+ */
236+ double GetSize () const;
237+
238+ /**
239+ * \brief Set the vessel's mean radius.
240+ * \param size vessel mean radius [m].
241+ * \note The size should correspond to the vessel's visual representation,
242+ * for example the mesh used to show the vessel in the simulation
243+ * window.
244+ * \note The size parameter is used by Orbiter to determine the camera
245+ * distance at which the vessel is within visual range of the
246+ * observer camera. It is also used for calculating various physical
247+ * parameters.
248+ * \note If SetSize is not called during the vessel setup, the value from
249+ * the Size entry in the vessel's configuration file is used.
250+ * \sa GetSize
251+ */
252+ void SetSize (double size) const;
253+
254+ /**
255+ * \brief Defines the vessel's range of visibility.
256+ * \param vislimit apparent size limit for vessel visibility
257+ * \param spotlimit apparent size limit for vessel "spot"
258+ * representation.
259+ * \note This function can be used to define the distance up to which a
260+ * vessel is visible, independent of screen resolution.
261+ * \note The vislimit value is the limiting apparent size (as a fraction of
262+ * the render window vertical) up to which the vessel is regarded
263+ * visible. Thus, the vessel is visible if the following condition is
264+ * satisfied: \f$S (d \tan a)^{-1} > vislimit\f$
265+ * where S is the vessel size, d is its camera distance, and a is the
266+ * camera aperture.
267+ * \note If the defined visibility limit exceeds the distance at which the
268+ * vessel can be rendered as a mesh at the given screen resolution,
269+ * it will simply be represented by a circular spot whose size is
270+ * reduced linearly (to reach zero at the limiting distance).
271+ * \note If the vessel is to be visible beyond its geometric size (e.g. due
272+ * to light beacons etc.) then the spotlimit value can be used to
273+ * define the limiting distance due to the vessel's geometry, while
274+ * vislimit defines the total visibility range including all
275+ * enhancing factors such as beacons.
276+ * \note spotlimit <= vislimit is required. If spotlimit < 0 (default),
277+ * then spotlimit = vislimit is assumed.
278+ * \note If SetVisibilityLimit is not called, then the default value is
279+ * vislimit = spotlimit = 1e-3.
280+ * \sa SetSize, SetClipRadius
281+ */
282+ void SetVisibilityLimit (double vislimit, double spotlimit = -1) const;
283+
284+ /**
285+ * \brief Returns the radius of the vessel's circumscribing sphere.
286+ * \return Radius of the circumscribing sphere of the vessel's visual
287+ * representation [m].
288+ * \note This parameter describes the radius of the sphere around the
289+ * vessel that is protected from clipping at the observer camera's
290+ * near clipping plane. (The near clipping plane defines an area
291+ * around the view camera within which no objects are rendered. The
292+ * distance of the near clipping plane cannot be made arbitrarily
293+ * small for technical reasons.)
294+ * \note By default, the clip radius is identical to the vessel's "Size"
295+ * parameter. However, the size parameter is correlated to physical
296+ * vessel properties and may therefore be smaller than the sphere
297+ * that contains the vessel's complete visual representation. In that
298+ * case, defining a clip radius that is larger than the size
299+ * parameter can avoid visual artefacts.
300+ * \note The view camera's near clip plane distance is adjusted so that it
301+ * does not intersect any nearby vessel's clip radius. However, there
302+ * is a minimum near clip distance of 2.5m. This means that if the
303+ * camera approaches a vessel to less than clip radius + 2.5,
304+ * clipping may still occur.
305+ * \note Visual cockpit meshes are rendered in a separate pass and are not
306+ * affected by the general near clip distance (they have a separate
307+ * near clip distance of 10cm).
308+ * \sa SetClipRadius, GetSize
309+ */
310+ double GetClipRadius () const;
311+
312+ /**
313+ * \brief Set the average colour distribution reflected by
314+ * the vessel.
315+ * \param albedo vessel colour vector (red, green blue), range [0..1]
316+ * for each component.
317+ * \note The colour passed to this function is currently used to define
318+ * the "spot" colour with which the vessel is rendered at long distances.
319+ * It should represent an average colour and brightness of the vessel
320+ * surface when fully lit.
321+ * \note The values for each of the RGB components should be in the range 0-1.
322+ * \note The default vessel albedo is bright white (1,1,1).
323+ * \note The albedo can be overridden by the AlbedoRGB entry in the
324+ * vessel's config file.
325+ */
326+ void SetAlbedoRGB (const VECTOR3 &albedo) const;
327+
328+ /**
329+ * \brief Set the radius of the vessel's circumscribing sphere.
330+ * \param rad Radius of the circumscribing sphere of the vessel's
331+ * visual representation [m].
332+ * \note
333+ * \note This parameter describes the radius of the sphere around the
334+ * vessel that is protected from clipping at the observer camera's
335+ * near clipping plane. (The near clipping plane defines an area
336+ * around the view camera within which no objects are rendered. The
337+ * distance of the near clipping plane cannot be made arbitrarily
338+ * small for technical reasons.)
339+ * \note By default, the clip radius is identical to the vessel's "Size"
340+ * parameter. However, the size parameter is correlated to physical
341+ * vessel properties and may therefore be smaller than the sphere
342+ * that contains the vessel's complete visual representation. In that
343+ * case, defining a clip radius that is larger than the size
344+ * parameter can avoid visual artefacts.
345+ * \note The view camera's near clip plane distance is adjusted so that it
346+ * does not intersect any nearby vessel's clip radius. However, there
347+ * is a minimum near clip distance of 2.5m. This means that if the
348+ * camera approaches a vessel to less than clip radius + 2.5,
349+ * clipping may still occur.
350+ * \note Visual cockpit meshes are rendered in a separate pass and are not
351+ * affected by the general near clip distance (they have a separate
352+ * near clip distance of 10cm).
353+ * \note Setting rad = 0 reverts to the default behaviour of using the
354+ * vessel's "Size" parameter to determine the clip radius.
355+ * \sa GetClipRadius, SetSize
356+ */
357+ void SetClipRadius (double rad) const;
358+
359+ /**
360+ * \brief Returns the vessel's empty mass (excluding propellants).
361+ * \return Vessel empty mass [kg].
362+ * \note The empty mass combines all parts of the vessel except propellant
363+ * resources defined via CreatePropellantResource.
364+ * \note The empty mass may change during the simulation, often
365+ * discontinuously, for example as a result of stage separation.
366+ * \sa oapiGetEmptyMass, GetMassDistribution, SetEmptyMass,
367+ * CreatePropellantResource
368+ */
369+ double GetEmptyMass () const;
370+
371+ /**
372+ * \brief Set the vessel's empty mass (excluding propellants).
373+ * \param m vessel empty mass [kg].
374+ * \note The empty mass combines all parts of the vessel except propellant
375+ * resources defined via CreatePropellantResource.
376+ * \note Use SetEmptyMass to account for structural changes such as stage
377+ * or booster separation, but not for fuel consumption, which is done
378+ * directly by Orbiter.
379+ * \sa GetEmptyMass, SetMassDistribution, oapiSetEmptyMass,
380+ * CreatePropellantResource
381+ */
382+ void SetEmptyMass (double m) const;
383+
384+ /**
385+ * \brief Elevation of the vessel's centre of gravity (COG) above ground.
386+ * \return Distance of COG from vessel ground contact plane [m].
387+ * \note The COG elevation is defined as the normal distance of the vessel's
388+ * centre of gravity from the ground contact plane defined by its
389+ * three touchdown points.
390+ * \note By definition, the vessel's centre of gravity coincides with the
391+ * origin of the local vessel frame.
392+ * \sa GetTouchdownPoints, SetTouchdownPoints
393+ */
394+ double GetCOG_elev () const;
395+
396+ /**
397+ * \brief Returns the three points defining the vessel's ground contact plane.
398+ * \param pt1 touchdown point of nose wheel (or equivalent)
399+ * \param pt2 touchdown point of left main wheel (or equivalent)
400+ * \param pt3 touchdown point of right main wheel (or equivalent)
401+ * \note The function returns 3 reference points defining the vessel's
402+ * surface contact points when touched down on a planetary surface
403+ * (e.g. landing gear).
404+ * \sa SetTouchdownPoints, GetCOG_elev
405+ */
406+ void GetTouchdownPoints (VECTOR3 &pt1, VECTOR3 &pt2, VECTOR3 &pt3) const;
407+
408+ /**
409+ * \brief Defines the three points defining the vessel's ground contact plane.
410+ * \param pt1 touchdown point of nose wheel (or equivalent)
411+ * \param pt2 touchdown point of left main wheel (or equivalent)
412+ * \param pt3 touchdown point of right main wheel (or equivalent)
413+ * \note The points are the positions at which the vessel's undercarriage
414+ * (or equivalent) touches the surface, specified in local vessel
415+ * coordinates.
416+ * \note The order of points is significant since it defines the direction
417+ * of the normal. The points should be specified such that the cross
418+ * product pt3-pt1 x pt2-pt1 defines the horizon "up" direction for
419+ * the landed vessel (given a left-handed coordinate system).
420+ * \note Modifying the touchdown points during the simulation while the
421+ * vessel is on the ground can result in jumps due to instantaneous
422+ * position changes (infinite acceleration). To avoid this, the
423+ * touchdown points should be modified gradually by small amounts
424+ * over time (proportional to simulation time steps).
425+ * \sa GetTouchdownPoints, GetCOG_elev
426+ */
427+ void SetTouchdownPoints (const VECTOR3 &pt1, const VECTOR3 &pt2, const VECTOR3 &pt3) const;
428+
429+ /**
430+ * \brief Set friction coefficients for ground contact.
431+ * \param mu_lng friction coefficient in longitudinal direction.
432+ * \param mu_lat friction coefficient in lateral direction.
433+ * \note The coefficients of surface friction define the deceleration
434+ * forces during sliding or rolling over a surface. mu_lng is the
435+ * coefficient acting in longitudinal (forward) direction, mu_lat the
436+ * coefficient acting in lateral (sideways) direction. The friction
437+ * forces are proportional to the coefficient and the weight of the
438+ * vessel:
439+ * <center><b>F</b><sub>friction</sub> = mu <b>G</b></center>
440+ * \note The higher the coefficient, the faster the vessel will come to a
441+ * halt.
442+ * \note Typical parameters for a spacecraft equipped with landing wheels
443+ * would be mu_lng = 0.1 and mu_lat = 0.5. If the vessel hasn't got
444+ * wheels, mu_lng = 0.5.
445+ * \note The coefficients should be adjusted for belly landings when the
446+ * landing gear is retracted.
447+ * \note The longitudinal and lateral directions are defined by the
448+ * touchdown points:
449+ * <center><b>s</b><sub>lng</sub> = <b>p</b><sub>0</sub> - (<b>p</b><sub>1</sub>
450+ * + <b>p</b><sub>2</sub>)/2, &nbsp;
451+ * <b>s</b><sub>lat</sub> = <b>p</b><sub>2</sub> - <b>p</b><sub>1</sub></center>
452+ * \sa SetTouchdownPoints
453+ */
454+ void SetSurfaceFrictionCoeff (double mu_lng, double mu_lat) const;
455+
456+ /**
457+ * \brief Returns the vessel's cross sections projected in the
458+ * direction of the vessel's principal axes.
459+ * \param cs vector receiving the cross sections of the vessel's
460+ * projection into the yz, xz and xy planes, respectively
461+ * [<b>m<sup>2</sup></b>]
462+ * \sa SetCrossSections
463+ */
464+ void GetCrossSections (VECTOR3 &cs) const;
465+
466+ /**
467+ * \brief Defines the vessel's cross-sectional areas, projected in the
468+ * directions of the vessel's principal axes.
469+ * \param cs vector of cross-sectional areas of the vessel's projection
470+ * along the x-axis into yz-plane, along the y-axis into the xz-plane,
471+ * and along the z-axis into the xy plane, respectively
472+ * [<b>m<sup>2</sup></b>].
473+ * \sa GetCrossSections
474+ */
475+ void SetCrossSections (const VECTOR3 &cs) const;
476+
477+ /**
478+ * \brief Returns the vessel's mass-normalised principal moments of
479+ * inertia (PMI)
480+ * \param pmi Diagonal elements of the vessel's inertia tensor
481+ * [<b>m<sup>2</sup></b>]
482+ * \note The inertia tensor describes the behaviour of a rigid body
483+ * under angular acceleration. It is the analog of the body's mass in
484+ * the linear case.
485+ * \note The values returned by this function are the diagonal elements
486+ * of the inertia tensor, in the local vessel frame of reference.
487+ * \note Orbiter's definition of PMI is mass-normalised, that is, the
488+ * values are divided by the total vessel mass. The elements of pmi
489+ * have the following meaning:
490+ * \f{eqnarray*}
491+ * \mathrm{pmi}_1 &=& M^{-1} \int \rho(\vec{r})(\vec{r}_y^2 + \vec{r}_z^2) d\vec{r}\\
492+ * \mathrm{pmi}_2 &=& M^{-1} \int \rho(\vec{r})(\vec{r}_z^2 + \vec{r}_x^2) d\vec{r}\\
493+ * \mathrm{pmi}_3 &=& M^{-1} \int \rho(\vec{r})(\vec{r}_x^2 + \vec{r}_y^2) d\vec{r}
494+ * \f}
495+ * \note Orbiter assumes that off-diagonal elements can be neglected,
496+ * that is, that the diagonal elements are the principal moments of
497+ * inertia. This is usually a good approximation when the vessel is
498+ * sufficiently symmetric with respect to its coordinate frame.
499+ * Otherwise, a diagonalisation by rotating the local frame may be
500+ * required.
501+ * \note The shipedit utility in the SDK package allows to calculate
502+ * the inertia tensor from a mesh, assuming a homogeneous mass
503+ * distribution.
504+ * \sa SetPMI
505+ */
506+ void GetPMI (VECTOR3 &pmi) const;
507+
508+ /**
509+ * \brief Set the vessel's mass-normalised principal moments of inertia
510+ * (PMI).
511+ * \param pmi pmi Diagonal elements of the vessel's inertia tensor
512+ * [<b>m<sup>2</sup></b>]
513+ * \note The inertia tensor describes the behaviour of a rigid body
514+ * under angular acceleration.
515+ * \note For more information and a definition of the PMI values, see
516+ * \ref GetPMI.
517+ * \sa GetPMI
518+ */
519+ void SetPMI (const VECTOR3 &pmi) const;
520+
521+ /**
522+ * \brief Returns the vessel's damping coefficient for gravity field
523+ * gradient-induced torque.
524+ * \return Torque damping coefficient (>= 0)
525+ * \note A nonspherical object in an inhomogeneous gravitational field
526+ * experiences a torque. Orbiter calculates this torque with
527+ * \f[
528+ * \vec{M}_G = \frac{3\mu m}{R^3} (\vec{R}_0 \times \vec{L}\vec{R}_0)
529+ * \f]
530+ * where mu = GM, G is the gravity constant, M is the reference body
531+ * mass, m is the vessel mass, R is the distance of the vessel to the
532+ * reference body centre, R0 is the unit vector towards the reference
533+ * body, and L is the mass-normalised inertia tensor (assumed diagonal).
534+ * \note This generates an undamped attitude oscillation in the vessel
535+ * orbiting the reference body.
536+ * \note Damping may occur due to tidal deformation of the vessel,
537+ * movement of liquids (fuel) etc. Orbiter allows to introduce a
538+ * damping term of the form
539+ * \f[
540+ * \vec{M}_D = -\alpha\omega_G
541+ * \f]
542+ * where \f$ \omega_G \f$ is the angular velocity, and
543+ * \f$ \alpha = d m r \f$, with damping coefficient \e d, vessel mass
544+ * \e m and vessel radius \e r.
545+ * \note If gravity gradient torque has been disabled in the launchpad
546+ * dialog, this function always returns 0.
547+ * \sa SetGravityGradientDamping, GetEmptyMass, GetPMI
548+ */
549+ double GetGravityGradientDamping () const;
550+
551+ /**
552+ * \brief Sets the vessel's damping coefficient for gravity field
553+ * gradient-induced torque.
554+ * \param damp Torque damping coefficient.
555+ * \return true if damping coefficient was applied, false if gravity
556+ * gradient torque is disabled.
557+ * \note For a definition of the torque experienced by the vessel in
558+ * an inhomogeneous gravity field, and the damping term that can be
559+ * applied, see \ref GetGravityGradientDamping.
560+ * \note If gravity gradient torque has been disabled in the launchpad
561+ * dialog, this function returns false and has no other effect.
562+ * \sa GetGravityGradientDamping, SetEmptyMass, SetPMI
563+ */
564+ bool SetGravityGradientDamping (double damp) const;
565+ //@}
566+
567+ /// \name Vessel state
568+ //@{
569+ /**
570+ * \brief Returns the vessel's current status parameters in a
571+ * VESSELSTATUS structure.
572+ * \param status structure receiving the current vessel status.
573+ * \note The VESSELSTATUS structure provides only limited information.
574+ * Applications should normally use GetStatusEx to obtain a
575+ * VESSELSTATUSx structure which contains additional parameters.
576+ * \sa VESSELSTATUS, GetStatusEx
577+ */
578+ void GetStatus (VESSELSTATUS &status) const;
579+
580+ /**
581+ * \brief Returns the vessel's current status parameters in a
582+ * VESSELSTATUSx structure (version x >= 2).
583+ * \param status pointer to a VESSELSTATUSx structure
584+ * \note This method can be used with any VESSELSTATUSx interface
585+ * version supported by Orbiter. Currently only VESSELSTATUS2 is
586+ * supported.
587+ * \note The version field of the VESSELSTATUSx structure must be set
588+ * by the caller prior to calling the method, to tell Orbiter which
589+ * interface version is required.
590+ * \note In addition, the caller must set the VS_FUELLIST, VS_THRUSTLIST
591+ * and VS_DOCKINFOLIST bits in the flag field, if the corresponding
592+ * lists are required. Otherwise Orbiter will not produce these lists.
593+ * \note If VS_FUELLIST is specified and the fuel field is NULL, Orbiter
594+ * will allocate memory for the list. The caller is responsible for
595+ * deleting the list after use. If the fuel field is not NULL, Orbiter
596+ * assumes that a list of sufficient length to store all propellant
597+ * resources has been allocated by the caller.
598+ * \note The same applies to the thruster and dockinfo lists.
599+ * \sa clbkSetStateEx, DefSetStateEx, VESSELSTATUS2
600+ */
601+ void GetStatusEx (void *status) const;
602+
603+ /**
604+ * \brief Set default vessel status parameters.
605+ *
606+ * Invokes Orbiter's vessel state initialisation with the standard
607+ * status parameters provided via a VESSELSTATUS structure.
608+ * \param status structure containing vessel status parameters
609+ * \note The VESSELSTATUS structure contains only a limited set of
610+ * parameters. Applications should normally use DefSetStateEx in
611+ * combination with an extended VESSELSTATUSx structure.
612+ * \sa VESSELSTATUS, DefSetStateEx, GetStatus
613+ */
614+ void DefSetState (const VESSELSTATUS *status) const;
615+
616+ /**
617+ * \brief Set default vessel status parameters.
618+ *
619+ * Invokes Orbiter's vessel state initialisation with the standard
620+ * status parameters provided in a VESSELSTATUSx structure.
621+ * \param status pointer to a VESSELSTATUSx structure (x >= 2).
622+ * \note status must point to a VESSELSTATUSx structure. Currently only
623+ * VESSELSTATUS2 is supported, but future Orbiter versions may
624+ * introduce new interfaces.
625+ * \note Typically, this function will be called in the body of an
626+ * overloaded VESSEL2::clbkSetStateEx to enable default state
627+ * initialisation.
628+ * \sa VESSELSTATUS2, GetStatusEx, VESSEL2::clbkSetStateEx
629+ */
630+ void DefSetStateEx (const void *status) const;
631+
632+ /**
633+ * \brief Returns a bit flag defining the vessel's current flight status.
634+ * \return vessel status flags (see notes).
635+ * \note The following flags are currently defined:
636+ * - bit 0:
637+ * - 0 = vessel is active (in flight),
638+ * - 1 = vessel is inactive (landed)
639+ * - bit 1:
640+ * - 0 = simple vessel (not docked to anything),
641+ * - 1 = part of superstructure, (docked to another vessel)
642+ */
643+ DWORD GetFlightStatus () const;
644+
645+ /**
646+ * \brief Returns current (total) vessel mass.
647+ * \return Current vessel mass [kg].
648+ * \note The returned value does not include any docked or attached
649+ * vessels.
650+ * \sa SetEmptyMass, GetWeightVector, oapiGetMass
651+ */
652+ double GetMass () const;
653+
654+ /**
655+ * \brief Returns the vessel's current position in the global reference
656+ * frame.
657+ * \param pos Vector receiving position [<b>m</b>]
658+ * \note The global reference frame is the solar barycentric ecliptic
659+ * system at ecliptic and equinox of J2000.0.
660+ * \sa oapiGetGlobalPos, GetGlobalVel, GetRelativePos
661+ */
662+ void GetGlobalPos (VECTOR3 &pos) const;
663+
664+ /**
665+ * \brief Returns the vessel's current velocity in the global reference
666+ * frame.
667+ * \param vel Vector receiving velocity [<b>m/s</b>]
668+ * \note The global reference frame is the solar barycentric ecliptic
669+ * system at ecliptic and equinox of J2000.0.
670+ * \sa oapiGetGlobalVel, GetGlobalPos, GetRelativeVel
671+ */
672+ void GetGlobalVel (VECTOR3 &vel) const;
673+
674+ /**
675+ * \brief Returns the vessel's current position with respect to another
676+ * object.
677+ * \param hRef reference object handle
678+ * \param pos vector receiving position [<b>m</b>]
679+ * \note This function returns the vessel's position relative to the
680+ * position of the object defined by handle hRef.
681+ * \note Results are returned in the ecliptic frame (ecliptic and
682+ * equinox of J2000.0).
683+ * \sa oapiGetRelativePos, GetRelativeVel, GetGlobalPos
684+ */
685+ void GetRelativePos (OBJHANDLE hRef, VECTOR3 &pos) const;
686+
687+ /**
688+ * \brief Returns the vessel's current velocity relative to another
689+ * object.
690+ * \param hRef reference object handle
691+ * \param vel vector receiving velocity [<b>m/s</b>]
692+ * \note This function returns the vessel's velocity relative to the
693+ * velocity of the object defined by handle hRef.
694+ * \note Results are returned in the ecliptic frame (ecliptic and
695+ * equinox of J2000.0).
696+ * \sa oapiGetRelativeVel, GetGlobalVel, GetRelativePos
697+ */
698+ void GetRelativeVel (OBJHANDLE hRef, VECTOR3 &vel) const;
699+
700+ /**
701+ * \brief Returns the vessel's current angular velocity components
702+ * around its principal axes.
703+ * \param [out] avel vector receiving angular velocity components [<b>rad/s</b>]
704+ * \note The returned vector contains the angular velocities
705+ * \f$ \omega_x, \omega_y, \omega_z \f$ around the vessel's x, y and z
706+ * axes, in the rotating vessel frame.
707+ * \note Because the change of the angular velocity components is is
708+ * governed by Euler's coupled differential equations of rigid body
709+ * motion, the values can fluctuate between the axes even if no torque
710+ * is acting on the vessel.
711+ * \sa SetAngularVel, GetAngularAcc
712+ */
713+ void GetAngularVel (VECTOR3 &avel) const;
714+
715+ /**
716+ * \brief Returns the vessel's current angular acceleration components
717+ * around its principal axes.
718+ * \param [out] aacc angular acceleration [<b>rad/s<sup>2</sup></b>]
719+ * \note The returned vector contains the angular accelerations
720+ * \f$ \partial\omega_x/\partial t, \partial\omega_y/\partial t, \partial\omega_z/\partial t \f$
721+ * around the vessel's x, y and z axes, in the rotating vessel frame.
722+ * \sa GetAngularVel, GetAngularMoment
723+ */
724+ void GetAngularAcc (VECTOR3 &aacc) const;
725+
726+ /**
727+ * \brief Returns the linear force vector currently acting on the vessel.
728+ * \param [out] F force vector in vessel coordinates [<b>N</b>]
729+ * \note The returned vector is the vector sum of all forces (gravity,
730+ * thrust, aerodynamic forces, etc.) currently acting on the vessel.
731+ * \sa GetAngularMoment
732+ */
733+ void GetLinearMoment (VECTOR3 &F) const;
734+
735+ /**
736+ * \brief Returns the sum of angular moments currently acting on the vessel.
737+ * \param [out] amom angular moment [<b>Nm</b>]
738+ * \note Given all force components <b>F</b><sub>i</sub> acting on the vessel at
739+ * positions <b>r</b><sub>i</sub>, the angular moment is defined as
740+ * \f[ \vec{M} = \sum_i \vec{F}_i \times \vec{r}_i \f]
741+ * (note the left-handed reference frame in the order of operands for the
742+ * cross product).
743+ * \sa GetLinearMoment
744+ */
745+ void GetAngularMoment (VECTOR3 &amom) const;
746+
747+ /**
748+ * \brief Applies new angular velocity to the vessel.
749+ * \param avel vector containing the new angular velocity components [<b>rad/s</b>]
750+ * \note The input vector defines the angular velocities around the
751+ * vessel's x, y and z axes. They refer to the rotating vessel frame.
752+ * \sa GetAngularVel
753+ */
754+ void SetAngularVel (const VECTOR3 &avel) const;
755+
756+ /**
757+ * \brief Returns the Euler angles defining the vessel's orientation.
758+ * \param arot vector receiving the three Euler angles [<b>rad</b>]
759+ * \note The components of the returned vector arot = \f$ (\alpha, \beta, \gamma) \f$
760+ * are the angles of rotation [rad] around the x,y,z axes in the
761+ * global (ecliptic) frame to produce the rotation matrix <b>R</b> for
762+ * mapping from the vessel's local frame of reference to the global
763+ * frame of reference:
764+ * \f[
765+ * \mathsf{R} = \left[ \begin{array}{ccc}
766+ * 1 & 0 & 0 \\ 0 & \cos\alpha & \sin\alpha \\ 0 & -\sin\alpha & \cos\alpha
767+ * \end{array} \right]
768+ * \left[ \begin{array}{ccc}
769+ * \cos\beta & 0 & -\sin\beta \\ 0 & 1 & 0 \\ \sin\beta & 0 & \cos\beta
770+ * \end{array} \right]
771+ * \left[ \begin{array}{ccc}
772+ * \cos\gamma & \sin\gamma & 0 \\ -\sin\gamma & \cos\gamma & 0 \\ 0 & 0 & 1
773+ * \end{array} \right]
774+ * \f]
775+ * \sa SetGlobalOrientation, GetRotationMatrix
776+ */
777+ void GetGlobalOrientation (VECTOR3 &arot) const;
778+
779+ /**
780+ * \brief Sets the vessel's orientation via Euler angles.
781+ * \param arot vector containing the set of Euler angles [<b>rad</b>]
782+ * \note Given the rotation matrix <b>R</b> which transforms from the
783+ * local (vessel) frame to the global (ecliptic) reference frame,
784+ * the Euler angles expected by this method are defined as
785+ * \f{eqnarray*}
786+ * \alpha &=& \mathrm{atan2} (R_{23}, R_{33}) \\
787+ * \beta &=& \mathrm{asin} (R_{13}) \\
788+ * \gamma &=& \mathrm{atan2} (R_{12}, R_{11})
789+ * \f}
790+ * \sa GetGlobalOrientation, SetRotationMatrix
791+ */
792+ void SetGlobalOrientation (const VECTOR3 &arot) const;
793+
794+ /**
795+ * \brief Returns a flag indicating contact with a planetary surface.
796+ * \return true indicates ground contact (at least one of the vessel's
797+ * touchdown reference points is in contact with a planet surface).
798+ * \sa SetTouchdownPoints
799+ */
800+ bool GroundContact () const;
801+
802+ /**
803+ * \brief Flag indicating whether orbit stabilisation is used for the
804+ * vessel at the current time step.
805+ * \return true indicates that the vessel's state is currently updated
806+ * by using the stabilisation algorithm, which calculates the
807+ * osculating elements with respect to the primary gravitational
808+ * source, and treats all additional forces as perturbations.
809+ * \note A vessel switches to orbit stabilisation only if the user has
810+ * enabled it in the launchpad dialog, and the user-defined
811+ * perturbation and time step limits are currently satisfied.
812+ * \note Stabilised mode reduces the effect of deteriorating orbits due
813+ * to accumulating numerical errors in the state vector propagation,
814+ * but is limited in handling multiple gravitational sources.
815+ * \sa GetElements
816+ */
817+ bool OrbitStabilised () const;
818+
819+ /**
820+ * \brief Flag for nonspherical gravity perturbations.
821+ *
822+ * Indicates whether the vessel considers gravity field perturbations
823+ * due to nonspherical planet shapes when updating its state vectors for
824+ * the current time step.
825+ * \return true indicates that gravity perturbations due to nonspherical
826+ * planet shapes are taken into account.
827+ * \note This function will always return false if the user has disabled
828+ * the "Nonspherical gravity sources" option in the Launchpad dialog.
829+ * \note If the user has enabled orbit stabilisation in the Launchpad,
830+ * this function may sometimes return false during high time
831+ * compression, even if the nonspherical option has been selected. In
832+ * such situations Orbiter can exclude nonspherical perturbations to
833+ * avoid numerical instabilities.
834+ * \sa GetWeightVector
835+ */
836+ bool NonsphericalGravityEnabled () const;
837+
838+ /**
839+ * \brief Returns aerodynamic control surfaces currently under manual
840+ * control.
841+ * \return Bit flags defining the current address mode for aerodynamic
842+ * control surfaces.
843+ * \note The input mode defines which types of control surfaces can be
844+ * manually controlled by the user.
845+ * \note The returned control mode contains bit flags as follows:
846+ * - bit 0: elevator enabled/disabled
847+ * - bit 1 rudder enabled/disabled
848+ * - bit 2 ailerons enabled/disabled
849+ * .
850+ * Therefore, mode=0 indicates control surfaces disabled, mode=7
851+ * indicates fully enabled.
852+ * \note Some vessel types may support not all, or not any, types of
853+ * control surfaces.
854+ * \sa SetADCtrlMode, CreateControlSurface, CreateControlSurface2,
855+ * GetControlSurfaceLevel, SetControlSurfaceLevel
856+ */
857+ DWORD GetADCtrlMode () const;
858+
859+ /**
860+ * \brief Configure manual input mode for aerodynamic control surfaces.
861+ * \param mode bit flags defining the address mode for aerodynamic
862+ * control surfaces (see notes)
863+ * \note The mode parameter contains bit flags as follows:
864+ * - bit 0: enable/disable elevator
865+ * - bit 1: enable/disable rudder
866+ * - bit 2 enable/disable ailerons
867+ * .
868+ * Therefore, use mode = 0 to disable all control surfaces, mode = 7 to
869+ * enable all control surfaces.
870+ * \sa GetADCtrlMode, CreateControlSurface, CreateControlSurface2,
871+ * GetControlSurfaceLevel, SetControlSurfaceLevel
872+ */
873+ void SetADCtrlMode (DWORD mode) const;
874+
875+ /**
876+ * \brief Activates one of the automated orbital navigation modes.
877+ * \param mode navigation mode identifier (see \ref navmode)
878+ * \return \e true if the specified navigation mode could be activated,
879+ * \e false if not available or active already.
880+ * \note Navmodes are high-level navigation modes which involve e.g.
881+ * the simultaneous and timed engagement of multiple attitude thrusters
882+ * to get the vessel into a defined state. Some navmodes terminate
883+ * automatically once the target state is reached (e.g. killrot),
884+ * others remain active until explicitly terminated (hlevel). Navmodes
885+ * may also terminate if a second conflicting navmode is activated.
886+ * \sa navmode, DeactivateNavmode, ToggleNavmode, GetNavmodeState
887+ */
888+ bool ActivateNavmode (int mode);
889+
890+ /**
891+ * \brief Deactivates an automated orbital navigation mode.
892+ * \param mode navigation mode identifier (see \ref navmode)
893+ * \return \e true if the specified navigation mode could be deactivated,
894+ * \e false if not available or inactive already.
895+ * \sa navmode, ActivateNavmode, ToggleNavmode, GetNavmodeState
896+ */
897+ bool DeactivateNavmode (int mode);
898+
899+ /**
900+ * \brief Toggles a navigation mode on/off.
901+ * \param mode navigation mode identifier (see \ref navmode)
902+ * \return \e true if the specified navigation mode could be
903+ * changed, \e false if it remains unchanged.
904+ * \sa navmode, ActivateNavmode, DeactivateNavmode, GetNavmodeState
905+ */
906+ bool ToggleNavmode (int mode);
907+
908+ /**
909+ * \brief Returns the current active/inactive state of a navigation mode.
910+ * \param mode navigation mode identifier (see \ref navmode)
911+ * \return \e true if the specified navigation mode is active, \e false
912+ * otherwise.
913+ * \sa navmode, ActivateNavmode, DeactivateNavmode, ToggleNavmode
914+ */
915+ bool GetNavmodeState (int mode);
916+ //@}
917+
918+
919+ /**
920+ * \name Orbital elements
921+ * See also: \ref orbit
922+ */
923+ //@{
924+ /**
925+ * \brief Returns a handle to the main contributor of the gravity field
926+ * at the vessel's current position.
927+ * \return Handle for gravity reference object.
928+ * \note All parameters calculated by functions in this section refer
929+ * to the gravity reference object, unless explicitly stated otherwise.
930+ */
931+ const OBJHANDLE GetGravityRef () const;
932+
933+ /**
934+ * \brief Returns osculating orbital elements.
935+ *
936+ * Calculates the set of osculating elements at the current time with
937+ * respect to the dominant gravitational source.
938+ * \param[out] el current osculating elements relative to dominant gravity
939+ * source, in ecliptic frame of reference.
940+ * \param[out] mjd_ref reference date (in Modified Julian Date format) to
941+ * which the returned el.L (mean longitude) value refers.
942+ * \return Handle of reference object. NULL indicates failure (no
943+ * elements available).
944+ * \note This method will return the mean longitude at a fixed reference
945+ * date, so the value will not change over time, unless the orbit
946+ * itself changes.
947+ * \note For extended functionality, see version 2 of GetElements.
948+ * \sa \subpage orbit, ELEMENTS, GetElements(OBJHANDLE,ELEMENTS&,ORBITPARAM*,double,int)const,
949+ * SetElements
950+ */
951+ OBJHANDLE GetElements (ELEMENTS &el, double &mjd_ref) const;
952+
953+ /**
954+ * \brief Returns osculating elements and additional orbit parameters.
955+ *
956+ * Returns the current osculating elements for the vessel. This version
957+ * has an extended functionality: it allows to specify an arbitrary
958+ * celestial body as reference object, an arbitrary reference time, and
959+ * can return elements either in the ecliptic or equatorial frame of
960+ * reference.
961+ * \param hRef reference body handle
962+ * \param el current osculating elements relative to hRef
963+ * \param prm additional orbital parameters
964+ * \param mjd_ref reference data (in Modified Julian Date format) to
965+ * which the el.L (mean longitude) value refers.
966+ * \param frame orientation of reference frame (see notes)
967+ * \return Currently always true.
968+ * \note For an overview of orbital parameters, see \ref orbit.
969+ * \note This version returns the elements with respect to an arbitrary
970+ * celestial body, even if that body is not the main source of the
971+ * gravity field acting on the vessel. If hRef==NULL, the default
972+ * reference body is used.
973+ * \note If the prm pointer is not set to NULL, the ORBITPARAM structure
974+ * it points to will be filled with additional orbital parameters
975+ * derived from the primary elements.
976+ * \note All parameters returned in the prm structure refer to the
977+ * current date, rather than the reference date mjd_ref. Therefore,
978+ * the values of el.L and prm->MnL can be different.
979+ * \note Unlike GetElements(ELEMENTS&,double&), mjd_ref is a
980+ * user-provided input parameter which specifies to which date the
981+ * returned el.L (mean longitude) value will refer. An exception is
982+ * mjd_ref = 0, which is interpreted as the current time (equivalent
983+ * to mjd_ref = oapiGetSimMJD() ).
984+ * \note The frame parameter can be set to one of the following:
985+ * - FRAME_ECL: returned elements are expressed in the ecliptic frame
986+ * (epoch J2000).
987+ * - FRAME_EQU: returned elements are expressed in the equatorial
988+ * frame of the reference object (hRef).
989+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetElements(ELEMENTS&,double&)const,
990+ * SetElements
991+ */
992+ bool GetElements (OBJHANDLE hRef, ELEMENTS &el, ORBITPARAM *prm = 0, double mjd_ref = 0, int frame = FRAME_ECL) const;
993+
994+ /**
995+ * \brief Set vessel state (position and velocity) by means of a set of
996+ * osculating orbital elements.
997+ * \param hRef reference body handle
998+ * \param el set of elements to be applied
999+ * \param prm secondary orbital parameters
1000+ * \param mjd_ref reference date (in Modified Julian Date format) to
1001+ * which the el.L (mean longitude) value refers
1002+ * \param frame orientation of reference frame (see notes)
1003+ * \return If the vessel position resulting from applying the elements
1004+ * would be located below the surface of the reference body, the
1005+ * method does nothing and returns false. Otherwise it returns true.
1006+ * \note This method resets the vessel's position and velocity
1007+ * according to the specified orbital elements.
1008+ * \note If the prm pointer is not set to NULL, the ORBITPARAM structure
1009+ * it points to will be filled with secondary orbital parameters
1010+ * derived from the primary elements el. Note that this is an output
1011+ * parameter, i.e. the resulting vessel state will not be influenced
1012+ * by initialising this structure prior to the function call.
1013+ * \note All parameters returned in the prm structure refer to the
1014+ * current date, rather than the reference date mjd_ref. Therefore,
1015+ * the values of el.L and prm->MnL can be different.
1016+ * \note The elements can be supplied either in terms of the ecliptic
1017+ * frame (frame = FRAME_ECL) or in the equatorial frame of the
1018+ * reference body (frame = FRAME_EQU).
1019+ * \note mjd_ref is an input parameter which defines the date to which
1020+ * the el.L (mean longitude) value refers. An exception is mjd_ref = 0,
1021+ * which is interpreted as the current time (equivalent to
1022+ * mjd_ref = oapiGetSimMJD() ).
1023+ * \note Calling SetElements will always put a vessel in freeflight
1024+ * mode, even if it had been landed before.
1025+ * \note Currently, SetElements doesn't check for validity of the
1026+ * provided elements. Setting invalid elements, or elements which put
1027+ * the vessel below a planetary surface will produce undefined
1028+ * results.
1029+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetElements(ELEMENTS&,double&)const,
1030+ * GetElements(OBJHANDLE,ELEMENTS&,ORBITPARAM*,double,int)const
1031+ */
1032+ bool SetElements (OBJHANDLE hRef, const ELEMENTS &el, ORBITPARAM *prm = 0, double mjd_ref = 0, int frame = FRAME_ECL) const;
1033+
1034+ /**
1035+ * \brief Returns the magnitude of the semi-minor axis of the current
1036+ * osculating orbit.
1037+ * \param [out] smi semi-minor axis [m]
1038+ * \return Handle of reference object, relative to which the orbit is
1039+ * calculated. NULL indicates failure (no orbit information available)
1040+ * \note The semi-minor axis is the smallest semi-diameter of the
1041+ * orbit ellipse (see \ref orbit).
1042+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetElements
1043+ */
1044+ OBJHANDLE GetSMi (double &smi) const;
1045+
1046+ /**
1047+ * \brief Returns argument of periapsis of the current osculating orbit.
1048+ * \param [out] arg argument of periapsis for current orbit [rad]
1049+ * \return Handle of reference body, relative to which the orbit is
1050+ * calculated. NULL indicates failure (no orbit information available)
1051+ * \note The argument of periapsis is the angle between periapsis and the
1052+ * ascending node (see \ref orbit_2).
1053+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetPeDist, GetApDist, GetElements
1054+ */
1055+ OBJHANDLE GetArgPer (double &arg) const;
1056+
1057+ /**
1058+ * \brief Returns the periapsis distance of the current osculating orbit.
1059+ * \param [out] pedist periapsis distance [m]
1060+ * \return Handle of reference body, relative to which the orbit is
1061+ * calculated. NULL indicates failure (no orbit information available)
1062+ * \note The periapsis distance is the smallest radius of the orbit (see
1063+ * \ref orbit).
1064+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetApDist, GetArgPer, GetElements
1065+ */
1066+ OBJHANDLE GetPeDist (double &pedist) const;
1067+
1068+ /**
1069+ * \brief Returns the apoapsis distance of the current osculating orbit.
1070+ * \param [out] apdist apoapsis distance [m]
1071+ * \return Handle of reference body, relative to which the orbit is
1072+ * calculated. NULL indicates failure (no orbit information available)
1073+ * \note the apoapsis distance is the largest radius of the orbit (see
1074+ * \ref orbit).
1075+ * \sa \subpage orbit, ELEMENTS, ORBITPARAM, GetPeDist, GetArgPer, GetElements
1076+ */
1077+ OBJHANDLE GetApDist (double &apdist) const;
1078+ //@}
1079+
1080+
1081+ /// \name Surface-relative parameters
1082+ //@{
1083+ /**
1084+ * \brief Returns a handle to the surface reference object (planet or moon).
1085+ * \return Surface reference object handle
1086+ * \note The surface reference is the planet or moon whose surface is
1087+ * closest to the current vessel position. All methods in this group
1088+ * refer to this celestial body.
1089+ */
1090+ const OBJHANDLE GetSurfaceRef () const;
1091+
1092+ /**
1093+ * \brief Returns the altitude above the surface of the surface reference
1094+ * body.
1095+ * \return Altitude [m]
1096+ * \note Currently all celestial bodies are assumed to be spheres. This
1097+ * method therefore returns the distance to the centre of the reference
1098+ * body minus the reference body radius.
1099+ * \note The reference body is the planet or moon whose surface is closest
1100+ * to the current vessel position (i.e. the body with minimal altitude).
1101+ * \sa GetSurfaceRef
1102+ */
1103+ double GetAltitude () const;
1104+
1105+ /**
1106+ * \brief Returns the current pitch angle with respect to the local horizon.
1107+ * \return pitch angle [rad]
1108+ * \note The pitch angle \e p is defined as
1109+ * \f[ p = \frac{\pi}{2} - q \f]
1110+ * where \e q is the angle between the vessel's positive z axis (forward
1111+ * direction) and the normal of the local horizon.
1112+ * \sa GetSurfaceRef, GetBank, GetYaw
1113+ */
1114+ double GetPitch () const;
1115+
1116+ /**
1117+ * \brief Returns the current bank (roll) angle with respect to the local
1118+ * horizon.
1119+ * \return bank angle [rad]
1120+ * \note The bank angle \e b is defined as the angle between the vessel's
1121+ * positive y axis (up direction) and the projection of the normal of the
1122+ * local horizon into the x-y plane.
1123+ * \sa GetSurfaceRef, GetPitch, GetYaw
1124+ */
1125+ double GetBank () const;
1126+
1127+ /**
1128+ * \brief Returns the current yaw angle with respect to the local horizon.
1129+ * \return yaw angle [rad]
1130+ * \note The yaw angle \e y is defined as the angle between the the projection
1131+ * of the vessel's positive z axis (forward direction) into the horizon
1132+ * plane, and the local horizon "north" direction.
1133+ * \sa GetSurfaceRef, GetPitch, GetBank
1134+ */
1135+ double GetYaw () const;
1136+
1137+ /**
1138+ * \brief Returns vessel's current equatorial position with respect to the
1139+ * closest planet or moon.
1140+ * \param [out] longitude longitude coordinate [rad]
1141+ * \param [out] latitude latitude coordinate [rad]
1142+ * \param [out] radius distance from planet centre [m]
1143+ * \return Handle to reference body to which the parameters refer.
1144+ * NULL indicates failure (no reference body available).
1145+ * \sa GetSurfaceRef
1146+ */
1147+ OBJHANDLE GetEquPos (double &longitude, double &latitude, double &radius) const;
1148+ //@}
1149+
1150+
1151+ /// \name Atmospheric parameters
1152+ //@{
1153+ /**
1154+ * \brief Returns a handle to the reference body for atmospheric calculations.
1155+ * \return Handle for the celestial body whose atmosphere the vessel is
1156+ * currently moving through, or NULL if the vessel is not inside an
1157+ * atmosphere.
1158+ * \sa GetAtmTemperature, GetAtmDensity, GetAtmPressure
1159+ */
1160+ const OBJHANDLE GetAtmRef () const;
1161+
1162+ /**
1163+ * \brief Returns ambient atmospheric temperature at current vessel position.
1164+ * \return Ambient temperature [K] at current vessel position.
1165+ * \note This function returns 0 if the vessel is outside all planetary
1166+ * atmospheric hulls, as defined by the planets' AtmAltLimit parameters.
1167+ * \sa GetAtmDensity, GetAtmPressure, GetAtmRef
1168+ */
1169+ double GetAtmTemperature () const;
1170+
1171+ /**
1172+ * \brief Returns atmospheric density at current vessel position.
1173+ * \return Atmospheric density [kg/m<sup>3</sup>] at current vessel position.
1174+ * \note This function returns 0 if the vessel is outside all planetary
1175+ * atmospheric hulls, as defined by the planets' AtmAltLimit parameters.
1176+ * \sa GetAtmPressure, GetAtmTemperature, GetAtmRef
1177+ */
1178+ double GetAtmDensity () const;
1179+
1180+ /**
1181+ * \brief Returns static atmospheric pressure at current vessel position.
1182+ * \return Static atmospheric pressure [Pa] at current vessel position.
1183+ * \note This function returns 0 if the vessel is outside all planetary
1184+ * atmospheric hulls, as defined by the planets' AtmAltLimit parameters.
1185+ * \sa GetDynPressure, GetAtmDensity, GetAtmTemperature, GetAtmRef
1186+ */
1187+ double GetAtmPressure () const;
1188+ //@}
1189+
1190+
1191+ /// \name Aerodynamic state parameters
1192+ //@{
1193+ /**
1194+ * \brief Returns the current dynamic pressure for the vessel.
1195+ * \return Current vessel dynamic pressure [Pa].
1196+ * \note The dynamic pressure is defined as
1197+ * \f[ q = \frac{1}{2} \rho V^2 \f]
1198+ * with density \f$\rho\f$ and airflow velocity \e V. Dynamic pressure is an
1199+ * important aerodynamic parameter.
1200+ * \sa GetAtmPressure, GetAtmRef
1201+ */
1202+ double GetDynPressure () const;
1203+
1204+ /**
1205+ * \brief Returns the vessel's current Mach number.
1206+ * \return Mach number - the ratio of current freestream airflow velocity over
1207+ * speed of sound.
1208+ * \note The speed of sound depends on several parameters, e.g. atmospheric
1209+ * composition and temperature. The Mach number can therefore vary even if
1210+ * the airspeed is constant.
1211+ * \sa GetAirspeed, GetAtmRef
1212+ */
1213+ double GetMachNumber () const;
1214+
1215+ /**
1216+ * \brief Returns magnitude of the freestream airflow velocity vector measured
1217+ * in ship-relative coordinates.
1218+ * \return Magnitude of airflow velocity vector [m/s]
1219+ * \note This function also works in the absence of an atmosphere. At low
1220+ * altitudes, the returned value is a ground-speed equivalent. At high
1221+ * altitudes the value diverges from ground speed, since an atmospheric drag
1222+ * effect is assumed.
1223+ * \note This function returns the length of the vector returned by
1224+ * GetShipAirspeedVector().
1225+ * \sa GetShipAirspeedVector, GetMachNumber, GetAtmRef
1226+ */
1227+ double GetAirspeed () const;
1228+
1229+ /**
1230+ * \brief Returns the airspeed vector in local horizon coordinates.
1231+ * \param [out] v airspeed vector on exit [<b>m/s</b>]
1232+ * \return \e false indicates error
1233+ * \note This method returns the airspeed vector in the reference frame of the local
1234+ * horizon. x = longitudinal component, y = vertical component, z = latitudinal
1235+ * component.
1236+ * \sa GetAirspeed, GetShipAirspeedVector
1237+ */
1238+ bool GetHorizonAirspeedVector (VECTOR3 &v) const;
1239+
1240+ /**
1241+ * \brief Returns the airspeed vector in vessel coordinates.
1242+ * \param [out] v airspeed vector on exit [<b>m/s</b>]
1243+ * \return \e false indicates error
1244+ * \note This method returns the airspeed vector in local ship coordinates. x =
1245+ * lateral component, y = vertical component, z = longitudinal component.
1246+ * \sa GetAirspeed, GetHorizonAirspeedVector
1247+ */
1248+ bool GetShipAirspeedVector (VECTOR3 &v) const;
1249+
1250+ /**
1251+ * \brief Returns the current angle of attack.
1252+ * \return AOA (angle of attack) value [rad] in the range -Pi ... +Pi.
1253+ * \note The AOA value is defined as the angle between the vessel's positive
1254+ * z axis and the flight path direction, projected into the yz-plane of the
1255+ * vessel's local coordinate system.
1256+ * \sa GetSlipAngle
1257+ */
1258+ double GetAOA () const;
1259+
1260+ /**
1261+ * \brief Returns the lateral (yaw) angle between the velocity vector and the
1262+ * vessel's longitudinal axis.
1263+ * \return slip angle [rad] in the range -Pi ... +Pi.
1264+ * \note The slip angle is defined as the angle between the vessel's positive
1265+ * z axis and the flight path direction, projected into the xz-plane of the
1266+ * vessel's local coordinate system.
1267+ * \sa GetAOA
1268+ */
1269+ double GetSlipAngle () const;
1270+ //@}
1271+
1272+
1273+ /// \name Airfoils and control surfaces
1274+ //@{
1275+ /**
1276+ * \brief Creates a new airfoil and defines its aerodynamic properties.
1277+ * \param align orientation of the lift vector (LIFT_VERTICAL or LIFT_HORIZONTAL)
1278+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1279+ * \param cf pointer to coefficient callback function (see notes)
1280+ * \param c airfoil chord length [m]
1281+ * \param S wing area [m<sup>2</sup>]
1282+ * \param A wing aspect ratio
1283+ * \note A vessel can define multiple airfoils (for wings, main body,
1284+ * tail stabilisators, etc.). In general, it should define at least
1285+ * one vertical and one horizontal component.
1286+ * \note Airfoil definitions for wings and horizontal stabilisers set
1287+ * \a align to LIFT_VERTICAL. Vertical stabilisers (vertical tail
1288+ * fin, etc.) set \a align to LIFT_HORIZONTAL.
1289+ * \note The centre of pressure is the point at which the lift and
1290+ * drag forces generated by the airfoil are applied to the vessel.
1291+ * Together with the moment coefficient it defines the aerodynamic
1292+ * stability of the vessel. Usually the CoP will be aft of the CG,
1293+ * and the moment coefficient will have a negative slope around the
1294+ * trim angle of attack.
1295+ * \note The \a AirfoilCoeffFunc is a callback function which must be
1296+ * supplied by the module. It calculates the lift, moment and drag
1297+ * coefficients for the airfoil. It has the following interface:
1298+ * \code
1299+ * void AirfoilCoeffFunc (double aoa, double M, double Re,
1300+ * double *cl, double *cm, double *cd)
1301+ * \endcode
1302+ * and returns the lift coefficient (\e cl), moment coefficient (\e
1303+ * cm) and drag coefficient (\e cd) as a function of angle of attack
1304+ * \e aoa [rad], Mach number \e M and Reynolds number \e Re. Note
1305+ * that aoa can range over the full circle (-pi to pi). For vertical
1306+ * lift components, aoa is the pitch angle of attack (a), while for
1307+ * horizontal components it is the yaw angle of attack (b).
1308+ * \note If the wing area S is set to 0, then Orbiter uses the
1309+ * projected vessel cross sections to define a reference area. Let
1310+ * (v<sub>x</sub>, v<sub>y</sub>, v<sub>z</sub>) be the unit vector
1311+ * of freestream air flow in vessel coordinates. Then the reference
1312+ * area is calculated as S = v<sub>z</sub>C<sub>z</sub> + v<sub>y</sub>C<sub>y</sub>
1313+ * for a LIFT_VERTICAL airfoil, and as S = v<sub>z</sub>C<sub>z</sub> + v<sub>x</sub>C<sub>x</sub>
1314+ * for a LIFT_HORIZONTAL airfoil, where C<sub>x</sub>, C<sub>y</sub>, C<sub>z</sub>
1315+ * are the vessel cross-sections in x, y and z direction, respectively.
1316+ * \note The wing aspect ratio is defined as defined as A = b<sup>2</sup>/S
1317+ * with wing span b.
1318+ * \note A vessel should typically define its airfoils in the
1319+ * \ref VESSEL2::clbkSetClassCaps callback function. If no airfoils
1320+ * are defined, Orbiter will fall back to its legacy drag
1321+ * calculation, using the cw coefficients defined in \ref SetCW.
1322+ * Legacy lift calculation is no longer supported.
1323+ * \note For more details, see the Programmer's Guide.
1324+ * \sa CreateAirfoil2, CreateAirfoil3, EditAirfoil, DelAirfoil
1325+ */
1326+ void CreateAirfoil (AIRFOIL_ORIENTATION align, const VECTOR3 &ref, AirfoilCoeffFunc cf, double c, double S, double A) const;
1327+
1328+ /**
1329+ * \brief Creates a new airfoil and defines its aerodynamic properties.
1330+ * \param align orientation of the lift vector (LIFT_VERTICAL or LIFT_HORIZONTAL)
1331+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1332+ * \param cf pointer to coefficient callback function (see notes)
1333+ * \param c airfoil chord length [m]
1334+ * \param S wing area [m<sup>2</sup>]
1335+ * \param A wing aspect ratio
1336+ * \return Handle for the new airfoil.
1337+ * \note This method is identical to \ref CreateAirfoil, but returns a
1338+ * handle which can be used to identify the airfoil later.
1339+ * \sa CreateAirfoil, CreateAirfoil3, EditAirfoil, DelAirfoil
1340+ */
1341+ AIRFOILHANDLE CreateAirfoil2 (AIRFOIL_ORIENTATION align, const VECTOR3 &ref, AirfoilCoeffFunc cf, double c, double S, double A) const;
1342+
1343+ /**
1344+ * \brief Creates a new airfoil and defines its aerodynamic properties.
1345+ * \param align orientation of the lift vector (LIFT_VERTICAL or LIFT_HORIZONTAL)
1346+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1347+ * \param cf pointer to coefficient callback function (see notes)
1348+ * \param context pointer to data block passed to cf callback function
1349+ * \param c airfoil chord length [m]
1350+ * \param S wing area [m<sup>2</sup>]
1351+ * \param A wing aspect ratio
1352+ * \return Handle for the new airfoil.
1353+ * \note This method is an extension to \ref CreateAirfoil2, using a
1354+ * more versatile coefficient callback function.
1355+ * \note AirfoilCoeffFuncEx has the following interface:
1356+ * \code
1357+ * void AirfoilCoeffFuncEx (VESSEL *v, double aoa, double M, double Re,
1358+ * void *context, double *cl, double *cm, double *cd)
1359+ * \endcode
1360+ * where \e v is a pointer to the calling vessel instance, and
1361+ * \a context is the pointer passed to CreateAirfoil3. It can be
1362+ * used to make available to the callback function any additional
1363+ * parameters required to calculate the lift and drag coefficients.
1364+ * All other parameters are identical to AirfoilCoeffFunc (see
1365+ * \ref CreateAirfoil).
1366+ * \sa CreateAirfoil, CreateAirfoil2, EditAirfoil, DelAirfoil
1367+ */
1368+ AIRFOILHANDLE CreateAirfoil3 (AIRFOIL_ORIENTATION align, const VECTOR3 &ref, AirfoilCoeffFuncEx cf, void *context, double c, double S, double A) const;
1369+
1370+ /**
1371+ * \brief Returns the parameters of an existing airfoil.
1372+ * \param [in] hAirfoil airfoil handle
1373+ * \param [out] ref pointer to centre of pressure [<b>m</b>]
1374+ * \param [out] cf pointer to aerodynamic coefficient callback function
1375+ * \param [out] c pointer to chord length [m]
1376+ * \param [out] S pointer to wing area [m<sup>2</sup>]
1377+ * \param [out] A pointer to wing aspect ratio
1378+ * \param [out] context pointer to callback context data
1379+ * \return \e false indicates failure
1380+ * \note This function copies the airfoil parameters into the
1381+ * variables referenced by the pointers in the parameter list.
1382+ * \note Any pointers set to NULL are ignored.
1383+ * \code
1384+ * VECTOR3 cop;
1385+ * AirfoilCoeffFunc cf;
1386+ * void *context;
1387+ * double c, S, A;
1388+ * v->GetAirfoilParam(hAirfoil,&cop,&cf,&context,&c,&S,&A);
1389+ * \endcode
1390+ * \sa CreateAirfoil, CreateAirfoil2, CreateAirfoil3, EditAirfoil, DelAirfoil
1391+ */
1392+ bool GetAirfoilParam (AIRFOILHANDLE hAirfoil, VECTOR3 *ref, AirfoilCoeffFunc *cf, void **context, double *c, double *S, double *A) const;
1393+
1394+ /**
1395+ * \brief Resets the parameters of an existing airfoil definition.
1396+ * \param hAirfoil airfoil handle
1397+ * \param flag bitflags to define which parameters to reset (see notes)
1398+ * \param ref new centre of pressure
1399+ * \param cf new callback function for coefficient calculation
1400+ * \param c new chord length [m]
1401+ * \param S new wing area [m<sup>2</sup>]
1402+ * \param A new wing aspect ratio
1403+ * \note This function can be used to modify the parameters of a
1404+ * previously created airfoil.
1405+ * \note \a flag contains the bit flags defining which parameters will
1406+ * be modified. It can be any combination of the following:
1407+ * <table>
1408+ * <tr><td>0x01</td><td>modify force attack point</td></tr>
1409+ * <tr><td>0x02</td><td>modify coefficient callback function</td></tr>
1410+ * <tr><td>0x04</td><td>modify chord length</td></tr>
1411+ * <tr><td>0x08</td><td>modify wing area</td></tr>
1412+ * <tr><td>0x10</td><td>modify wing aspect ratio</td></tr>
1413+ * </table>
1414+ * \note If the airfoil identified by \a hAirfoil was created with
1415+ * \ref CreateAirfoil3, and you want to modifiy the callback
1416+ * function, then \a cf must point to a function with
1417+ * \e AirfoilCoeffFuncEx interface, and must be cast to
1418+ * \e AirfoilCoeffFunc when passed to EditAirfoil.
1419+ * \sa CreateAirfoil2, CreateAirfoil3
1420+ */
1421+ void EditAirfoil (AIRFOILHANDLE hAirfoil, DWORD flag, const VECTOR3 &ref, AirfoilCoeffFunc cf, double c, double S, double A) const;
1422+
1423+ /**
1424+ * \brief Deletes a previously defined airfoil.
1425+ * \param hAirfoil airfoil handle
1426+ * \return \e false indicates failure (invalid handle)
1427+ * \note If all the vessel's airfoils are deleted without creating
1428+ * new ones, Orbiter reverts to the obsolete legacy atmospheric
1429+ * flight model.
1430+ * \sa CreateAirfoil2, CreateAirfoil3, ClearAirfoilDefinitions
1431+ */
1432+ bool DelAirfoil (AIRFOILHANDLE hAirfoil) const;
1433+
1434+ /**
1435+ * \brief Removes all airfoils currently defined for the vessel.
1436+ * \note This function is useful if a vessel needs to re-define all
1437+ * its airfoil definitions as a result of a structural change.
1438+ * \note After clearing all airfoils, you should generate new ones.
1439+ * Even wingless objects (such as capsules) should define their
1440+ * aerodynamic behaviour by airfoils (see CreateAirfoil). Vessels
1441+ * without airfoil definitions revert to the obsolete legacy
1442+ * atmospheric flight model.
1443+ * \sa DelAirfoil, CreateAirfoil, CreateAirfoil2, CreateAirfoil3
1444+ */
1445+ void ClearAirfoilDefinitions () const;
1446+
1447+ /**
1448+ * \brief Creates an aerodynamic control surface.
1449+ * \param type control surface type (see \ref airctrltype)
1450+ * \param area control surface area [m<sup>2</sup>]
1451+ * \param dCl shift in lift coefficient achieved by fully extended control
1452+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1453+ * \param axis rotation axis (see \ref airctrlaxis)
1454+ * \param anim animation reference, if applicable
1455+ * \note Control surfaces include elevators, rudders, ailerons, flaps, etc.
1456+ * They can be used to control the vessel during atmospheric flight.
1457+ * \note When selecting automatic axis control (axis=AIRCTRL_AXIS_AUTO), the
1458+ * following axes will be used for given control surfaces:
1459+ * <table>
1460+ * <tr><td>Elevator</td><td>XPOS</td></tr>
1461+ * <tr><td>Rudder</td><td>YPOS</td></tr>
1462+ * <tr><td>Aileron</td><td>XPOS if ref.x &gt; 0, XNEG otherwise</td></tr>
1463+ * <tr><td>Flap</td><td>XPOS</td></tr>
1464+ * </table>
1465+ * \note For ailerons, at least 2 control surfaces should be defined (e.g. on
1466+ * left and right wing) with opposite rotation axes, to obtain the angular
1467+ * momentum for banking the vessel.
1468+ * \note Elevators typically use the XPOS axis, assuming the that the centre
1469+ * of pressure is aft of the centre of gravity. If pitch control is provided
1470+ * by a canard configuration \e ahead of the CoG, XNEG should be used instead.
1471+ * \note The centre of pressure defined by the \a ref parameter is the point at
1472+ * which the lift and drag forces for the control surface are applied.
1473+ * \note To improve performance, multiple control surfaces may sometimes be
1474+ * defined by a single call to CreateControlSurface. For example, the elevator
1475+ * controls on the left and right wing may be combined by setting a centered
1476+ * attack point.
1477+ * \note Control surfaces can be animated, by passing an animation reference to
1478+ * CreateControlSurface. The animation reference is obtained when creating the
1479+ * animation with \ref CreateAnimation. The animation should support a state
1480+ * in the range from 0 to 1, with neutral surface position at state 0.5.
1481+ * \sa CreateControlSurface2, CreateControlSurface3
1482+ */
1483+ void CreateControlSurface (AIRCTRL_TYPE type, double area, double dCl,
1484+ const VECTOR3 &ref, int axis = AIRCTRL_AXIS_AUTO, UINT anim = (UINT)-1) const;
1485+
1486+ /**
1487+ * \brief Creates an aerodynamic control surface and returns a handle.
1488+ * \param type control surface type (see \ref airctrltype)
1489+ * \param area control surface area [m<sup>2</sup>]
1490+ * \param dCl shift in lift coefficient achieved by fully extended control
1491+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1492+ * \param axis rotation axis (see \ref airctrlaxis)
1493+ * \param anim animation reference, if applicable
1494+ * \return Control surface handle.
1495+ * \note This function is identical to \ref CreateControlSurface, but it returns
1496+ * a handle for later reference (e.g. to delete it with \ref DelControlSurface)
1497+ * \note It is equivalent to \ref CreateControlSurface3 with \a delay = 1.
1498+ * \sa CreateControlSurface, CreateControlSurface3, DelControlSurface
1499+ */
1500+ CTRLSURFHANDLE CreateControlSurface2 (AIRCTRL_TYPE type, double area, double dCl,
1501+ const VECTOR3 &ref, int axis = AIRCTRL_AXIS_AUTO, UINT anim = (UINT)-1) const;
1502+
1503+ /**
1504+ * \brief Creates an aerodynamic control surface and returns a handle.
1505+ * \param type control surface type (see \ref airctrltype)
1506+ * \param area control surface area [m<sup>2</sup>]
1507+ * \param dCl shift in lift coefficient achieved by fully extended control
1508+ * \param ref centre of pressure in vessel coordinates [<b>m</b>]
1509+ * \param axis rotation axis (see \ref airctrlaxis)
1510+ * \param delay response delay setting [s]
1511+ * \param anim animation reference, if applicable
1512+ * \return Control surface handle.
1513+ * \note This function is identical to \ref CreateControlSurface2 except that
1514+ * it specifies an additional 'delay' parameter which defines the response
1515+ * delay for the surface (the time it takes to move from neutral to fully
1516+ * deployed). Setting delay=0 provides direct response.
1517+ * \sa CreateControlSurface, CreateControlSurface2
1518+ */
1519+ CTRLSURFHANDLE CreateControlSurface3 (AIRCTRL_TYPE type, double area, double dCl,
1520+ const VECTOR3 &ref, int axis = AIRCTRL_AXIS_AUTO, double delay = 1.0, UINT anim = (UINT)-1) const;
1521+
1522+ /**
1523+ * \brief Deletes a previously defined aerodynamic control surface.
1524+ * \param hCtrlSurf control surface handle
1525+ * \return \e false indicates error (invalid handle)
1526+ * \sa CreateControlSurface2, CreateControlSurface3
1527+ */
1528+ bool DelControlSurface (CTRLSURFHANDLE hCtrlSurf) const;
1529+
1530+ /**
1531+ * \brief Removes all aerodynamic control surfaces.
1532+ * \note This function is useful if the vessel has to re-define all its
1533+ * control surfaces (e.g. as a result of structural change).
1534+ * \sa DelControlSurface
1535+ */
1536+ void ClearControlSurfaceDefinitions () const;
1537+
1538+ /**
1539+ * \brief Updates the position of an aerodynamic control surface.
1540+ * \param type control surface type (see \ref airctrltype)
1541+ * \param level new control surface position [-1...+1]
1542+ * \note Parameter \a level defines a \e target state for the surface. Control
1543+ * surfaces generally require a finite amount of time to move from the
1544+ * current to the target state.
1545+ * \note This method affects the \e permanent setting of the control surface,
1546+ * while manual input via keyboard or joystick affects the \e transient
1547+ * setting. The total target state of the control surface is the sum of both
1548+ * settings, clamped to the range [-1...+1]
1549+ * \sa SetControlSurfaceLevel(AIRCTRL_TYPE,double,bool)const,
1550+ * GetControlSurfaceLevel
1551+ */
1552+ void SetControlSurfaceLevel (AIRCTRL_TYPE type, double level) const;
1553+
1554+ /**
1555+ * \brief Updates the position of an aerodynamic control surface.
1556+ * \param type control surface type (see \ref airctrltype)
1557+ * \param level new control surface position [-1...+1]
1558+ * \param direct application mode
1559+ * \note If parameter \a direct==true then the specified level is applied
1560+ * directly, bypassing any reaction delays defined for the control surface.
1561+ * \note If parameter \a direct==false then this method is equivalent to
1562+ * \ref SetControlSurfaceLevel(AIRCTRL_TYPE,double)const .
1563+ * \note Bypassing the response delay can be useful for debugging autopilots
1564+ * etc. but should be avoided in production code, since it is unphysical.
1565+ * If you want to simulate fast-responding controls, create the surface
1566+ * with a small delay setting instead.
1567+ * \sa SetControlSurfaceLevel(AIRCTRL_TYPE,double)const, CreateControlSurface3
1568+ */
1569+ void SetControlSurfaceLevel (AIRCTRL_TYPE type, double level, bool direct) const;
1570+
1571+ /**
1572+ * \brief Returns the current position of a control surface.
1573+ * \param type control surface type (see \ref airctrltype)
1574+ * \return Current position of the surface [-1..+1]
1575+ * \note This method returns the \e actual, not the \e target position. Due to
1576+ * finite response time, it may therefore not return the value set by a
1577+ * preceeding call to SetControlSurfaceLevel.
1578+ * \sa SetControlSurfaceLevel
1579+ */
1580+ double GetControlSurfaceLevel (AIRCTRL_TYPE type) const;
1581+
1582+ /**
1583+ * \brief Attaches a modifyable drag component to the vessel.
1584+ * \param drag pointer to external drag control parameter
1585+ * \param factor drag magnitude scaling factor
1586+ * \param ref drag force attack point [<b>m</b>]
1587+ * \note This method is useful for defining drag produced by movable parts
1588+ * such as landing gear and airbrakes.
1589+ * \note The magnitude of the drag force is calculated as
1590+ * \f[ D = d \cdot f \cdot q_\infty \f]
1591+ * where \e d is the control parameter, \e f is the scale factor, and
1592+ * \e q is the freestream dynamic pressure.
1593+ * \note The value of \e d (the parameter pointed to by \a drag) should
1594+ * be set to values between 0 (no drag) and 1 (full drag). Any changes
1595+ * to the value have immediate effect.
1596+ * \note Depending on the attack point, the applied drag force may create
1597+ * torque in addition to linear force.
1598+ * \sa ClearVariableDragElements
1599+ */
1600+ void CreateVariableDragElement (double *drag, double factor, const VECTOR3 &ref) const;
1601+
1602+ /**
1603+ * \brief Removes all drag elements defined with CreateVariableDragElement.
1604+ * \sa CreateVariableDragElement
1605+ */
1606+ void ClearVariableDragElements () const;
1607+ //@}
1608+
1609+
1610+ /// \name Aerodynamic vessel properties (legacy model)
1611+ /// The methods in this group are used only if the vessel does not define
1612+ /// any airfoils.
1613+ //@{
1614+ /**
1615+ * \brief Returns the vessel's wind resistance coefficients (legacy flight
1616+ * model only).
1617+ * \param cw_z_pos resistance coefficient in positive z direction (forward)
1618+ * \param cw_z_neg resistance coefficient in negative z direction (back)
1619+ * \param cw_x resistance coefficient in lateral direction (left/right)
1620+ * \param cw_y resistance coefficient in vertical direction (up/down)
1621+ * \note <b>[Legacy aerodynamic flight model only]</b>
1622+ * \note The cw coefficients are only used by the legacy flight model (if
1623+ * no airfoils are defined). In the presence of airfoils, drag calculations
1624+ * are performed on the basis of the airfoil parameters.
1625+ * \note The first value (cw_z_pos) is the coefficient used if the vessel's
1626+ * airspeed z-component is positive (vessel moving forward). The second
1627+ * value is used if the z-component is negative (vessel moving backward).
1628+ * \note Lateral and vertical components are assumed symmetric.
1629+ * \sa SetCW, CreateAirfoil
1630+ */
1631+ void GetCW (double &cw_z_pos, double &cw_z_neg, double &cw_x, double &cw_y) const;
1632+
1633+ /**
1634+ * \brief Set the vessel's wind resistance coefficients along its axis directions.
1635+ * \param cw_z_pos coefficient in positive z direction (forward)
1636+ * \param cw_z_neg coefficient in negative z direction (back)
1637+ * \param cw_x coefficient in lateral direction (left/right)
1638+ * \param cw_y coefficient in vertical direction (up/down)
1639+ * \note <b>[Legacy aerodynamic flight model only]</b>
1640+ * \note The cw coefficients are only used by the legacy flight model (if
1641+ * no airfoils are defined). In the presence of airfoils, drag calculations
1642+ * are performed on the basis of the airfoil parameters.
1643+ * \note The first value (cw_z_pos) is the coefficient used if the vessel's airspeed
1644+ * z-component is positive (vessel moving forward). The second value is used if
1645+ * the z-component is negative (vessel moving backward).
1646+ * \note Lateral and vertical components are assumed symmetric.
1647+ * \sa GetCW, CreateAirfoil
1648+ */
1649+ void SetCW (double cw_z_pos, double cw_z_neg, double cw_x, double cw_y) const;
1650+
1651+ /**
1652+ * \brief Returns the vessel's wing aspect ratio (wingspan<sup>2</sup> / wing area)
1653+ * \return Wing aspect ratio (wingspan<sup>2</sup> / wing area)
1654+ * \note <b>[Legacy aerodynamic flight model only]</b>
1655+ * \note The aspect ratio returned by this function is only used by the
1656+ * legacy aerodynamic flight model. If the vessel uses the new flight
1657+ * model (i.e. defines at least one airfoil), then this value is ignored,
1658+ * and the airfoil parameters are used instead.
1659+ * \note The aspect ratio is used in the calculation of induced drag.
1660+ * \sa SetWingAspect, GetWingEffectiveness, CreateAirfoil
1661+ */
1662+ double GetWingAspect () const;
1663+
1664+ /**
1665+ * \brief Set the wing aspect ratio (wingspan<sup>2</sup> / wing area)
1666+ * \param aspect wing aspect ratio
1667+ * \note <b>[Legacy aerodynamic flight model only]</b>
1668+ * \note This function defines the wing aspect ratio for the legacy flight
1669+ * model. If the vessel uses the new flight model (i.e. defines at least
1670+ * one airfoil), then this value is ignored, and the airfoil parameters
1671+ * are used instead.
1672+ * \note The aspect ratio is used in the calculation of induced drag.
1673+ * \sa GetWingAspect, SetWingEffectiveness, CreateAirfoil
1674+ */
1675+ void SetWingAspect (double aspect) const;
1676+
1677+ /**
1678+ * \brief Returns the wing form factor used in aerodynamic calculations.
1679+ * \return wing form factor
1680+ * \note <b>[Legacy aerodynamic flight model only]</b>
1681+ * \note The form factor returned by this function is only used by the
1682+ * legacy aerodynamic flight model. If the vessel uses the new flight
1683+ * model (i.e. defines at least one airfoil), then this value is ignored,
1684+ * and the airfoil parameters are used instead.
1685+ * \note The form factor, together with the aspect ratio, determines the
1686+ * amount of induced drag for given lift. Higher values of the form factor
1687+ * result in lower drag.
1688+ * \note Typical values are ~3.1 for elliptic wings, ~2.8 for tapered wings,
1689+ * and ~2.5 for rectangular wings. Default is 2.8.
1690+ * \sa SetWingEffectiveness, GetWingAspect, CreateAirfoil
1691+ */
1692+ double GetWingEffectiveness () const;
1693+
1694+ /**
1695+ * \brief Set the wing form factor for aerodynamic lift and drag calculations.
1696+ * \param eff wing form factor
1697+ * \note <b>[Legacy aerodynamic flight model only]</b>
1698+ * \note This function defines the wing form factor for the legacy flight
1699+ * model. If the vessel uses the new flight model (i.e. defines at least
1700+ * one airfoil), then this value is ignored, and the airfoil parameters
1701+ * are used instead.
1702+ * \note The form factor, together with the aspect ratio, determines the
1703+ * amount of induced drag for given lift. Higher values of the form factor
1704+ * result in lower drag.
1705+ * \note Typical values for \a eff are: ~3.1 for elliptic wings, ~2.8 for
1706+ * tapered wings, ~2.5 for rectangular wings.
1707+ * \sa GetWingEffectiveness, SetWingAspect, CreateAirfoil
1708+ */
1709+ void SetWingEffectiveness (double eff) const;
1710+
1711+ /**
1712+ * \brief Returns the vessel's atmospheric rotation resistance coefficients.
1713+ * \param rd drag coefficients for rotation around the 3 vessel axes
1714+ * \note \a rd contains the components <i>r<sub>x,y,z</sub></i> against
1715+ * rotation around the local vessel axes in atmosphere, where angular
1716+ * deceleration due to atmospheric friction is defined as a<i><sub>x,y,z</sub></i>
1717+ * = -w<i><sub>x,y,z</sub></i> <i>q</i> <i>S<sub>y</sub></i> <i>r<sub>x,y,z</sub></i>
1718+ * with angular velocity w, dynamic pressure <i>q</i> and reference surface
1719+ * <i>S<sub>y</sub></i>, defined by the vessel's cross section projected along
1720+ * the vertical (y) axis.
1721+ * \sa SetRotDrag
1722+ */
1723+ void GetRotDrag (VECTOR3 &rd) const;
1724+
1725+ /**
1726+ * \brief Set the vessel's atmospheric rotation resistance coefficients
1727+ * \param rd drag coefficients for rotation around the 3 vessel axes
1728+ * \note \a rd contains the components <i>r<sub>x,y,z</sub></i> against
1729+ * rotation around the local vessel axes in atmosphere, where angular
1730+ * deceleration due to atmospheric friction is defined as a<i><sub>x,y,z</sub></i>
1731+ * = -w<i><sub>x,y,z</sub></i> <i>q</i> <i>S<sub>y</sub></i> <i>r<sub>x,y,z</sub></i>
1732+ * with angular velocity w, dynamic pressure <i>q</i> and reference surface
1733+ * <i>S<sub>y</sub></i>, defined by the vessel's cross section projected along
1734+ * the vertical (y) axis.
1735+ * \sa GetRotDrag
1736+ */
1737+ void SetRotDrag (const VECTOR3 &rd) const;
1738+
1739+ /**
1740+ * \brief Returns the scaling factor for the pitch moment.
1741+ * \return pitch moment scale factor
1742+ * \note The pitch moment is the angular moment around the vessel's lateral
1743+ * (x) axis occurring in atmospheric flight. It works toward reducing
1744+ * the pitch angle (angle of attack).
1745+ * \note The larger the scaling factor, the stronger the effect becomes
1746+ * ("stiff handling")
1747+ * \note This value is only used with the old aerodynamic flight model,
1748+ * i.e. if no airfoils have been defined.
1749+ * \sa SetPitchMomentScale, GetYawMomentScale, CreateAirfoil
1750+ */
1751+ double GetPitchMomentScale () const;
1752+
1753+ /**
1754+ * \brief Sets the scaling factor for the pitch moment.
1755+ * \param scale scale factor for pitch moment
1756+ * \note The pitch moment is the angular moment around the vessel's lateral
1757+ * (x) axis occurring in atmospheric flight. It works toward reducing
1758+ * the pitch angle (angle of attack) between the vessel's longitudinal
1759+ * axis and the airstream vector.
1760+ * \note The larger the scaling factor, the stronger the effect becomes
1761+ * ("stiff handling")
1762+ * \note This value is only used with the old aerodynamic flight model,
1763+ * i.e. if not airfoils have been defined.
1764+ * \note The default value is 0.
1765+ * \sa GetPitchMomentScale, SetYawMomentScale, CreateAirfoil
1766+ */
1767+ void SetPitchMomentScale (double scale) const;
1768+
1769+ /**
1770+ * \brief Returns the scaling factor for the yaw moment.
1771+ * \return yaw moment scale factor
1772+ * \note The yaw moment is the angular moment around the vessel's
1773+ * vertical (y) axis occurring in atmospheric flight. It works
1774+ * toward reducing the slip angle between the vessel's longidudinal
1775+ * axis and the airstream vector.
1776+ * \note This value is only used with the old aerodynamic flight model,
1777+ * i.e. if no airfoils have been defined.
1778+ * \sa SetYawMomentScale, GetPitchMomentScale, CreateAirfoil
1779+ */
1780+ double GetYawMomentScale () const;
1781+
1782+ /**
1783+ * \brief Sets the scaling factor for the yaw moment.
1784+ * \param scale scale factor for yaw angle moment.
1785+ * \note The yaw moment is the angular moment around the vessel's
1786+ * vertical (y) axis occurring in atmospheric flight. It works
1787+ * toward reducing the slip angle between the vessel's longidudinal
1788+ * axis and the airstream vector.
1789+ * \note This value is only used with the old aerodynamic flight model,
1790+ * i.e. if not airfoils have been defined.
1791+ * \note The default value is 0.
1792+ * \sa SetPitchMomentScale, GetYawMomentScale, CreateAirfoil
1793+ */
1794+ void SetYawMomentScale (double scale) const;
1795+
1796+ /**
1797+ * \brief Returns the scaling factor for the pitch trim control.
1798+ * \return pitch trim scale factor.
1799+ * \note This function returns the value previously set with SetTrimScale
1800+ * \note It is only used with the old atmospheric flight model (if no
1801+ * airfoils have been defined).
1802+ * \sa SetTrimScale, GetPitchMomentScale, GetYawMomentScale,
1803+ * CreateAirfoil
1804+ */
1805+ double GetTrimScale () const;
1806+
1807+ /**
1808+ * \brief Sets the scaling factor for the pitch trim control.
1809+ * \param scale pitch trim scaling factor
1810+ * \note This method is used only in combination with the old flight model,
1811+ * that is, if the vessel doesn't define any airfoils. In the new
1812+ * flight model, this has been replaced by CreateControlSurface
1813+ * (AIRCTRL_ELEVATORTRIM, ...).
1814+ * \note If scale is set to zero (default) the vessel does not have a pitch
1815+ * trim control.
1816+ * \sa GetTrimScale, SetPitchMomentScale, SetYawMomentScale,
1817+ * CreateAirfoil, CreateControlSurface
1818+ */
1819+ void SetTrimScale (double scale) const;
1820+
1821+ /**
1822+ * \brief Defines the callback function for aerodynamic lift calculation.
1823+ * \param lcf pointer to callback function (see notes)
1824+ * \note <b>[Legacy aerodynamic flight model only]</b>
1825+ * \note This method defines callback function for lift calculation as a
1826+ * function of angle of attack for the legacy flight model. If the vessel
1827+ * uses the new flight model (i.e. defines at least one airfoil), then this
1828+ * value is ignored, and the airfoil parameters are used instead.
1829+ * \note The interface of the callback function is defined as
1830+ * \code typedef double (*LiftCoeffFunc)(double aoa) \endcode
1831+ * where \e aoa is the angle of attack [rad], and the return value is the
1832+ * resulting lift coefficient.
1833+ * \note The callback function must be able to process input aoa values in the
1834+ * range -Pi ... +Pi.
1835+ * \note The preferred method for defining lift and drag characteristics is via
1836+ * the CreateAirfoil method, which is much more versatile. Orbiter ignores the
1837+ * SetLiftCoeffFunc function if any airfoils have been created.
1838+ * \note If neither airfoils are defined, nor this method is called, then the
1839+ * default behaviour is not to generate any aerodynamic lift.
1840+ * \sa CreateAirfoil
1841+ */
1842+ void SetLiftCoeffFunc (LiftCoeffFunc lcf) const;
1843+ //@}
1844+
1845+
1846+ /// \name Forces
1847+ //@{
1848+ /**
1849+ * \brief Returns magnitude of aerodynamic lift force vector.
1850+ * \return Magnitude of lift force vector [N].
1851+ * \note Return value is the sum of lift components from all airfoils.
1852+ * \sa GetLiftVector, GetDrag
1853+ */
1854+ double GetLift () const;
1855+
1856+ /**
1857+ * \brief Returns magnitude of aerodynamic drag force vector.
1858+ * \return Magnitude of drag force vector [N].
1859+ * \note Return value is the sum of drag components from all airfoils.
1860+ * \sa GetDragVector, GetLift
1861+ */
1862+ double GetDrag () const;
1863+
1864+ /**
1865+ * \brief Returns gravitational force vector in local vessel coordinates.
1866+ * \param[out] G gravitational force vector [<b>N</b>]
1867+ * \return Always true.
1868+ * \note When the vessel status is updated dynamically, G is composed of
1869+ * all gravity sources currently used for the vessel propagation
1870+ * (excluding sources with contributions below threshold).
1871+ * \note During orbit stabilisation, only the contribution from the
1872+ * primary source is returned.
1873+ * \sa GetThrustVector, GetLiftVector, GetDragVector, GetForceVector
1874+ */
1875+ bool GetWeightVector (VECTOR3 &G) const;
1876+
1877+ /**
1878+ * \brief Returns thrust force vector in local vessel coordinates.
1879+ * \param[out] T thrust vector [<b>N</b>]
1880+ * \return false indicates zero thrust. In that case, the returned
1881+ * vector is (0,0,0).
1882+ * \note On return, T contains the vector sum of thrust components from
1883+ * all engines.
1884+ * \note This function provides information about the linear thrust
1885+ * force, but not about the angular moment (torque) induced.
1886+ * \sa GetWeightVector, GetLiftVector, GetDragVector, GetForceVector
1887+ */
1888+ bool GetThrustVector (VECTOR3 &T) const;
1889+
1890+ /**
1891+ * \brief Returns aerodynamic lift force vector in local vessel
1892+ * coordinates.
1893+ * \param[out] L lift vector [<b>N</b>]
1894+ * \return false indicates zero lift. In that case, the returned vector
1895+ * is (0,0,0).
1896+ * \note Return value is the sum of lift components from all airfoils.
1897+ * \note The lift vector is perpendicular to the relative wind (and thus
1898+ * to the drag vector) and has zero x-component.
1899+ * \sa GetLift, GetWeightVector, GetThrustVector, GetDragVector,
1900+ * GetForceVector
1901+ */
1902+ bool GetLiftVector (VECTOR3 &L) const;
1903+
1904+ /**
1905+ * \brief Returns aerodynamic drag force vector in local vessel
1906+ * coordinates.
1907+ * \param[out] D drag vector [<b>N</b>]
1908+ * \return false indicates zero drag. In that case, the returned vector
1909+ * is (0,0,0).
1910+ * \note On return, D contains the sum of drag components from all
1911+ * airfoils.
1912+ * \note The drag vector is parallel to the relative wind (direction of
1913+ * air flow).
1914+ * \sa GetDrag, GetWeightVector, GetThrustVector, GetLiftVector,
1915+ * GetForceVector
1916+ */
1917+ bool GetDragVector (VECTOR3 &D) const;
1918+
1919+ /**
1920+ * \brief Returns total force vector acting on the vessel in local
1921+ * vessel coordinates.
1922+ * \param[out] F total force vector [<b>N</b>]
1923+ * \return Always true
1924+ * \note On return, F contains the sum of all forces acting on the
1925+ * vessel.
1926+ * \note This may not be equal to the sum of weight, thrust, lift and
1927+ * drag vectors, because it also includes surface contact forces,
1928+ * user-defined forces and any other forces.
1929+ * \sa GetWeightVector, GetThrustVector, GetLiftVector, GetDragVector,
1930+ * GetTorqueVector
1931+ */
1932+ bool GetForceVector (VECTOR3 &F) const;
1933+
1934+ /**
1935+ * \brief Returns the total torque vector acting on the vessel in
1936+ * local vessel coordinates.
1937+ * \param[out] M total torque vector [<b>Nm</b>]
1938+ * \return Always true
1939+ * \note On return, M contains the total torque vector acting on the
1940+ * vessel in its centre of mass. The torque vector contains
1941+ * contributions from thrusters, aerodynamic forces and gravity
1942+ * gradient effects (if enabled).
1943+ * \sa GetForceVector
1944+ */
1945+ bool GetTorqueVector (VECTOR3 &M) const;
1946+
1947+ /**
1948+ * \brief Add a custom body force.
1949+ * \param F force vector [<b>N</b>]
1950+ * \param r force attack point in local vessel coordinates [<b>m</b>]
1951+ * \note This function can be used to implement custom forces (braking
1952+ * chutes, tethers, etc.). It should not be used for standard forces
1953+ * such as engine thrust or aerodynamic forces which are handled
1954+ * internally (although in theory this function makes it possible to
1955+ * bypass Orbiter's built-in thrust and aerodynamics model completely
1956+ * and replace it by a user-defined model).
1957+ * \note The force is applied only for the next time step. AddForce will
1958+ * therefore usually be used inside the VESSEL2::clbkPreStep callback
1959+ * function.
1960+ * \sa GetForceVector
1961+ */
1962+ void AddForce (const VECTOR3 &F, const VECTOR3 &r) const;
1963+ //@}
1964+
1965+
1966+ /// \name Fuel management
1967+ //@{
1968+ /**
1969+ * \brief Create a new propellant resource ("fuel tank")
1970+ *
1971+ * Propellant resources are a component of the vessel's propulsion
1972+ * system. They can hold propellants and distribute them to connected
1973+ * engines to generate thrust.
1974+ * \param maxmass maximum propellant capacity of the tank [kg]
1975+ * \param mass initial propellant mass of the resource [kg]
1976+ * \param efficiency fuel efficiency factor (>0)
1977+ * \return propellant resource handle
1978+ * \note Orbiter doesn't distinguish between propellant and oxidant. A
1979+ * "propellant resource" is assumed to be a combination of fuel and
1980+ * oxidant resources.
1981+ * \note The interpretation of a propellant resource (liquid or solid
1982+ * propulsion system, ion drive, etc.) is up to the vessel developer.
1983+ * \note The rate of fuel consumption depends on the thrust level and
1984+ * Isp (fuel-specific impulse) of the thrusters attached to the
1985+ * resource.
1986+ * \note The fuel efficiency rating, together with a thruster's Isp
1987+ * rating, determines how much fuel is consumed per second to obtain a
1988+ * given thrust: \f$R = F (e \cdot Isp)^{-1}\f$ with fuel rate R
1989+ * [kg/s], thrust F [N], efficiency e and fuel-specific impulse Isp
1990+ * [m/s].
1991+ * \note If mass < 0 then mass = maxmass is substituted.
1992+ * \sa DelPropellantResource, SetPropellantMaxMass, SetPropellantMass,
1993+ * SetPropellantEfficiency, GetPropellantMaxMass, GetPropellantMass,
1994+ * GetPropellantEfficiency
1995+ */
1996+ PROPELLANT_HANDLE CreatePropellantResource (double maxmass, double mass=-1.0, double efficiency=1.0) const;
1997+
1998+ /**
1999+ * \brief Remove a propellant resource.
2000+ * \param ph propellant resource handle (NULL on return)
2001+ * \note If any thrusters were attached to this fuel resource, they are
2002+ * disabled until connected to a new fuel resource.
2003+ * \sa CreatePropellantResource, ClearPropellantResources
2004+ */
2005+ void DelPropellantResource (PROPELLANT_HANDLE &ph) const;
2006+
2007+ /**
2008+ * \brief Remove all propellant resources for the vessel.
2009+ * \note After a call to this function, all the vessel's thrusters will
2010+ * be disabled until they are linked to new resources.
2011+ * \sa DelPropellantResource
2012+ */
2013+ void ClearPropellantResources () const;
2014+
2015+ /**
2016+ * \brief Returns the current number of vessel propellant resources.
2017+ * \return Number of propellant resources currently defined for the
2018+ * vessel.
2019+ * \sa CreatePropellantResource, GetPropellantHandleByIndex
2020+ */
2021+ DWORD GetPropellantCount () const;
2022+
2023+ /**
2024+ * \brief Returns the handle of a propellant resource for a given index.
2025+ * \param idx propellant resource index (>= 0)
2026+ * \return Propellant resource handle
2027+ * \note The index must be in the range between 0 and
2028+ * GetPropellantCount()-1. If the index is out of range, the returned
2029+ * handle is NULL.
2030+ * \note The index of a given propellant resource may change if any
2031+ * resources are deleted. The handle remains valid until the
2032+ * corresponding resource is deleted.
2033+ * \sa CreatePropellantResource, GetPropellantCount
2034+ */
2035+ PROPELLANT_HANDLE GetPropellantHandleByIndex (DWORD idx) const;
2036+
2037+ /**
2038+ * \brief Returns the maximum capacity of a propellant resource.
2039+ * \param ph propellant resource handle
2040+ * \return Max. propellant capacity [kg].
2041+ * \sa SetPropellantMaxMass, GetPropellantMass, SetPropellantMass
2042+ */
2043+ double GetPropellantMaxMass (PROPELLANT_HANDLE ph) const;
2044+
2045+ /**
2046+ * \brief Reset the maximum capacity of a fuel resource.
2047+ * \param ph propellant resource handle
2048+ * \param maxmass max. fuel capacity (>= 0) [kg]
2049+ * \note The actual fuel mass contained in the tank is not affected by
2050+ * this function, unless the new maximum propellant mass is less than
2051+ * the current fuel mass, in which case the fuel mass is reduced to
2052+ * the maximum capacity.
2053+ * \sa GetPropellantMaxMass, SetPropellantMass, GetPropellantMass,
2054+ * GetTotalPropellantMass, GetFuelMass, SetPropellantEfficiency
2055+ */
2056+ void SetPropellantMaxMass (PROPELLANT_HANDLE ph, double maxmass) const;
2057+
2058+ /**
2059+ * \brief Returns the current mass of a propellant resource.
2060+ * \param ph propellant resource handle
2061+ * \return Current propellant mass [kg].
2062+ * \sa SetPropellantMass, GetPropellantMaxMass, SetPropellantMaxMass
2063+ */
2064+ double GetPropellantMass (PROPELLANT_HANDLE ph) const;
2065+
2066+ /**
2067+ * \brief Reset the current mass of a propellant resource.
2068+ * \param ph propellant resource handle
2069+ * \param mass propellant mass (>= 0) [kg]
2070+ * \note 0 <= mass <= maxmass is required, where maxmass is the maximum
2071+ * capacity of the propellant resource.
2072+ * \note This method should be used to simulate refuelling, fuel leaks,
2073+ * cross-feeding between tanks, etc. but not for normal fuel
2074+ * consumption by thrusters (which is handled internally by the
2075+ * Orbiter core).
2076+ * \sa GetPropellantMass, SetPropellantMaxMass, GetTotalPropellantMass,
2077+ * GetFuelMass, SetPropellantEfficiency
2078+ */
2079+ void SetPropellantMass (PROPELLANT_HANDLE ph, double mass) const;
2080+
2081+ /**
2082+ * \brief Returns the vessel's current total propellant mass.
2083+ * \return Sum of current mass of all propellant resources defined for
2084+ * the vessel [kg].
2085+ * \sa GetPropellantMass, GetPropellantMaxMass
2086+ */
2087+ double GetTotalPropellantMass () const;
2088+
2089+ /**
2090+ * \brief Returns the efficiency factor of a propellant resource.
2091+ * \param ph propellant resource handle
2092+ * \return Fuel efficiency factor
2093+ * \note The fuel efficiency rating, together witha thruster's Isp
2094+ * rating, determines how much fuel is consumed per second to obtain
2095+ * a given thrust: R = F/(e Isp) with fuel rate R [kg/s], thrust F [N],
2096+ * efficiency e and fuel-specific impulse Isp [m/s].
2097+ * \sa SetPropellantEfficiency, GetPropellantMaxMass,
2098+ * CreatePropellantResource
2099+ */
2100+ double GetPropellantEfficiency (PROPELLANT_HANDLE ph) const;
2101+
2102+ /**
2103+ * \brief Reset the efficiency factor of a fuel resource.
2104+ * \param ph propellant resource handle
2105+ * \param efficiency fuel efficiency factor (> 0)
2106+ * \note The fuel efficiency rating, together witha thruster's Isp
2107+ * rating, determines how much fuel is consumed per second to obtain
2108+ * a given thrust: R = F/(e Isp) with fuel rate R [kg/s], thrust F [N],
2109+ * efficiency e and fuel-specific impulse Isp [m/s].
2110+ * \sa GetPropellantEfficiency, CreatePropellantResource,
2111+ * SetPropellantMaxMass, SetPropellantMass
2112+ */
2113+ void SetPropellantEfficiency (PROPELLANT_HANDLE ph, double efficiency) const;
2114+
2115+ /**
2116+ * \brief Returns the current mass flow rate from a propellant resource.
2117+ * \param ph propellant resource handle
2118+ * \return Current propellant mass flow rate [kg/s].
2119+ * \sa GetPropellantMass, GetTotalPropellantFlowrate, GetFuelRate
2120+ */
2121+ double GetPropellantFlowrate (PROPELLANT_HANDLE ph) const;
2122+
2123+ /**
2124+ * \brief Returns the current total mass flow rate, summed over all
2125+ * propellant resources.
2126+ * \return Total propellant mass flow rate [kg/s].
2127+ * \sa GetPropellantFlowrate, GetFuelRate
2128+ */
2129+ double GetTotalPropellantFlowrate () const;
2130+
2131+ /**
2132+ * \brief Define a "default" propellant resource.
2133+ *
2134+ * This is used for the various legacy fuel-related API functions, and
2135+ * for the "Fuel" indicator in the generic panel-less HUD display.
2136+ * \param ph propellant resource handle
2137+ * \note If this function is not called, the first propellant resource
2138+ * is used as default.
2139+ * \sa CreatePropellantResource, GetDefaultPropellantResource
2140+ */
2141+ void SetDefaultPropellantResource (PROPELLANT_HANDLE ph) const;
2142+
2143+ /**
2144+ * \brief Returns the handle for the vessel's default propellant resource.
2145+ * \return Default propellant resource handle
2146+ * \sa SetDefaultPropellantResource
2147+ */
2148+ PROPELLANT_HANDLE GetDefaultPropellantResource () const;
2149+
2150+ /**
2151+ * \brief Returns the maximum capacity of the vessel's default propellant
2152+ * resource.
2153+ * \return Max. capacity of default propellant resource [kg].
2154+ * \note The function returns 0 if no fuel resources are defined.
2155+ * \sa GetPropellantMaxMass, SetDefaultPropellantResource
2156+ */
2157+ double GetMaxFuelMass () const;
2158+
2159+ /**
2160+ * \brief Set the maximum fuel capacity of the vessel's default
2161+ * propellant resource.
2162+ * \param mass max. propellant mass [kg].
2163+ * \note If no propellant resources are defined for the vessel, a call
2164+ * to this method creates a new propellant resource with the specified
2165+ * capacity.
2166+ * \note If the vessel already contains propellant resources, this
2167+ * method resets the maximum capacity of the vessel's default resource.
2168+ * \sa SetPropellantMaxMass, SetDefaultPropellantResource
2169+ */
2170+ void SetMaxFuelMass (double mass) const;
2171+
2172+ /**
2173+ * \brief Returns the current mass of the vessel's default propellant
2174+ * resource.
2175+ * \return Current mass of the default propellant resource [kg].
2176+ * \sa GetPropellantMass, SetDefaultPropellantResource
2177+ */
2178+ double GetFuelMass () const;
2179+
2180+ /**
2181+ * \brief Reset the current mass of the vessel's default propellant
2182+ * resource.
2183+ * \param mass new propellant mass [kg].
2184+ * \note mass must be between 0 and the maximum capacity of the
2185+ * propellant resource.
2186+ * \note If the vessel has not defined any propellant resources, this
2187+ * method has no effect.
2188+ * \sa GetFuelMass, SetPropellantMass, SetMaxFuelMass,
2189+ * SetDefaultPropellantResource
2190+ */
2191+ void SetFuelMass (double mass) const;
2192+
2193+ /**
2194+ * \brief Returns the current mass flow rate from the default propellant
2195+ * resource.
2196+ * \return Current mass flow rate from the default propellant resource
2197+ * [kg/s].
2198+ * \sa GetPropellantFlowrate, SetDefaultPropellantResource
2199+ */
2200+ double GetFuelRate () const;
2201+ //@}
2202+
2203+ /// \name Thruster management
2204+ //@{
2205+ /**
2206+ * \brief Add a logical thruster definition for the vessel.
2207+ * \param pos thrust force attack point in vessel coordinates [<b>m</b>]
2208+ * \param dir thrust force direction in vessel coordinates (normalised)
2209+ * \param maxth0 max. vacuum thrust rating [N]
2210+ * \param hp propellant resource feeding the thruster
2211+ * \param isp0 vacuum fuel-specific impulse (Isp) [m/s]
2212+ * \param isp_ref Isp value at reference pressure p_ref [m/s]
2213+ * \param p_ref reference pressure for Isp_ref [Pa]
2214+ * \return Thruster identifier
2215+ * \note The fuel-specific impulse defines how much thrust is produced
2216+ * by burning 1kg of fuel per second. If the Isp level is not
2217+ * specified or is = 0, a default value is used (see SetISP()).
2218+ * \note To define the thrust and Isp ratings to be pressure-dependent,
2219+ * specify an isp_ref value > 0, and set p_ref to the corresponding
2220+ * atmospheric pressure. Thrust and Isp at pressure p will then be
2221+ * calculated as
2222+ * \f[
2223+ * \mathrm{Isp}(p) = \mathrm{Isp}_0(1-p\eta), \qquad
2224+ * \mathrm{Th}(p) = \mathrm{Th}_0(1-p\eta), \qquad \mathrm{where}\qquad
2225+ * \eta = \frac{\mathrm{Isp}_0 - \mathrm{Isp}_\mathrm{ref}}{p_\mathrm{ref} \mathrm{Isp}_0}
2226+ * \f]
2227+ * \note If isp_ref = 0 then no pressure-dependency is assumed (\f$\eta=0\f$).
2228+ * \note If no propellant resource is specified, the thruster is
2229+ * disabled until it is linked to a resource by SetThrusterResource().
2230+ * \note If isp0 <= 0, then the default Isp value is substituted (see SetISP()).
2231+ * \note Thruster forces can create linear as well as angular
2232+ * moments, depending on the attack point and direction.
2233+ * \note Use CreateThrusterGroup to assemble thrusters into logical
2234+ * groups.
2235+ * \sa DelThruster, CreateThrusterGroup, AddExhaust, SetISP,
2236+ * SetThrusterIsp, SetThrusterResource
2237+ */
2238+ THRUSTER_HANDLE CreateThruster (const VECTOR3 &pos, const VECTOR3 &dir, double maxth0,
2239+ PROPELLANT_HANDLE hp=NULL, double isp0=0.0, double isp_ref=0.0, double p_ref=101.4e3) const;
2240+
2241+ /**
2242+ * \brief Delete a logical thruster definition.
2243+ * \param th thruster handle (NULL on return)
2244+ * \return true on success, false if the supplied thruster handle was
2245+ * invalid.
2246+ * \note Deleted thrusters will be automatically removed from all
2247+ * thruster groups they had been assigned to.
2248+ * \note All exhaust render definitions which refer to the deleted
2249+ * thruster are removed.
2250+ * \sa CreateThruster, CreateThrusterGroup, AddExhaust
2251+ */
2252+ bool DelThruster (THRUSTER_HANDLE &th) const;
2253+
2254+ /**
2255+ * \brief Delete all thruster and thruster group definitions.
2256+ * \note This function removes all thruster definitions, as well as all
2257+ * the thruster group definitions.
2258+ * \note It also removes all previously defined exhaust render
2259+ * definitions.
2260+ * \sa CreateThruster, DelThruster, CreateThrusterGroup, AddExhaust
2261+ */
2262+ void ClearThrusterDefinitions () const;
2263+
2264+ /**
2265+ * \brief Returns the number of thrusters currently defined.
2266+ * \return Number of logical thruster definitions.
2267+ * \sa CreateThruster, GetThrusterHandleByIndex
2268+ */
2269+ DWORD GetThrusterCount () const;
2270+
2271+ /**
2272+ * \brief Returns the handle of a thruster specified by its index.
2273+ * \param idx thruster index (>= 0)
2274+ * \return Thruster handle
2275+ * \note The index must be in the range between 0 and nthruster-1,
2276+ * where nthruster is the thruster count returned by
2277+ * GetThrusterCount(). If the index is out of range, the returned
2278+ * handle is NULL.
2279+ * \note The index of a given thruster may change if vessel thrusters
2280+ * are deleted. The handle remains valid until the corresponding
2281+ * thruster is deleted.
2282+ * \sa CreateThruster, DelThruster, GetThrusterCount
2283+ */
2284+ THRUSTER_HANDLE GetThrusterHandleByIndex (DWORD idx) const;
2285+
2286+ /**
2287+ * \brief Returns a handle for the propellant resource feeding the
2288+ * thruster.
2289+ * \param th thruster handle
2290+ * \return Propellant resource handle, or NULL if the thruster is not
2291+ * connected.
2292+ * \sa SetThrusterResource, CreateThruster
2293+ */
2294+ PROPELLANT_HANDLE GetThrusterResource (THRUSTER_HANDLE th) const;
2295+
2296+ /**
2297+ * \brief Connect a thruster to a propellant resource.
2298+ * \param th thruster handle
2299+ * \param ph propellant resource handle
2300+ * \note A thruster can only be connected to one propellant resource at
2301+ * a time. Setting a new resource disconnects from the previous
2302+ * resource.
2303+ * \note To disconnect the thruster from its current tank, use \a ph = NULL.
2304+ * \sa GetThrusterResource
2305+ */
2306+ void SetThrusterResource (THRUSTER_HANDLE th, PROPELLANT_HANDLE ph) const;
2307+
2308+ /**
2309+ * \brief Returns the thrust force attack point of a thruster.
2310+ * \param[in] th thruster handle
2311+ * \param[out] pos thrust attack point [<b>m</b>]
2312+ * \note \a pos is returned in the vessel frame of reference.
2313+ * \sa SetThrusterRef, GetThrusterDir
2314+ */
2315+ void GetThrusterRef (THRUSTER_HANDLE th, VECTOR3 &pos) const;
2316+
2317+ /**
2318+ * \brief Reset the thrust force attack point of a thruster.
2319+ * \param th thruster handle
2320+ * \param pos new force attack point [<b>m</b>]
2321+ * \note \a pos is specified in the vessel reference system.
2322+ * \note This method should be used whenever a thruster has been
2323+ * physically moved in the vessel's local frame of reference.
2324+ * \note If the vessel's centre of gravity, i.e. the origin of its
2325+ * reference system, is moved with ShiftCG(), the thruster positions
2326+ * are updated automatically.
2327+ * \note The attack point has no influence on the linear force exerted
2328+ * on the vessel by the thruster, but it affects the induced torque.
2329+ * \sa GetThrusterRef, CreateThruster, ShiftCG, SetThrusterDir
2330+ */
2331+ void SetThrusterRef (THRUSTER_HANDLE th, const VECTOR3 &pos) const;
2332+
2333+ /**
2334+ * \brief Returns the force direction of a thruster.
2335+ * \param[in] th thruster handle
2336+ * \param[out] dir thrust direction (vessel frame of reference)
2337+ * \sa SetThrusterDir, GetThrusterRef
2338+ */
2339+ void GetThrusterDir (THRUSTER_HANDLE th, VECTOR3 &dir) const;
2340+
2341+ /**
2342+ * \brief Reset the force direction of a thruster.
2343+ * \param th thruster handle
2344+ * \param dir new thrust direction (vessel frame of reference)
2345+ * \note This method can be used to realise a tilt of the rocket
2346+ * motor (e.g. for implementing a thruster gimbal mechanism)
2347+ * \sa GetThrusterDir, CreateThruster, SetThrusterRef
2348+ */
2349+ void SetThrusterDir (THRUSTER_HANDLE th, const VECTOR3 &dir) const;
2350+
2351+ /**
2352+ * \brief Returns the maximum vacuum thust rating of a thruster.
2353+ * \param th thruster handle
2354+ * \return Maximum vacuum thust rating [N]
2355+ * \note To retrieve the actual current maximum thrust rating (which may
2356+ * be lower in the presence of ambient atmospheric pressure), use
2357+ * GetThrusterMax().
2358+ * \sa SetThrusterMax0,\n
2359+ * GetThrusterMax(THRUSTER_HANDLE)const,\n
2360+ * GetThrusterMax(THRUSTER_HANDLE,double)const
2361+ */
2362+ double GetThrusterMax0 (THRUSTER_HANDLE th) const;
2363+
2364+ /**
2365+ * \brief Reset the maximum vacuum thrust rating of a thruster.
2366+ * \param th thruster handle
2367+ * \param maxth0 new maximum vacuum thrust rating [N]
2368+ * \note The max. thrust rating in the presence of atmospheric ambient
2369+ * pressure may be lower than the vacuum thrust if a pressure-dependent
2370+ * Isp value has been defined.
2371+ * \sa GetThrusterMax0, CreateThruster,\n
2372+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2373+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const
2374+ */
2375+ void SetThrusterMax0 (THRUSTER_HANDLE th, double maxth0) const;
2376+
2377+ /**
2378+ * \brief Returns the current maximum thrust rating of a thruster.
2379+ * \param th thruster handle
2380+ * \return Max. thrust rating a the current atmospheric pressure [N].
2381+ * \note If a pressure-dependent Isp rating has been defined for the
2382+ * thruster, and if the vessel is moving through a planetary
2383+ * atmosphere, this method returns the maximum thrust rating given
2384+ * the current atmospheric pressure.
2385+ * \note Otherwise it returns the maximum vacuum thrust rating of the
2386+ * thruster.
2387+ * \sa GetThrusterMax(THRUSTER_HANDLE,double)const,\n
2388+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2389+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2390+ * CreateThruster
2391+ */
2392+ double GetThrusterMax (THRUSTER_HANDLE th) const;
2393+
2394+ /**
2395+ * \brief Returns the maximum thrust rating of a thruster at a specific
2396+ * ambient pressure.
2397+ * \param th thruster handle
2398+ * \param p_ref reference pressure [Pa]
2399+ * \return Max. thrust rating a atmospheric pressure \a p_ref [N].
2400+ * \note If a pressure-dependent Isp rating has been defined for the
2401+ * thruster, and if the vessel is moving through a planetary
2402+ * atmosphere, this method returns the maximum thrust rating at
2403+ * ambient pressure \a p_ref.
2404+ * \note Otherwise it returns the maximum vacuum thrust rating of the
2405+ * thruster.
2406+ * \sa GetThrusterMax(THRUSTER_HANDLE)const,\n
2407+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2408+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2409+ * CreateThruster
2410+ */
2411+ double GetThrusterMax (THRUSTER_HANDLE th, double p_ref) const;
2412+
2413+ /**
2414+ * \brief Returns the vacuum fuel-specific impulse (Isp) rating for a
2415+ * thruster.
2416+ * \param th thruster handle
2417+ * \return Isp value in vacuum [m/s]
2418+ * \note Equivalent to GetThrusterIsp (th,0)
2419+ * \sa GetThrusterIsp(THRUSTER_HANDLE)const,\n
2420+ * GetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2421+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2422+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2423+ * CreateThruster
2424+ */
2425+ double GetThrusterIsp0 (THRUSTER_HANDLE th) const;
2426+
2427+ /**
2428+ * \brief Returns the current fuel-specific impulse (Isp) rating of a
2429+ * thruster.
2430+ * \param th thruster handle
2431+ * \return Current Isp value [m/s].
2432+ * \note If the vessel is moving within a planetary atmosphere, and if a
2433+ * pressure-dependent Isp rating has been defined for this thruster,
2434+ * the returned Isp value will vary with ambient atmospheric pressure.
2435+ * \sa GetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2436+ * GetThrusterIsp0,\n
2437+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2438+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2439+ * CreateThruster
2440+ */
2441+ double GetThrusterIsp (THRUSTER_HANDLE th) const;
2442+
2443+ /**
2444+ * \brief Returns the fuel-specific impulse (Isp) rating of a thruster
2445+ * at a specific ambient atmospheric pressure.
2446+ * \param th thruster handle
2447+ * \param p_ref reference pressure [Pa]
2448+ * \return Isp value at ambient pressure \a p_ref [m/s].
2449+ * \note If no pressure-dependent Isp rating has been defined for this
2450+ * thruster, it will always return the vacuum rating, independent of
2451+ * the specified pressure.
2452+ * \note To obtain vacuum Isp rating, set \a p_ref to 0.
2453+ * \note To obtain the Isp rating at (Earth) sea level, set \a p_ref =
2454+ * 101.4e3.
2455+ * \sa GetThrusterIsp(THRUSTER_HANDLE)const,\n
2456+ * GetThrusterIsp0,\n
2457+ * SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2458+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2459+ * CreateThruster
2460+ */
2461+ double GetThrusterIsp (THRUSTER_HANDLE th, double p_ref) const;
2462+
2463+ /**
2464+ * \brief Reset the fuel-specific impulse (Isp) rating of a thruster,
2465+ * assuming no pressure dependence.
2466+ * \param th thruster handle
2467+ * \param isp new Isp rating [m/s]
2468+ * \note The Isp value correlates the propellant mass flow rate dm/dt
2469+ * with the resulting thrust force F:
2470+ * F = Isp (dm/dt).
2471+ * \note In the engineering literature, fuel-specific impulse is
2472+ * sometimes given in units of time, by dividing the Isp as defined
2473+ * above by the gravitational acceleration 1g = 9.81 m/s<sup>2</sup>.
2474+ * \note The specified Isp value is assumed to be independent of ambient
2475+ * atmospheric pressure. To define a pressure-dependent Isp value, use
2476+ * SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const.
2477+ * \sa SetThrusterIsp(THRUSTER_HANDLE,double,double,double)const,\n
2478+ * GetThrusterIsp(THRUSTER_HANDLE)const,\n
2479+ * GetThrusterIsp(THRUSTER_HANDLE,double)const, GetThrusterIsp0,\n
2480+ * CreateThruster
2481+ */
2482+ void SetThrusterIsp (THRUSTER_HANDLE th, double isp) const;
2483+
2484+ /**
2485+ * \brief Reset the fuel-specific impulse (Isp) rating of a thruster
2486+ * including a pressure dependency.
2487+ * \param th thruster handle
2488+ * \param isp0 vacuum Isp rating [m/s]
2489+ * \param isp_ref Isp rating at ambient pressure \a p_ref [m/s]
2490+ * \param p_ref reference pressure [Pa] for isp_ref (defaults to Earth
2491+ * sea level pressure)
2492+ * \note See SetThrusterIsp(THRUSTER_HANDLE,double)const for a
2493+ * definition of the relationship between Isp, thrust and fuel mass
2494+ * flow rate.
2495+ * \sa SetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2496+ * GetThrusterIsp(THRUSTER_HANDLE)const,\n
2497+ * GetThrusterIsp(THRUSTER_HANDLE,double)const,\n
2498+ * GetThrusterIsp0, CreateThruster
2499+ */
2500+ void SetThrusterIsp (THRUSTER_HANDLE th, double isp0, double isp_ref, double p_ref=101.4e3) const;
2501+
2502+ /**
2503+ * \brief Returns the current thrust level setting of a thruster.
2504+ * \param th thruster handle
2505+ * \return Current thrust level (0...1)
2506+ * \note To obtain the actual force [N] currently generated by the
2507+ * thruster, multiply the thrust level with the max. thrust rating
2508+ * returned by GetThrusterMax().
2509+ * \sa GetThrusterMax, SetThrusterLevel
2510+ */
2511+ double GetThrusterLevel (THRUSTER_HANDLE th) const;
2512+
2513+ /**
2514+ * \brief Set thrust level for a thruster.
2515+ * \param th thruster handle
2516+ * \param level thrust level (0...1)
2517+ * \note At level 1 the thruster generates maximum force, as defined by
2518+ * its maxth parameter.
2519+ * \note Certain thrusters are controlled directly by Orbiter via
2520+ * primary input controls (e.g. joystick throttle control for main
2521+ * thrusters), which may override this function.
2522+ * \sa IncThrusterLevel, GetThrusterLevel
2523+ */
2524+ void SetThrusterLevel (THRUSTER_HANDLE th, double level) const;
2525+
2526+ /**
2527+ * \brief Apply a change to the thrust level of a thruster.
2528+ * \param th thruster handle
2529+ * \param dlevel thrust level change (-1...1)
2530+ * \note The applied thrust level change is limited to give a resulting
2531+ * thrust level in the range (0...1).
2532+ * \sa SetThrusterLevel, GetThrusterLevel
2533+ */
2534+ void IncThrusterLevel (THRUSTER_HANDLE th, double dlevel) const;
2535+
2536+ /**
2537+ * \brief Set the thrust level of a thruster for the current time step
2538+ * only.
2539+ * \param th thruster handle
2540+ * \param level thrust level (0...1)
2541+ * \note At level 1 the thruster generates maximum force, as defined by
2542+ * its maxth parameter.
2543+ * \note This method overrides the thruster's permanent thrust level
2544+ * for the current time step only, so it should normally only be used
2545+ * in the body of the VESSEL2::clbkPreStep() method.
2546+ * \sa SetThrusterLevel, VESSEL2::clbkPreStep()
2547+ */
2548+ void SetThrusterLevel_SingleStep (THRUSTER_HANDLE th, double level) const;
2549+
2550+ /**
2551+ * \brief Apply a thrust level change to a thruster for the current time
2552+ * step only.
2553+ * \param th thruster handle
2554+ * \param dlevel thrust level change (-1...1)
2555+ * \note This method overrides the thruster's permanent thrust level for
2556+ * the current time step only, so it should normally only be used in
2557+ * the body of the VESSEL2::clbkPreStep() method.
2558+ * \note This method may be overridden by manual user input via keyboard
2559+ * and joystick, or by automatic attitude sequences.
2560+ * \note The applied thrust level change is limited to give a resulting
2561+ * thrust level in the range (0...1).
2562+ * \sa SetThrusterLevel_SingleStep, IncThrusterLevel, VESSEL2::clbkPreStep()
2563+ */
2564+ void IncThrusterLevel_SingleStep (THRUSTER_HANDLE th, double dlevel) const;
2565+
2566+ /**
2567+ * \brief Returns the linear moment (force) and angular moment (torque)
2568+ * currently generated by a thruster.
2569+ * \param th thruster handle
2570+ * \param F linear force [N]
2571+ * \param T torque [Nm]
2572+ * \note The returned values include the influence of ambient pressure
2573+ * on the thrust generated by the engine.
2574+ */
2575+ void GetThrusterMoment (THRUSTER_HANDLE th, VECTOR3 &F, VECTOR3 &T) const;
2576+
2577+ /**
2578+ * \brief Returns the vessel's current default fuel-specific impulse.
2579+ * \return Fuel-specific impulse [m/s]. The is the amount of thrust
2580+ * [N] obtained by burning 1kg of fuel per second.
2581+ * \note The function returns the current default Isp value which will be
2582+ * used for all subsequently defined thrusters which do not define
2583+ * their individual Isp settings.
2584+ * \note To obtain an actual Isp value for a thruster, use GetThrusterISP.
2585+ * \note The default Isp value can be set by the SetISP() method, or via the
2586+ * 'Isp' entry in the vessel configuration file. If not defined, the default
2587+ * value is 5e4.
2588+ * \sa SetISP, GetThrusterISP
2589+ */
2590+ double GetISP () const;
2591+
2592+ /**
2593+ * \brief Sets the default Isp value for subsequently created thrusters.
2594+ * \param isp fuel-specific impulse [m/s]
2595+ * \note The Isp value defines the amount of thrust [N] obtained by burning 1
2596+ * kg of fuel per second.
2597+ * \note Resetting the default Isp value affects only thrusters which are
2598+ * created subsequently, and which don't define individual Isp values.
2599+ * \note Before the first call to SetISP, the initial value is read from
2600+ * the 'Isp' entry of the vessel definition file. If no entry exists, a value
2601+ * of 5e4 is used.
2602+ * \note It is recommended to define individual Isp values during thruster
2603+ * creation instead of using SetISP.
2604+ */
2605+ void SetISP (double isp) const;
2606+ //@}
2607+
2608+ /// \name Thruster group management
2609+ //@{
2610+ /**
2611+ * \brief Combine thrusters into a logical group.
2612+ * \param th array of thruster handles to form a group
2613+ * \param nth number of thrusters in the array
2614+ * \param thgt thruster group type (see \ref thrusterparam)
2615+ * \return thruster group handle
2616+ * \note Thruster groups (except for user-defined groups) are engaged by
2617+ * Orbiter as a result of user input. For example, pushing the stick backward
2618+ * in rotational attitude mode will engage the thrusters in the
2619+ * THGROUP_ATT_PITCHUP group.
2620+ * \note It is the responsibility of the vessel designer to make sure that the
2621+ * thruster groups are designed so that they behave in a sensible way.
2622+ * \note Thrusters can be added to more than one group. For example, an
2623+ * attitude thruster can be simultaneously grouped into THGROUP_ATT_PITCHUP
2624+ * and THGROUP_ATT_UP.
2625+ * \note Rotational thrusters should be designed so that they don't induce a
2626+ * significant linear momentum. This means rotational groups require at least
2627+ * 2 thrusters each.
2628+ * \note Linear thrusters should be designed such that they don't induce a
2629+ * significant angular momentum.
2630+ * \note If a vessel does not define a complete set of attitude thruster
2631+ * groups, certain navmode sequences (e.g. KILLROT) may fail.
2632+ * \sa DelThrusterGroup, CreateThruster, thrusterparam
2633+ */
2634+ THGROUP_HANDLE CreateThrusterGroup (THRUSTER_HANDLE *th, int nth, THGROUP_TYPE thgt) const;
2635+
2636+ /**
2637+ * \brief Delete a thruster group and (optionally) all associated thrusters.
2638+ * \param thg thruster group handle
2639+ * \param delth thruster destruction flag (see notes)
2640+ * \return \e true on success.
2641+ * \note If \a delth==true, all thrusters associated with the group will be
2642+ * destroyed. Note that this can have side effects if the thrusters were
2643+ * associated with multiple groups, since they are removed from all those
2644+ * groups as well.
2645+ * \sa DelThrusterGroup(THGROUP_TYPE,bool)const, CreateThrusterGroup,
2646+ * DelThruster, thrusterparam
2647+ */
2648+ bool DelThrusterGroup (THGROUP_HANDLE thg, bool delth = false) const;
2649+
2650+ /**
2651+ * \brief Delete a default thruster group and (optionally) all associated
2652+ * thrusters.
2653+ * \param thgt thruster group type (excluding THGROUP_USER)
2654+ * \param delth thruster destruction flag
2655+ * \return \e true on success
2656+ * \note This version can only be used for default thruster groups
2657+ * (< THGROUP_USER).
2658+ * \note If \a delth==true, all thrusters associated with the group will be
2659+ * destroyed. Note that this can have side effects if the thrusters were
2660+ * associated with multiple groups, since they are removed from all those
2661+ * groups as well.
2662+ * \sa DelThrusterGroup(THGROUP_HANDLE,bool)const,
2663+ * CreateThrusterGroup, DelThruster, thrusterparam
2664+ */
2665+ bool DelThrusterGroup (THGROUP_TYPE thgt, bool delth = false) const;
2666+
2667+ /**
2668+ * \brief Returns the handle of a default thruster group.
2669+ * \param thgt thruster group type (see \ref thrusterparam)
2670+ * \return thruster group handle (or NULL if no group is defined for the
2671+ * specified type).
2672+ * \note The thruster group type must not be THGROUP_USER. To retrieve the
2673+ * handle of a nonstandard thruster group, use
2674+ * GetUserThrusterGroupHandleByIndex().
2675+ * \sa GetUserThrusterGroupHandleByIndex
2676+ */
2677+ THGROUP_HANDLE GetThrusterGroupHandle (THGROUP_TYPE thgt) const;
2678+
2679+ /**
2680+ * \brief Returns the handle of a user-defined (nonstandard) thruster group.
2681+ * \param idx index of user-defined thruster group (>= 0)
2682+ * \return thruster group handle (or NULL if index out of range)
2683+ * \note Use this method only to retrieve handles for nonstandard thruster
2684+ * groups (created with the THGROUP_USER flag). For standard groups, use
2685+ * GetThrusterGroupHandle() instead.
2686+ * \note The index must be in the range between 0 and nuserthgroup-1, where
2687+ * nuserthgroup is the number of nonstandard thruster groups. Use
2688+ * GetUserThrusterGroupCount() to obtain this value.
2689+ * \sa GetThrusterGroupHandle, GetUserThrusterGroupCount
2690+ */
2691+ THGROUP_HANDLE GetUserThrusterGroupHandleByIndex (DWORD idx) const;
2692+
2693+ /**
2694+ * \brief Returns the number of thrusters assigned to a logical thruster group.
2695+ * \param thg thruster group handle
2696+ * \return Number of thrusters assigned to the specified thruster group.
2697+ * \note Thrusters can be assigned to more than one group (and some thrusters
2698+ * may not be assigned to any group) so the sum of GetGroupThrusterCount
2699+ * values over all groups can be different to the total number of thrusters.
2700+ * \sa GetGroupThrusterCount(THGROUP_TYPE)const
2701+ */
2702+ DWORD GetGroupThrusterCount (THGROUP_HANDLE thg) const;
2703+
2704+ /**
2705+ * \brief Returns the number of thrusters assigned to a standard logical thruster
2706+ * group.
2707+ * \param thgt thruster group enumeration type (see \ref thrusterparam)
2708+ * \return Number of thrusters assigned to the specified thruster group.
2709+ * \note This function only works for standard group types. Do not use it with
2710+ * THGROUP_USER. For user-defined groups, use
2711+ * VESSEL::GetGroupThrusterCount(THGROUP_HANDLE)const instead.
2712+ * \note Thrusters can be assigned to more than one group (and some thrusters
2713+ * may not be assigned to any group) so the sum of GetGroupThrusterCount
2714+ * values over all groups can be different to the overall number of thrusters.
2715+ * \sa GetGroupThrusterCount(THGROUP_HANDLE)const
2716+ */
2717+ DWORD GetGroupThrusterCount (THGROUP_TYPE thgt) const;
2718+
2719+ /**
2720+ * \brief Returns a handle for a thruster that belongs to a specified thruster
2721+ * group.
2722+ * \param thg thruster group handle
2723+ * \param idx thuster index (0 <= idx < GetGroupThrusterCount())
2724+ * \return Thuster handle
2725+ */
2726+ THRUSTER_HANDLE GetGroupThruster (THGROUP_HANDLE thg, DWORD idx) const;
2727+
2728+ /**
2729+ * \brief Returns a handle for a thruster that belongs to a standard thruster
2730+ * group.
2731+ * \param thgt thruster group enumeration type (see \ref thrusterparam)
2732+ * \param idx thruster index (0 <= idx < GetGroupThrusterCount())
2733+ * \return Thruster handle
2734+ * \note This function only works for standard group types. Do not use with
2735+ * THGROUP_USER. For user-defined groups, use GetGroupThruster(THGROUP_HANDLE,DWORD)const.
2736+ */
2737+ THRUSTER_HANDLE GetGroupThruster (THGROUP_TYPE thgt, DWORD idx) const;
2738+
2739+ /**
2740+ * \brief Returns the number of user-defined (nonstandard) thruster groups.
2741+ * \return Number of user-defined thruster groups.
2742+ * \note The value returned by this method only includes user-defined thruster
2743+ * groups (created with the THGROUP_USER flag). It does not contain any standard
2744+ * thruster groups (such as THGROUP_MAIN, etc.)
2745+ */
2746+ DWORD GetUserThrusterGroupCount () const;
2747+
2748+ /**
2749+ * \brief Indicates if a default thruster group is defined by the vessel.
2750+ * \param thgt thruster group enumeration type (see \ref thrusterparam)
2751+ * \return \e true if the group contains any thrusters, \e false otherwise.
2752+ * \note This method only works for default groups. Do not use with
2753+ * THGROUP_USER.
2754+ * \note A group is considered to be "defined" if it contains at least one
2755+ * thruster.
2756+ * \sa GetGroupThrusterCount
2757+ */
2758+ bool ThrusterGroupDefined (THGROUP_TYPE thgt) const;
2759+
2760+ /**
2761+ * \brief Sets the thrust level for all thrusters in a group.
2762+ * \param thg thruster group identifier
2763+ * \param level new thrust level (range 0-1)
2764+ * \sa SetThrusterGroupLevel(THGROUP_TYPE,double)const
2765+ */
2766+ void SetThrusterGroupLevel (THGROUP_HANDLE thg, double level) const;
2767+
2768+ /**
2769+ * \brief Sets the thrust level for all thrusters in a standard group.
2770+ * \param thgt thruster group type (see \ref thrusterparam)
2771+ * \param level new thrust level (range 0-1)
2772+ * \note This method can only be used with standard thruster group types. Do
2773+ * not use with THGROUP_USER.
2774+ * \sa SetThrusterGroupLevel (THGROUP_HANDLE,double)const
2775+ */
2776+ void SetThrusterGroupLevel (THGROUP_TYPE thgt, double level) const;
2777+
2778+ /**
2779+ * \brief Increments the thrust level for all thrusters in a group.
2780+ * \param thg thruster group identifier
2781+ * \param dlevel thrust level increment
2782+ * \note Resulting thrust levels are automatically truncated to the range [0..1]
2783+ * \note Use negative \a dlevel to decrement the thrust level.
2784+ * \sa VESSEL::IncThrusterGroupLevel(THGROUP_TYPE,double)const
2785+ */
2786+ void IncThrusterGroupLevel (THGROUP_HANDLE thg, double dlevel) const;
2787+
2788+ /**
2789+ * \brief Increments the thrust level for all thrusters in a standard group.
2790+ * \param thgt thruster group type
2791+ * \param dlevel thrust level increment
2792+ * \note This method can be used for standard thruster group types enumerated in
2793+ * \ref thrusterparam except THGROUP_USER.
2794+ * \note Resulting thrust levels are automatically truncated to the range [0..1]
2795+ * \note Use negative \a dlevel to decrement the thrust level.
2796+ * \sa VESSEL::IncThrusterGroupLevel(THGROUP_HANDLE,double)const
2797+ */
2798+ void IncThrusterGroupLevel (THGROUP_TYPE thgt, double dlevel) const;
2799+
2800+ /**
2801+ * \brief Increments the thrust level of a group for a single time step.
2802+ * \param thg thruster group identifier
2803+ * \param dlevel thrust level increment
2804+ * \note The total thrust level of a thruster group is composed of the sum of
2805+ * a \e permanent and an \e override portion, constrained to range [0..1].
2806+ * The permanent setting only changes when reset explicitly, while the
2807+ * override setting is reset to zero after each time step.
2808+ * \note This function increments the override portion of the thrust level
2809+ * for the thruster group for the current time step only.
2810+ * \note Negative values for the override thrust level are permitted to
2811+ * reduce the total thrust level below its permanent setting (down to
2812+ * a minimum of 0).
2813+ * \note Any override adjustments of individual thrusters in the group with
2814+ * \ref IncThrusterLevel_SingleStep are added to their total level.
2815+ * \sa IncThrusterGroupLevel_SingleStep(THGROUP_TYPE,double)const,
2816+ * IncThrusterLevel_SingleStep
2817+ */
2818+ void IncThrusterGroupLevel_SingleStep (THGROUP_HANDLE thg, double dlevel) const;
2819+
2820+ /**
2821+ * \brief Increments the thrust level of a standard group for a single time step.
2822+ * \param thgt thruster group type
2823+ * \param dlevel thrust level increment
2824+ * \note The total thrust level of a thruster group is composed of the sum of
2825+ * a \e permanent and an \e override portion, constrained to range [0..1].
2826+ * The permanent setting only changes when reset explicitly, while the
2827+ * override setting is reset to zero after each time step.
2828+ * \note This function increments the override portion of the thrust level
2829+ * for the thruster group for the current time step only.
2830+ * \note Negative values for the override thrust level are permitted to
2831+ * reduce the total thrust level below its permanent setting (down to
2832+ * a minimum of 0).
2833+ * \note Any override adjustments of individual thrusters in the group with
2834+ * \ref IncThrusterLevel_SingleStep are added to their total level.
2835+ * \sa IncThrusterGroupLevel_SingleStep(THGROUP_HANDLE,double)const,
2836+ * IncThrusterLevel_SingleStep
2837+ */
2838+ void IncThrusterGroupLevel_SingleStep (THGROUP_TYPE thgt, double dlevel) const;
2839+
2840+ /**
2841+ * \brief Returns the mean thrust level for a thruster group.
2842+ * \param thg thruster group identifier
2843+ * \return Mean group thrust level [0..1]
2844+ * \note In general, this method is only useful for groups where all thrusters
2845+ * have the same maximum thrust rating and the same thrust direction.
2846+ * \sa GetThrusterGroupLevel(THGROUP_TYPE)const
2847+ */
2848+ double GetThrusterGroupLevel (THGROUP_HANDLE thg) const;
2849+
2850+ /**
2851+ * \brief Returns the mean thrust level for a default thruster group.
2852+ * \param thgt thruster group type
2853+ * \return Mean group thrust level [0..1]
2854+ * \note In general, this method is only useful for groups where all thrusters
2855+ * have the same maximum thrust rating and the same thrust direction.
2856+ * \sa GetThrusterGroupLevel(THGROUP_HANDLE)const
2857+ */
2858+ double GetThrusterGroupLevel (THGROUP_TYPE thgt) const;
2859+
2860+ /**
2861+ * \brief Returns the thrust level of an attitude thruster group set via
2862+ * keyboard or mouse input.
2863+ * \param thgt thruster group identifier
2864+ * \param mode attitude control mode (see \ref manctrl_mode)
2865+ * \param device input device (see \ref manctrl_dev)
2866+ * \return Manual thrust level [0..1]
2867+ * \note If \a mode is not MANCTRL_ANYMODE, only thruster groups which
2868+ * are of the specified mode (linear or rotational) will return
2869+ * nonzero values.
2870+ */
2871+ double GetManualControlLevel (THGROUP_TYPE thgt, DWORD mode = MANCTRL_ATTMODE, DWORD device = MANCTRL_ANYDEVICE) const;
2872+ //@}
2873+
2874+ /// \name Reaction control system
2875+ //@{
2876+ /**
2877+ * \brief Returns the current RCS (reaction control system) thruster
2878+ * mode.
2879+ * \return Current RCS mode (see \ref rcsmode)
2880+ * \note The reaction control system consists of a set of small
2881+ * thrusters arranged around the vessel. They can be fired in
2882+ * pre-defined configurations to provide either a change in angular
2883+ * velocity (in RCS_ROT mode) or in linear velocity (in RCS_LIN mode).
2884+ * \note RCS_NONE indicates that the RCS is disabled or not available.
2885+ * \note Currently Orbiter doesn't allow simultaneous linear and
2886+ * rotational RCS control via keyboard or joystick. The user has to
2887+ * switch between the two. However, simultaneous operation is possible
2888+ * via the "RControl" plugin module.
2889+ * \note Not all vessel classes may define a complete RCS.
2890+ * \sa SetAttitudeMode, rcsmode
2891+ */
2892+ int GetAttitudeMode () const;
2893+
2894+ /**
2895+ * \brief Sets the vessel's RCS (reaction control system) thruster mode.
2896+ * \param mode New RCS mode (see \ref rcsmode)
2897+ * \return true on success, false for invalid argument
2898+ * \note The reaction control system consists of a set of small
2899+ * thrusters arranged around the vessel. They can be fired in
2900+ * pre-defined configurations to provide either a change in angular
2901+ * velocity (in RCS_ROT mode) or in linear velocity (in RCS_LIN mode).
2902+ * \note Set RCS_NONE to disable the RCS.
2903+ * \sa GetAttitudeMode, rcsmode
2904+ */
2905+ bool SetAttitudeMode (int mode) const;
2906+
2907+ /**
2908+ * \brief Switch between linear and rotational RCS mode
2909+ * \return New RCS mode index
2910+ * \note If the RCS is disabled, this method does nothing and returns 0.
2911+ * \note During playback, this method does nothing and returns the current RCS mode.
2912+ * \sa SetAttitudeMode, GetAttitudeMode
2913+ */
2914+ int ToggleAttitudeMode () const;
2915+
2916+ /**
2917+ * \brief Returns the current combined thrust levels for the reaction control
2918+ * system thruster groups in rotational mode.
2919+ * \param[out] th vector containing RCS thruster group levels for rotation
2920+ * around the 3 principal vessel axes (values: -1 to +1).
2921+ * \note The fractional thrust levels of the RCS engines for rotation around
2922+ * the vessel's x, y and z axis are returned in the x, y, and z components of
2923+ * \a th, respectively.
2924+ * \note The orientation of the vessel axes is implementation-dependent, but
2925+ * usually by convention, +x is "right", +y is "up", and +z is "forward".
2926+ * \note A value of +1 denotes maximum thrust in the positive direction around
2927+ * an axis, while -1 denotes maximum thrust in the negative direction.
2928+ * \note This method combines the results of calls to GetThrusterGroupLevel for
2929+ * all relevant RCS thruster groups in the following combinations:
2930+ * <table>
2931+ * <tr><td>th.x</td><td>THGROUP_ATT_PITCHUP - THGROUP_ATT_PITCHDOWN</td></tr>
2932+ * <tr><td>th.y</td><td>THGROUP_ATT_YAWLEFT - THGROUP_ATT_YAWRIGHT</td></tr>
2933+ * <tr><td>th.z</td><td>THGROUP_ATT_BANKRIGHT - THGROUP_ATT_BANKLEFT</td></tr>
2934+ * </table>
2935+ * \note To obtain the actual thrust force magnitudes [N], the absolute values
2936+ * must be multiplied with the max. attitude thrust.
2937+ * \sa GetAttitudeLinLevel, SetAttitudeRotLevel, GetThrusterGroupLevel,
2938+ * GetAttitudeMode
2939+ */
2940+ void GetAttitudeRotLevel (VECTOR3 &th) const;
2941+
2942+ /**
2943+ * \brief Set RCS thruster levels for rotation in all 3 vessel axes.
2944+ * \param th RCS thruster levels for rotation around x,y,z axes (range -1...+1)
2945+ * \note This method is functional even if the manual RCS input mode is set
2946+ * to linear.
2947+ * \sa SetAttitudeRotLevel(int,double)const, GetAttitudeRotLevel,
2948+ * SetAttitudeLinLevel
2949+ */
2950+ void SetAttitudeRotLevel (const VECTOR3 &th) const;
2951+
2952+ /**
2953+ * \brief Set RCS thruster level for rotation around a single axis.
2954+ * \param axis rotation axis (0=x, 1=y, 2=z)
2955+ * \param th RCS thruster level (range -1...+1)
2956+ * \note This method is functional even if the manual RCS input mode is set
2957+ * to linear.
2958+ * \sa SetAttitudeRotLevel(const VECTOR3&)const, GetAttitudeRotLevel,
2959+ * SetAttitudeLinLevel
2960+ */
2961+ void SetAttitudeRotLevel (int axis, double th) const;
2962+
2963+ /**
2964+ * \brief Returns the current combined thrust levels for the reaction control
2965+ * system thruster groups in linear (translational) mode.
2966+ * \param[out] th vector containing RCS thruster group levels for translation
2967+ * along the 3 principal vessel axes (values: -1 to +1)
2968+ * \note The fractional thrust levels of the RCS engines for translation along
2969+ * the vessel's x, y and z axis are returned in the x, y, and z components of
2970+ * \a th, respectively.
2971+ * \note The orientation of the vessel axes is implementation-dependent, but
2972+ * usually by convention, +x is "right", +y is "up", and +z is "forward".
2973+ * \note A value of +1 denotes maximum thrust in the positive direction along
2974+ * an axis, while -1 denotes maximum thrust in the negative direction.
2975+ * \note This method combines the results of calls to GetThrusterGroupLevel for
2976+ * all relevant RCS thruster groups in the following combinations:
2977+ * <table>
2978+ * <tr><td>th.x</td><td>THGROUP_ATT_RIGHT - THGROUP_ATT_LEFT</td></tr>
2979+ * <tr><td>th.y</td><td>THGROUP_ATT_UP - THGROUP_ATT_DOWN</td></tr>
2980+ * <tr><td>th.z</td><td>THGROUP_ATT_FORWARD - THGROUP_ATT_BACK</td></tr>
2981+ * </table>
2982+ * \note To obtain the actual thrust force magnitudes [N], the absolute values
2983+ * must be multiplied with the max. attitude thrust.
2984+ * \sa GetAttitudeRotLevel, SetAttitudeLinLevel, GetThrusterGroupLevel,
2985+ * GetAttitudeMode
2986+ */
2987+ void GetAttitudeLinLevel (VECTOR3 &th) const;
2988+
2989+ /**
2990+ * \brief Set RCS thruster levels for linear translation in all 3 vessel axes.
2991+ * \param th RCS thruster levels (range -1...+1)
2992+ * \note This method is functional even if the manual RCS input mode is set
2993+ * to rotational.
2994+ * \sa SetAttitudeLinLevel(int,double)const, SetAttitudeLinLevel,
2995+ * SetAttitudeRotLevel
2996+ */
2997+ void SetAttitudeLinLevel (const VECTOR3 &th) const;
2998+
2999+ /**
3000+ * \brief Set RCS thruster level for linear translation along a single axis.
3001+ * \param axis translation axis (0=x, 1=y, 2=z)
3002+ * \param th RCS thruster level (range -1...+1)
3003+ * \note This method is functional even if the manual RCS input mode is set
3004+ * to rotational.
3005+ * \sa SetAttitudeLinLevel(const VECTOR3&)const, SetAttitudeLinLevel,
3006+ * SetAttitudeRotLevel
3007+ */
3008+ void SetAttitudeLinLevel (int axis, double th) const;
3009+ //@}
3010+
3011+ /// \name Communication interface
3012+ //@{
3013+ /**
3014+ * \brief Send a simulated buffered key event to the vessel
3015+ * \param key key code
3016+ * \param down key down event flag
3017+ * \param kstate key state map for additional modifier keys
3018+ * \return Process flag (0=key not processed, 1=key processed)
3019+ * \note This method simulates a manual keyboard press and can be used
3020+ * to trigger actions associated with the key.
3021+ * \note If \a down = true, a key down event is simulated. Otherwise,
3022+ * a key up event is simulated.
3023+ * \note Additional modifier keys (e.g. Ctrl, Shift, Alt) can be set
3024+ * by passing a kstate array with the appropriate keys defined.
3025+ * \note This method triggers a call to VESSEL2::clbkConsumeBufferedKey.
3026+ * If not consumed by the callback function, the key event is offered
3027+ * to the default key handler.
3028+ * \sa VESSEL2::clbkConsumeBufferedKey
3029+ */
3030+ int SendBufferedKey (DWORD key, bool down=true, char *kstate=0);
3031+ //@}
3032+
3033+ /// \name Navigation radio interface
3034+ //@{
3035+ /**
3036+ * \brief Defines the number of navigation (NAV) radio receivers
3037+ * supported by the vessel.
3038+ * \param nnav number of NAV radio receivers
3039+ * \note A vessel requires NAV radio receivers to obtain instrument
3040+ * navigation aids such as ILS or docking approach information.
3041+ * \note If no NAV receivers are available, then certain MFD modes such
3042+ * as Landing or Docking will not be supported.
3043+ * \note Default is 2 NAV receivers.
3044+ * \sa GetNavCount
3045+ */
3046+ void InitNavRadios (DWORD nnav) const;
3047+
3048+ /**
3049+ * \brief Returns the number of NAV radio receivers.
3050+ * \return Number of NAV receivers (>= 0)
3051+ * \sa InitNavRadios
3052+ */
3053+ DWORD GetNavCount () const;
3054+
3055+ /**
3056+ * \brief Sets the channel of a NAV radio receiver.
3057+ * \param n receiver index (>= 0)
3058+ * \param ch channel (>= 0)
3059+ * \return \e false on error (receiver index or channel out of range),
3060+ * \e true otherwise
3061+ * \note NAV radios can be tuned from 108.00 to 139.95 MHz in steps of
3062+ * 0.05 MHz, corresponding to channels 0 to 639.
3063+ * \sa InitNavRadios, GetNavChannel
3064+ */
3065+ bool SetNavChannel (DWORD n, DWORD ch) const;
3066+
3067+ /**
3068+ * \brief Returns the current channel setting of a NAV radio receiver.
3069+ * \param n receiver index (>= 0)
3070+ * \return Receiver channel [0..639]. If index \a n is out of range, the
3071+ * return value is 0.
3072+ * \sa GetNavRecvFreq, SetNavChannel
3073+ */
3074+ DWORD GetNavChannel (DWORD n) const;
3075+
3076+ /**
3077+ * \brief Returns the current radio frequency of a NAV radio receiver.
3078+ * \param n receiver index (>= 0)
3079+ * \return Receiver frequency [MHz] (range 108.00 to 139.95). If index
3080+ * \a n is out of range, the return value is 0.0.
3081+ * \sa GetNavChannel
3082+ */
3083+ float GetNavRecvFreq (DWORD n) const;
3084+
3085+ /**
3086+ * \brief Enable/disable transmission of transponder signal.
3087+ * \param enable \e true to enable the transponder, \e false to disable.
3088+ * \note The transponder is a radio transmitter which can be used by other
3089+ * vessels to obtain navigation information, e.g. for docking
3090+ * rendezvous approaches.
3091+ * \note If the transponder is turned on (enable = true), its initial
3092+ * frequency is set to 108.00 MHz (channel 0). Use
3093+ * \ref SetTransponderChannel to tune to a different frequency.
3094+ * \sa SetTransponderChannel, SetIDSChannel
3095+ */
3096+ void EnableTransponder (bool enable) const;
3097+
3098+ /**
3099+ * \brief Switch the channel number of the vessel's transponder.
3100+ * \param ch transponder channel [0..639]
3101+ * \return \e false indicates failure (transponder not enabled or
3102+ * input parameter out of range)
3103+ * \note Transponders can be tuned from 108.00 to 139.95 MHz in steps
3104+ * of 0.05 MHz. The frequency corresponding to a channel number \a ch
3105+ * is given by f = (108.0 + 0.05 \a ch) MHz.
3106+ * \sa EnableTransponder, SetNavChannel
3107+ */
3108+ bool SetTransponderChannel (DWORD ch) const;
3109+
3110+ /**
3111+ * \brief Enable/disable one of the vessel's IDS (Instrument Docking
3112+ * System) transmitters.
3113+ * \param hDock docking port handle
3114+ * \param bEnable \e true to enable, \e false to disable the IDS for the dock.
3115+ * \note If the IDS transmitter is turned on (\a bEnable = \e true), its
3116+ * channel is initially set to 0 (transmitter frequency 108.00 MHz). Use
3117+ * \ref SetIDSChannel to tune to a different channel.
3118+ * \sa SetIDSChannel, EnableTransponder
3119+ */
3120+ void EnableIDS (DOCKHANDLE hDock, bool bEnable) const;
3121+
3122+ /**
3123+ * \brief Switch the channel number of one of the vessel's IDS (Instrument
3124+ * Docking System) transmitters.
3125+ * \param hDock docking port handle
3126+ * \param ch IDS channel [0..639]
3127+ * \return \e false indicates failure (IDS not enabled or input parameter
3128+ * out of range)
3129+ * \note IDS transmitters can be tuned from 108.00 to 139.95 MHz in steps
3130+ * of 0.05 MHz. The frequency corresponding to a channel number \a ch
3131+ * is given by f = (108.0 + 0.05 \a ch) MHz.
3132+ * \sa EnableIDS, SetTransponderChannel, SetNavChannel
3133+ */
3134+ bool SetIDSChannel (DOCKHANDLE hDock, DWORD ch) const;
3135+
3136+ /**
3137+ * \brief Return handle of vessel transponder if available.
3138+ * \return Navigation radio handle of the vessel's transponder, or NULL if
3139+ * not available.
3140+ * \note This function returns NULL unless the transponder has been enabled
3141+ * by a call to \ref EnableTransponder or by setting the EnableXPDR entry
3142+ * in the vessel's config file to TRUE.
3143+ * \note It is not safe to store the handle, because it can become invalid
3144+ * as a result of disabling/enabling the transponder. Instead, the handle
3145+ * should be queried when needed.
3146+ * \note The handle can be used to retrieve information about the transmitter,
3147+ * such as current frequency.
3148+ * \sa EnableTransponder, SetTransponderChannel
3149+ */
3150+ NAVHANDLE GetTransponder () const;
3151+
3152+ /**
3153+ * \brief Return handle of one of the vessel's instrument docking system
3154+ * (IDS) radio transmitters.
3155+ * \param hDock docking port handle
3156+ * \return Navigation radio handle of the vessel's IDS transmitter for docking
3157+ * port \a hDock.
3158+ * \note This function returns NULL if \a hDock does not define an IDS
3159+ * transmitter.
3160+ * \note Docking port handles are returned by the \ref CreateDock and
3161+ * \ref GetDockHandle methods.
3162+ * \note The IDS handle becomes invalid when the dock is deleted (e.g. as
3163+ * a result of \ref DelDock or \ref ClearDockDefinitions).
3164+ * \note The handle returned by this function can be used to retrieve
3165+ * information about the transmitter, such as sender frequency.
3166+ * \sa CreateDock, GetDockHandle, DelDock, ClearDockDefinitions, EnableIDS,
3167+ * GetTransponder
3168+ */
3169+ NAVHANDLE GetIDS (DOCKHANDLE hDock) const;
3170+
3171+ /**
3172+ * \brief Return handle of transmitter source currently received by one of
3173+ * the vessel's NAV receivers.
3174+ * \param n NAV receiver index (>= 0)
3175+ * \return handle of transmitter currently received, or NULL if the receiver
3176+ * is not tuned to any station, or if \a n is out of range.
3177+ * \note The handle returned by this function may change in consecutive calls,
3178+ * depending on the radio frequency of the corresponding receiver, the vessel
3179+ * position and the position of radio transmitters in the range of the receiver.
3180+ */
3181+ NAVHANDLE GetNavSource (DWORD n) const;
3182+ //@}
3183+
3184+ /// \name Cockpit camera methods
3185+ //@{
3186+ /**
3187+ * \brief Set the camera position for internal (cockpit) view.
3188+ * \param co camera offset in vessel coordinates [<b>m</b>]
3189+ * \note The camera offset can be used to define the pilot's eye position in the
3190+ * spacecraft.
3191+ * \note The default offset is (0,0,0).
3192+ * \note This function is called typically either globally in
3193+ * \ref VESSEL2::clbkSetClassCaps, if the camera position doesn't change
3194+ * between views, or individually in \ref VESSEL2::clbkLoadGenericCockpit,
3195+ * \ref VESSEL2::clbkLoadPanel and \ref VESSEL2::clbkLoadVC for each defined
3196+ * view.
3197+ * \sa GetCameraOffset
3198+ */
3199+ void SetCameraOffset (const VECTOR3 &co) const;
3200+
3201+ /**
3202+ * \brief Returns the current camera position for internal (cockpit) view.
3203+ * \param co camera offset in vessel coordinates [<b>m</b>]
3204+ * \sa SetCameraOffset
3205+ */
3206+ void GetCameraOffset (VECTOR3 &co) const;
3207+
3208+ /**
3209+ * \brief Set the default camera direction for internal (cockpit) view.
3210+ * \param cd new default direction in vessel coordinates
3211+ * \note By default, the default direction is (0,0,1), i.e. forward.
3212+ * \note The supplied direction vector must be normalised to length 1.
3213+ * \note Calling this function automatically sets the current actual view
3214+ * direction to the default direction.
3215+ * \note This function can either be called during VESSEL2::clbkSetClassCaps,
3216+ * to define the default camera direction globally for the vessel, or during
3217+ * VESSEL2::clbkLoadGenericCockpit, VESSEL2::clbkLoadPanel and VESSEL2::clbkLoadVC,
3218+ * to define different default directions for different instrument panels or
3219+ * virtual cockpit positions.
3220+ * \note In Orbiter, the user can return to the default direction by pressing the
3221+ * \e Home key on the cursor key pad.
3222+ * \sa SetCameraDefaultDirection(const VECTOR3&,double)const,
3223+ * GetCameraDefaultDirection, VESSEL2::clbkSetClassCaps,
3224+ * VESSEL2::clbkLoadGenericCockpit, VESSEL2::clbkLoadPanel, VESSEL2::clbkLoadVC
3225+ */
3226+ void SetCameraDefaultDirection (const VECTOR3 &cd) const;
3227+
3228+ /**
3229+ * \brief Set the default camera direction and tilt angle for internal (cockpit) view.
3230+ * \param cd new default direction in vessel coordinates
3231+ * \param tilt camera tilt angle around the default direction [rad]
3232+ * \note This function allows to set the camera tilt angle in addition to the default
3233+ * direction.
3234+ * \note By default, the default direction is (0,0,1), i.e. forward, and the tilt
3235+ * angle is 0 (upright).
3236+ * \note The supplied direction vector must be normalised to length 1.
3237+ * \note The tilt angle should be in the range [-Pi,+Pi]
3238+ * \note Calling this function automatically sets the current actual view direction to
3239+ * the default direction.
3240+ * \sa SetCameraDefaultDirection(const VECTOR3&)const, GetCameraDefaultDirection
3241+ */
3242+ void SetCameraDefaultDirection (const VECTOR3 &cd, double tilt) const;
3243+
3244+ /**
3245+ * \brief Returns the default camera direction for internal (cockpit) view.
3246+ * \param cd default camera direction in vessel coordinates
3247+ * \note The default camera direction may change as a result of invoking
3248+ * SetCameraDefaultDirection, typically when the user selects a different instrument
3249+ * panel or virtual cockpit position.
3250+ * \note The returned direction vector is normalised to length 1.
3251+ * \sa SetCameraDefaultDirection(const VECTOR3&)const,
3252+ * SetCameraDefaultDirection(const VECTOR3&,double)const
3253+ */
3254+ void GetCameraDefaultDirection (VECTOR3 &cd) const;
3255+
3256+ /**
3257+ * \brief Set the angle over which the cockpit camera auto-centers to default direction.
3258+ * \param cangle auto-center catchment angle [rad]
3259+ * \note The cockpit camera auto-centers to its default ("forward") direction when
3260+ * it is close enough to this direction. This function can be used to specify the
3261+ * angle over which auto-centering occurs.
3262+ * \note Setting cangle=0 disables the auto-centering function.
3263+ * \note The default catchment angle is 5 degrees (5.0*RAD).
3264+ * \note To reset the catchment angle globally for all cockpit views of the vessel,
3265+ * SetCameraCatchAngle would typically used in VESSEL2::clbkSetClassCaps(). To reset
3266+ * the catchment angle for individual cockpit positions, the function would be used
3267+ * for the appropriate cockpit modes in VESSEL2::clbkLoadPanel() and VESSEL2::clbkLoadVC().
3268+ */
3269+ void SetCameraCatchAngle (double cangle) const;
3270+
3271+ /**
3272+ * \brief Sets the range over which the cockpit camera can be rotated from its default
3273+ * direction.
3274+ * \param left rotation range to the left [rad]
3275+ * \param right rotation range to the right [rad]
3276+ * \param up rotation range up [rad]
3277+ * \param down rotation range down [rad]
3278+ * \note The meaning of the "left", "right", "up" and "down" directions is given by the
3279+ * orientation of the local vessel frame. For a default view direction of (0,0,1),
3280+ * "left" is a rotation towards the -x axis, "right" is a rotation towards the +x axis,
3281+ * "up" is a rotation towards the +y axis, and "down" is a rotation towards the -y axis.
3282+ * \note All ranges must be >= 0. The left and right ranges should be < Pi. The up and
3283+ * down ranges should be < Pi/2.
3284+ * \note The default values are 0.8Pi for left and right ranges, and 0.4Pi for up and down
3285+ * ranges.
3286+ * \sa SetCameraShiftRange, SetCameraMovement
3287+ */
3288+ void SetCameraRotationRange (double left, double right, double up, double down) const;
3289+
3290+ /**
3291+ * \brief Set the linear movement range for the cockpit camera.
3292+ *
3293+ * Defining a linear movement allows the user to move the head forward or sideways, e.g. to
3294+ * get a better look out of a window, or a closer view of a virtual cockpit instrument
3295+ * panel.
3296+ * \param fpos offset vector when leaning forward [<b>m</b>]
3297+ * \param lpos offset vector when leaning left [<b>m</b>]
3298+ * \param rpos offset vector when leaning right [<b>m</b>]
3299+ * \note If a linear movement range is defined with this function, the user can 'lean'
3300+ * forward or sideways using the 'cockpit slew' keys. Supported keys are:
3301+ * <table col="3">
3302+ * <tr><td><b>Name</b></td><td><b>default</b></td><td><b>action</b></td></tr>
3303+ * <tr><td>CockpitCamDontLean</td><td>Ctrl+Alt+Down</td><td>return to default position</td></tr>
3304+ * <tr><td>CockpitCamLeanForward</td><td>Ctrl+Alt+Up</td><td>lean forward</td></tr>
3305+ * <tr><td>CockpitCamLeanLeft</td><td>Ctrl+Alt+Left</td><td>lean left</td></tr>
3306+ * <tr><td>CockpitCamLeanRight</td><td>Ctrl+Alt+Right</td><td>lean right</td></tr>
3307+ * </table>
3308+ * \note The movement vectors are taken relative to the default cockpit position defined
3309+ * via SetCameraOffset.
3310+ * \note This function should be called when initialising a cockpit mode (e.g. in
3311+ * clbkLoadPanel or clbkLoadVC). By default, Orbiter resets the linear movement range
3312+ * to zero whenever the cockpit mode changes.
3313+ * \note In addition to the linear movement, the camera also turns left when leaning left,
3314+ * turns right when leaning right, and returns to default direction when leaning forward.
3315+ * For more control over camera rotation at the different positions, use SetCameraMovement
3316+ * instead.
3317+ * \sa SetCameraMovement, SetCameraRotationRange
3318+ */
3319+ void SetCameraShiftRange (const VECTOR3 &fpos, const VECTOR3 &lpos, const VECTOR3 &rpos) const;
3320+
3321+ /**
3322+ * \brief Set both linear movement range and orientation of the cockpit camera when "leaning"
3323+ * forward, left and right.
3324+ * \param fpos offset vector when leaning forward [<b>m</b>]
3325+ * \param fphi camera rotation azimuth angle when leaning forward [rad]
3326+ * \param ftht camera rotation polar angle when leaning forward [rad]
3327+ * \param lpos offset vector when leaning left [<b>m</b>]
3328+ * \param lphi camera rotation azimuth angle when leaning left [rad]
3329+ * \param ltht camera rotation polar angle when leaning left [rad]
3330+ * \param rpos offset vector when leaning right [<b>m</b>]
3331+ * \param rphi camera rotation azimuth angle when leaning right [rad]
3332+ * \param rtht camera rotation polar angle when leaning right [rad]
3333+ * \note This function is an extended version of \ref SetCameraShiftRange.
3334+ * \note It is more versatile, because in addition to the linear camera movement vectors, it
3335+ * also allows to define the camera orientation (via azimuth and polar angle relative to
3336+ * default view direction). This allows to point the camera to a particular cockpit window,
3337+ * instrument panel, etc.
3338+ * \sa SetCameraShiftRange, SetCameraRotationRange
3339+ */
3340+ void SetCameraMovement (const VECTOR3 &fpos, double fphi, double ftht, const VECTOR3 &lpos, double lphi, double ltht, const VECTOR3 &rpos, double rphi, double rtht) const;
3341+ //@}
3342+
3343+ /// \name Mesh methods
3344+ //@{
3345+ /**
3346+ * \brief Remove all mesh definitions for the vessel.
3347+ * \param retain_anim flag for retaining mesh animation objects
3348+ * \note If \a retain_anim is \e false, all animations defined for the vessel are deleted
3349+ * together with the meshes. If \e true, the animations stay behind. This is only useful
3350+ * if the same meshes are subsequently added again in the same order, so that the animations
3351+ * point to the appropriate meshes and mesh groups and can be re-used. If different meshes
3352+ * are loaded later, the behaviour of the animations becomes undefined.
3353+ * \note In the future, obsolete method \ref ClearMeshes()const will be removed, and
3354+ * \a retain_anim will have a default value of false.
3355+ */
3356+ void ClearMeshes (bool retain_anim) const;
3357+
3358+ /**
3359+ * \brief Load a mesh definition for the vessel from a file.
3360+ * \param meshname mesh file name
3361+ * \param ofs optional pointer to a displacement vector which describes the offset of the
3362+ * mesh origin against the vessel origin [<b>m</b>].
3363+ * \return mesh index
3364+ * \note \a meshname defines a path to an existing mesh file. The mesh must be in
3365+ * Orbiter's MSH format (see 3DModel.pdf).
3366+ * \note The file name (including optional directory path) is relative to Orbiter's mesh
3367+ * directory (usually ".\\Meshes"). The file extension must not be specified (.msh is assumed.)
3368+ * \note The mesh is either appended to the end of the vessel's mesh list, or inserted at the
3369+ * location of a previously deleted mesh (see VESSEL::DelMesh)
3370+ * \note The returned value is the mesh list index at which the mesh reference was stored. It
3371+ * can be used to identify the mesh later (e.g. for animations).
3372+ * \note This function only creates a \e reference to a mesh, but does not directly load the
3373+ * mesh from frile. The mesh is physically loaded only when it is required (whenever the
3374+ * vessel moves within visual range of the observer camera).
3375+ * \sa AddMesh(MESHHANDLE,const VECTOR3*)const, DelMesh
3376+ */
3377+ UINT AddMesh (const char *meshname, const VECTOR3 *ofs=0) const;
3378+
3379+ /**
3380+ * \brief Add a pre-loaded mesh definition to the vessel.
3381+ * \param hMesh mesh handle
3382+ * \param ofs optional pointer to a displacement vector which describes the offset of the
3383+ * mesh origin against the vessel origin [<b>m</b>].
3384+ * \return mesh index
3385+ * \note \a hMesh is a handle to a mesh previously loaded with \ref oapiLoadMeshGlobal.
3386+ * \note The global handle hMesh repersents a "mesh template". Whenever the vessel needs
3387+ * to create its visual representation (when moving within visual range of the observer
3388+ * camera), it creates its individual mesh as a copy of the template.
3389+ * \sa AddMesh(const char*,const VECTOR3*)const, oapiLoadMeshGlobal, DelMesh
3390+ */
3391+ UINT AddMesh (MESHHANDLE hMesh, const VECTOR3 *ofs=0) const;
3392+
3393+ /**
3394+ * \brief Insert or replace a mesh at a specific index location of the vessel's mesh list.
3395+ * \param meshname mesh file name
3396+ * \param idx mesh list index (>= 0)
3397+ * \param ofs optional pointer to a displacement vector which describes the offset of the
3398+ * mesh origin against the vessel origin [<b>m</b>].
3399+ * \return mesh index
3400+ * \note \a meshname defines a path to an existing mesh file. The mesh must be in
3401+ * Orbiter's MSH format.
3402+ * \note The file name (including optional directory path) is relative to Orbiter's mesh
3403+ * directory (usually ".\\Meshes"). The file extension should not be specified (.msh is
3404+ * assumed.)
3405+ * \note \a idx is a zero-based index which specifies at which point the mesh reference
3406+ * is added into the vessel's mesh list. If a mesh already exists at this position, it
3407+ * is overwritten. If idx > number of meshes, then the required number of (empty) entries
3408+ * is generated.
3409+ * \note The return value is always equal to \a idx.
3410+ * \sa InsertMesh(MESHHANDLE,UINT,const VECTOR3*)const,
3411+ * AddMesh(const char*,const VECTOR3*)const,
3412+ * AddMesh(MESHHANDLE,const VECTOR3*)const
3413+ */
3414+ UINT InsertMesh (const char *meshname, UINT idx, const VECTOR3 *ofs=0) const;
3415+
3416+ /**
3417+ * \brief Insert or replace a mesh at a specific index location of the vessel's mesh list.
3418+ * \param hMesh mesh handle
3419+ * \param idx mesh list index (>= 0)
3420+ * \param ofs optional pointer to a displacement vector which describes the offset of the
3421+ * mesh origin against the vessel origin [<b>m</b>].
3422+ * \return mesh index
3423+ * \note \a hMesh is a handle to a mesh previously loaded with \ref oapiLoadMeshGlobal.
3424+ * \note The global handle \a hMesh represents a "mesh template". Whenever the vessel
3425+ * needs to create its visual representation (when moving within visual range of the
3426+ * observer camera), it creates its individual mesh as a copy of the template.
3427+ * \note \a idx is a zero-based index which specifies at which point the mesh reference
3428+ * is added into the vessel's mesh list. If a mesh already exists at this position,
3429+ * it is overwritten. If idx > number of meshes, then the required number of (empty)
3430+ * entries is generated.
3431+ * \note The return value is always equal to \a idx.
3432+ * \sa InsertMesh(const char*,UINT,const VECTOR3*)const,
3433+ * AddMesh(const char*,const VECTOR3*)const,
3434+ * AddMesh(MESHHANDLE,const VECTOR3*)const
3435+ */
3436+ UINT InsertMesh (MESHHANDLE hMesh, UINT idx, const VECTOR3 *ofs=0) const;
3437+
3438+ /**
3439+ * \brief Remove a mesh from the vessel's mesh list.
3440+ * \param idx mesh list index (>= 0)
3441+ * \param retain_anim flag for keeping mesh animations
3442+ * \return \e true on success, \e false to indicate failure (index
3443+ * out of range, or mesh already deleted.)
3444+ * \note After a mesh has been deleted, the mesh index is no longer valid,
3445+ * and should not be used any more in function calls (e.g. for animations).
3446+ * \note If meshes are added subsequently, they are placed in the vacant list
3447+ * slots, and therefore can be assigned the indices of previously deleted
3448+ * meshes.
3449+ * \note If you want to replace a mesh, it is easier to use the \ref InsertMesh
3450+ * function instead of a combination of DelMesh and \ref AddMesh.
3451+ * \note By default, all animation components associated with the mesh are
3452+ * deleted. This can be prevented by setting retain_anim to true. In general
3453+ * this is only useful if the same mesh is subsequently loaded again into the
3454+ * same mesh index slot. In all other cases, retaining the animations of
3455+ * deleted meshes can lead to undefined behaviour.
3456+ * \sa InsertMesh, AddMesh, ClearMeshes
3457+ */
3458+ bool DelMesh (UINT idx, bool retain_anim=false) const;
3459+
3460+ /**
3461+ * \brief Shift the position of a mesh relative to the vessel's local coordinate
3462+ * system.
3463+ * \param idx mesh list index (>= 0)
3464+ * \param ofs translation vector [<b>m</b>]
3465+ * \return \e true on success, \e false indicates error (index out of range).
3466+ * \note This function does not define an animation (i.e. gradual transition),
3467+ * but resets the mesh position instantly.
3468+ * \sa ShiftMeshes, GetMeshOffset
3469+ */
3470+ bool ShiftMesh (UINT idx, const VECTOR3 &ofs) const;
3471+
3472+ /**
3473+ * \brief Shift the position of all meshes relative to the vessel's local
3474+ * coordinate system.
3475+ * \param ofs translation vector [<b>m</b>]
3476+ * \note This function is useful when resetting a vessel's centre of gravity,
3477+ * in combination with \ref ShiftCentreOfMass.
3478+ * \note A more convenient way to shift the centre of gravity is a call to
3479+ * \ref ShiftCG.
3480+ * \sa ShiftMesh, GetMeshOffset, ShiftCentreOfMass, ShiftCG
3481+ */
3482+ void ShiftMeshes (const VECTOR3 &ofs) const;
3483+
3484+ /**
3485+ * \brief Returns the mesh offset in the vessel frame
3486+ * \param idx mesh index (0 <= idx < GetMeshCount())
3487+ * \param[out] ofs mesh offset [<b>m</b>]
3488+ * \return true if idx refers to a valid mesh index
3489+ * \sa AddMesh, InsertMesh, ShiftMesh, ShiftMeshes
3490+ */
3491+ bool GetMeshOffset (UINT idx, VECTOR3 &ofs) const;
3492+
3493+ /**
3494+ * \brief Number of meshes
3495+ *
3496+ * Returns the number of meshes currently defined for the vessel
3497+ * \return mesh count (>= 0)
3498+ */
3499+ UINT GetMeshCount () const;
3500+
3501+ /**
3502+ * \brief Obtain mesh handle for a vessel mesh
3503+ *
3504+ * Returns a handle for a vessel mesh \e instance. Mesh instances only exist
3505+ * while the vessel is within visual range of the camera. This function should
3506+ * therefore only be called between VESSEL2::clbkVisualCreated and
3507+ * VESSEL2::clbkVisualDestroyed, with the VISHANDLE provided by these functions.
3508+ * \param vis identifies the visual for which the mesh was created
3509+ * \param idx mesh index (0 <= idx < GetMeshCount())
3510+ * \return mesh handle
3511+ * \ng The non-graphics version of Orbiter returns always NULL, even if
3512+ * a graphics client is attached. To obtain a client-specific mesh handle,
3513+ * use \ref GetDevMesh .
3514+ * \sa GetMeshTemplate, GetMeshCount, GetDevMesh
3515+ */
3516+ MESHHANDLE GetMesh (VISHANDLE vis, UINT idx) const;
3517+
3518+ /**
3519+ * \brief Returns a handle for a device-specific mesh instance
3520+ * \param vis identifies the visual for which the mesh was created.
3521+ * \param idx mesh index (0 <= idx < GetMeshCount())
3522+ * \return device mesh handle
3523+ * \note For Orbiter_ng, this method returns a handle for a mesh instance managed
3524+ * by the external graphics client. Graphics clients may implement their own
3525+ * mesh formats, so the object pointed to by the handle is client-specific.
3526+ * \note For inline graphics version, the returned handle points to the same object
3527+ * as the handle returned by \ref GetMesh .
3528+ * \sa GetMesh
3529+ */
3530+ DEVMESHHANDLE GetDevMesh (VISHANDLE vis, UINT idx) const;
3531+
3532+ /**
3533+ * \brief Obtain a handle for a vessel mesh template
3534+ *
3535+ * Returns the mesh handle for a pre-loaded mesh template, if available.
3536+ * \param idx mesh index (0 <= idx < GetMeshCount())
3537+ * \return mesh template handle
3538+ * \note Mesh templates can only be returned for meshes pre-loaded with
3539+ * oapiLoadMeshGlobal(). For all other (load-on-demand) meshes this
3540+ * method returns NULL.
3541+ * \note Mesh templates are resources shared between all vessels and should
3542+ * never be modified by individual vessels. Orbiter creates individual
3543+ * copies of the templates whenever a vessel is rendered.
3544+ */
3545+ const MESHHANDLE GetMeshTemplate (UINT idx) const;
3546+
3547+ /**
3548+ * \brief Obtain mesh file name for an on-demand mesh.
3549+ *
3550+ * Returns the mesh file name (with path relative to Orbiter's main mesh
3551+ * directory) for a vessel mesh that is loaded on demand (i.e. not
3552+ * pre-loaded).
3553+ * \param idx mesh index (0 <= idx < GetMeshCount())
3554+ * \return mesh file name, or NULL if mesh is pre-loaded
3555+ * \note The file names for pre-loaded meshes are not retained by Orbiter.
3556+ * \note Graphics clients can obtain pre-loaded mesh file names by
3557+ * intercepting the oapi::GraphicsClient::clbkStoreMeshPersistent() method.
3558+ */
3559+ const char *GetMeshName (UINT idx) const;
3560+
3561+ /**
3562+ * \brief Make a copy of one of the vessel's mesh templates.
3563+ * \param idx mesh index
3564+ * \return handle of copied mesh
3565+ * \note Meshes loaded with \ref oapiLoadMeshGlobal are templates shared
3566+ * between all vessel instances and should never be modified by individual
3567+ * vessels. If a vessel needs to modify its meshes, it should operate on
3568+ * a copy of the template.
3569+ */
3570+ MESHHANDLE CopyMeshFromTemplate (UINT idx) const;
3571+
3572+ /**
3573+ * \brief Returns the visibility flags for a vessel mesh.
3574+ * \param idx mesh index (>= 0)
3575+ * \return Visibility mode flags (see \ref SetMeshVisibilityMode for possible
3576+ * values).
3577+ * \sa SetMeshVisibilityMode, meshvis
3578+ */
3579+ WORD GetMeshVisibilityMode (UINT idx) const;
3580+
3581+ /**
3582+ * \brief Set the visibility flags for a vessel mesh.
3583+ * \param idx mesh index (>= 0)
3584+ * \param mode visibility mode flags (see \ref meshvis)
3585+ * \note This method can be used to specify if a mesh is visible
3586+ * in particular camera modes. Some meshes may only be visible
3587+ * in external views, while others should only be visible in
3588+ * cockpit views.
3589+ * \note Turning off the unnecessary rendering of meshes can
3590+ * improve the performance of the simulator.
3591+ * \note \a mode can be a combination of the \ref meshvis.
3592+ * \note The default mode after adding a mesh is MESHVIS_EXTERNAL.
3593+ * \note MESHVIS_EXTPASS can't be used on its own, but as a modifier to any of the
3594+ * other visibility modes. If specified, it forces the mesh to be rendered in
3595+ * Orbiter's external render pass, even if it is labelled as internal (e.g.
3596+ * MESHVIS_COCKPIT or MESHVIS_VC). The significance of the external render pass
3597+ * is that it allows the mesh to be obscured by other objects in front of it.
3598+ * However, objects in the external render pass are clipped at a camera distance
3599+ * of 2.5m. Meshes that are rendered during the internal pass always cover all
3600+ * other objects, and have a smaller clipping distance.
3601+ * \note Use the MESHVIS_EXTPASS modifier for parts of the vessel that are visible
3602+ * from the cockpit, but are not close to the camera and may be obscured by other
3603+ * objects. An example is the Shuttle payload bay, which can be covered by payload
3604+ * objects.
3605+ * \sa GetMeshVisibilityMode, meshvis
3606+ */
3607+ void SetMeshVisibilityMode (UINT idx, WORD mode) const;
3608+
3609+ /**
3610+ * \brief Affine transformation of a mesh group.
3611+ * \param vis vessel visual handle
3612+ * \param mt transformation parameter structure
3613+ * \return \e true on success, \e false on failure (group index out of range)
3614+ * \ng This function is not yet supported in orbiter_ng and
3615+ * always returns \e false.
3616+ */
3617+ bool MeshgroupTransform (VISHANDLE vis, const MESHGROUP_TRANSFORM &mt) const;
3618+
3619+ /**
3620+ * \brief Notifies Orbiter of a change in a mesh group.
3621+ * \param hMesh mesh handle
3622+ * \param grp group index (>= 0)
3623+ * \param modflag type of modification (currently ignored)
3624+ * \return error code (0=ok)
3625+ * \note This method should be called if the components of a mesh group
3626+ * (vertices or indices) have been modified, to allow Orbiter to propagate
3627+ * the changes to the render object.
3628+ * \note For the built-in renderer, this registration is not strictly necessary,
3629+ * because it uses the mesh directly as the render object, so any changes to
3630+ * the mesh groups are applied directly.
3631+ * \note External graphics clients however may map the mesh data into device-specific
3632+ * data structures. In that case, MeshModified tells the graphics subsystem to
3633+ * synchronise its mesh data.
3634+ * \note MeshModified does not need to be called after applying an affine transformation
3635+ * of the mesh group as a whole (\ref MeshgroupTransform), because this is performed
3636+ * by assigning a transformation matrix, rather than by modifying the vertex positions
3637+ * themselves.
3638+ * \sa oapiMeshGroup, oapiMeshGroupEx
3639+ */
3640+ int MeshModified (MESHHANDLE hMesh, UINT grp, DWORD modflag);
3641+ //@}
3642+
3643+ /// \name Animations
3644+ //@{
3645+ /**
3646+ * \brief Logs a request for calls to \ref VESSEL2::clbkAnimate
3647+ * \note This function allows to implement animation sequences in combination
3648+ * with the %VESSEL2::clbkAnimate callback function. After a call to
3649+ * RegisterAnimation, %VESSEL2::clbkAnimate is called at each time step
3650+ * whenever the vessel's visual object exists.
3651+ * \note Use \ref UnregisterAnimation to stop further calls to
3652+ * %VESSEL2::clbkAnimate.
3653+ * \note Each call to RegisterAnimation increments a reference counter, while
3654+ * each call to UnregisterAnimation decrements the counter. Orbiter
3655+ * continues calling %VESSEL2::clbkAnimate as long as the counter is greater
3656+ * than 0.
3657+ * \note If %VESSEL2::clbkAnimate is not overloaded by the module,
3658+ * RegisterAnimation has no effect.
3659+ * \note The RegisterAnimation mechanism leaves the actual implementation of
3660+ * the animation (transformation of mesh groups, etc.) entirely to the
3661+ * module. The VESSEL::CreateAnimation / VESSEL::AddAnimationComponent
3662+ * mechanism is an alternative way to define animations where the
3663+ * transformations are managed by the Orbiter core.
3664+ * \sa VESSEL2::clbkAnimate, UnregisterAnimation, CreateAnimation,
3665+ * AddAnimationComponent
3666+ */
3667+ void RegisterAnimation () const;
3668+
3669+ /**
3670+ * \brief Unlogs an animation request.
3671+ * \note This stops a request for animation callback calls from a previous
3672+ * \ref RegisterAnimation.
3673+ * \note The call to UnregisterAnimation should not be placed in the body of
3674+ * \ref VESSEL2::clbkAnimate, since it may be lost if the vessel's visual
3675+ * doesn't exist.
3676+ * \sa RegisterAnimation, VESSEL2::clbkAnimate
3677+ */
3678+ void UnregisterAnimation () const;
3679+
3680+ /**
3681+ * \brief Create a mesh animation object.
3682+ *
3683+ * The sequence can contain multiple components (rotations, translations,
3684+ * scalings of mesh groups) with a fixed temporal correlation. The
3685+ * animation is driven by manipulating its "state", which is a number
3686+ * between 0 and 1 used to linearly interpolate the animation within its
3687+ * range. See API User's Guide for details.
3688+ * \param initial_state the animation state corresponding to the
3689+ * unmodified mesh
3690+ * \return Animation identifier
3691+ * \note After creating an animation, components can be added with
3692+ * \ref AddAnimationComponent.
3693+ * \note Use SetAnimation() to manipulate the animation state.
3694+ * \note 0 <= \a initial_state <= 1 defines at which state the animation is stored in
3695+ * the mesh file. Example: Landing gear animation between retracted
3696+ * state (0) and deployed state (1). If the landing gear is retracted
3697+ * in the mesh file, set initial_state to 0. If it is deployed in the
3698+ * mesh file, set initial_state to 1.
3699+ * \sa DelAnimation, AddAnimationComponent
3700+ */
3701+ UINT CreateAnimation (double initial_state) const;
3702+
3703+ /**
3704+ * \brief Delete an existing mesh animation object.
3705+ * \param anim animation identifier, as returned by CreateAnimation
3706+ * \return true if animation was deleted successfully
3707+ * \note The animation is deleted by removing all the components
3708+ * associated with it. Subsequently, any calls to SetAnimation using
3709+ * this animation index will not have any effect.
3710+ * \note Before the animation is deleted, the mesh groups associated
3711+ * with the animation are reset to their default (initial) positions.
3712+ * To avoid jumps in the visual appearance of the vessel, animations
3713+ * should therefore only be deleted when the animation state has
3714+ * returned to the default state.
3715+ * \sa CreateAnimation
3716+ */
3717+ bool DelAnimation (UINT anim) const;
3718+
3719+ /**
3720+ * \brief Add a component (rotation, translation or scaling) to an
3721+ * animation.
3722+ *
3723+ * Optionally, animations can be stacked hierachically, where
3724+ * transforming a parent recursively also transforms all its children
3725+ * (e.g. a wheel spinning while the landing gear is being retracted).
3726+ * \param anim animation identifier, as returned by CreateAnimation()
3727+ * \param state0 animation cutoff state 0 for the component
3728+ * \param state1 animation cutoff state 1 for the component
3729+ * \param trans transformation data (see notes)
3730+ * \param parent parent transformation
3731+ * \return Animation component handle
3732+ * \note state0 and state1 (0..1) allow to define the temporal endpoints
3733+ * of the component's animation within the sequence. For example,
3734+ * state0=0 and state1=1 perform the animation over the whole duration
3735+ * of the animation sequence, while state0=0 and state1=0.5 perform
3736+ * the animation over the first half of the total animation. This
3737+ * allows to build complex animations where different components are
3738+ * animated in a defined temporal sequence.
3739+ * \note MGROUP_TRANSFORM is the base class for mesh group transforms.
3740+ * Derived classes provide support for rotations, translations and
3741+ * scaling.
3742+ * \note To animate a complete mesh, rather than individual mesh groups,
3743+ * set the "grp" pointer to NULL in the constructor of the
3744+ * corresponding MGROUP_TRANSFORM operator. The "ngrp" value is then
3745+ * ignored.
3746+ * \note To define a transformation as a child of another
3747+ * transformation, set parent to the handle returned by the
3748+ * \ref AddAnimationComponent call for the parent.
3749+ * \note Instead of adding mesh groups to an animation, it is also
3750+ * possible to add a local VECTOR3 array. To do this, set "mesh" to
3751+ * \ref LOCALVERTEXLIST, and set "grp" to \ref MAKEGROUPARRAY(vtxptr), where
3752+ * vtxptr is the VECTOR3 array. "ngrp" is set to the number of
3753+ * vertices in the array. Example:
3754+ * \code
3755+ * VECTOR3 vtx[2] = {_V(0,0,0), _V(1,0,-1)};
3756+ * MGROUP_TRANSFORM *mt = new MGROUP_TRANSFORM (LOCALVERTEXLIST,
3757+ * MAKEGROUPARRAY(vtx), 2);
3758+ * AddAnimationComponent (anim, 0, 1, mt);
3759+ * \endcode
3760+ * Transforming local vertices in this way does not have an effect on
3761+ * the visual appearance of the animation, but it can be used by the
3762+ * module to keep track of a transformed point during animation. The
3763+ * Atlantis module uses this method to track a grappled satellite
3764+ * during animation of the RMS arm.
3765+ * \note The ANIMATIONCOMPONENT_HANDLE is a pointer to a ANIMATIONCOMP
3766+ * structure.
3767+ * \bug When defining a scaling transformation as a child of a parent
3768+ * rotation, only homogeneous scaling is supported, i.e. scale.x =
3769+ * scale.y = scale.z is required.
3770+ * \sa CreateAnimation, DelAnimationComponent, animationflags
3771+ */
3772+ ANIMATIONCOMPONENT_HANDLE AddAnimationComponent (UINT anim, double state0, double state1,
3773+ MGROUP_TRANSFORM *trans, ANIMATIONCOMPONENT_HANDLE parent = NULL) const;
3774+
3775+ /**
3776+ * \brief Remove a component from an animation.
3777+ * \param anim animation identifier
3778+ * \param hAC animation component handle
3779+ * \return \e false indicates failure (\a anim out of range, or \a hAC invalid)
3780+ * \note If the component has children belonging to the same animation,
3781+ * these will be deleted as well.
3782+ * \note In the current implementation, the component must not have children
3783+ * belonging to other animations. Trying to delete such a component will
3784+ * result in undefined behaviour.
3785+ * \sa AddAnimationComponent
3786+ */
3787+ bool DelAnimationComponent (UINT anim, ANIMATIONCOMPONENT_HANDLE hAC);
3788+
3789+ /**
3790+ * \brief Set the state of an animation.
3791+ * \param anim animation identifier
3792+ * \param state animation state (0 ... 1)
3793+ * \return \e false indicates failure (animation identifier out of range)
3794+ * \note Each animation is defined by its state, with extreme points state=0 and
3795+ * state=1. When setting a state between 0 and 1, Orbiter carries out the
3796+ * appropriate transformations to advance the animation to that state. It is
3797+ * the responsibility of the code developer to call SetAnimation in such a way
3798+ * as to provide a smooth movement of the animated parts.
3799+ */
3800+ bool SetAnimation (UINT anim, double state) const;
3801+
3802+ /**
3803+ * \brief Returns a pointer to the array of animations defined by the vessel
3804+ * \param[out] anim pointer list of vessel animations
3805+ * \return list length (number of animations)
3806+ * \note The pointer can become invalid whenever the vessel adds or deletes
3807+ * animations. It should therefore not be stored, but queried on demand.
3808+ */
3809+ UINT GetAnimPtr (ANIMATION **anim) const;
3810+ //@}
3811+
3812+
3813+ /// \name Recording/playback functions
3814+ //@{
3815+ /**
3816+ * \brief Flag for active recording session.
3817+ * \return \e true if flight recording is active, \e false otherwise.
3818+ * \sa Playback, RecordEvent
3819+ */
3820+ bool Recording () const;
3821+
3822+ /**
3823+ * \brief Flag for active playback session.
3824+ * \return \e true if the current session is a playback of a recorded flight,
3825+ * \e false otherwise.
3826+ * \sa Recording
3827+ */
3828+ bool Playback () const;
3829+
3830+ /**
3831+ * \brief Writes a custom tag to the vessel's articulation data stream during
3832+ * a running recording session.
3833+ * \param event_type event tag label
3834+ * \param event event string
3835+ * \note This function can be used to record custom vessel events (e.g.
3836+ * animations) to the articulation stream (.atc) of a vessel record.
3837+ * \note The function does nothing if no recording is active, so it is not
3838+ * necessary to check for a running recording before invoking RecordEvent.
3839+ * \note To read the recorded articulation tags during the playback of a
3840+ * recorded session, overload the VESSEL2::clbkPlaybackEvent callback
3841+ * function.
3842+ * \sa Recording, VESSEL2::clbkPlaybackEvent
3843+ */
3844+ void RecordEvent (const char *event_type, const char *event) const;
3845+ //@}
3846+
3847+
3848+ /// \name Coordinate transformations
3849+ //@{
3850+ /**
3851+ * \brief Register a shift in the centre of mass after a structural change
3852+ * (e.g. stage separation).
3853+ * \param shift centre of mass displacement vector [<b>m</b>]
3854+ * \note This function should be called after a vessel has undergone a
3855+ * structural change which resulted in a shift of the vessel's centre of
3856+ * gravity (CG). Note that in Orbiter, a vessel's CG coincides by definition
3857+ * always with the origin (0,0,0) of its local reference frame.
3858+ * Therefore, in order to achieve a shift of the CG by a vector <b>S</b>,
3859+ * this function shifts the vessel's global position by +<b>S</b>.
3860+ * This allows to shift the meshes by -<b>S</b>, thus retaining their
3861+ * global position.
3862+ * The net result is unchanged mesh positions in the global frame, but a
3863+ * shift of the local frame of reference (and thus CG) of +<b>S</b>.
3864+ * \note The camera position is shifted to take into account the new CG. An
3865+ * external camera view performs a smooth transition.
3866+ * \note The shift of meshes (and any other reference positions defined in
3867+ * the local vessel frame, such as docking ports, etc.) is not performed
3868+ * by this function but must be executed separately.
3869+ * A more convenient way to implement a transition of the centre of
3870+ * mass is the function \ref ShiftCG, which automatically takes care of
3871+ * translating meshes, docking ports, etc.
3872+ * \sa ShiftCG
3873+ */
3874+ void ShiftCentreOfMass (const VECTOR3 &shift);
3875+
3876+ /**
3877+ * \brief Shift the centre of gravity of a vessel.
3878+ * \param shift centre of gravity displacement vector [<b>m</b>]
3879+ * \note This function should be called after a vessel has undergone a
3880+ * structural change which resulted in a shift of the vessel's centre of
3881+ * gravity (CG). Note that in Orbiter, a vessel's CG coincides by definition
3882+ * always with the origin (0,0,0) of its local reference frame.
3883+ * Therefore, in order to achieve a shift of the CG by \a shift,
3884+ * this function performs the following actions:
3885+ * - Calls \ref ShiftCentreOfMass (+shift) to align the vessel's global
3886+ * position with the new CG position.
3887+ * - Calls \ref ShiftMeshes (-shift) to compensate the mesh positions
3888+ * - Applies equivalent shift to all
3889+ * - thruster positions,
3890+ * - docking ports,
3891+ * - attachment points,
3892+ * - explicitly defined light source positions,
3893+ * - and to the cockpit camera position
3894+ * .
3895+ * The net effect is a shift of the vessel frame of reference (and thus the
3896+ * CG by +shift, while the mesh positions remain in place in the global
3897+ * frame.
3898+ * \sa ShiftCentreOfMass, ShiftMeshes
3899+ */
3900+ void ShiftCG (const VECTOR3 &shift);
3901+
3902+ /**
3903+ * \brief Returns the centre of gravity of the superstructure to which the
3904+ * vessel belongs, if applicable.
3905+ * \param cg superstructure centre of gravity [<b>m</b>]
3906+ * \return \e true if the vessel is part of a superstructure, \e false
3907+ * otherwise.
3908+ * \note The returned vector is the position of the superstructure centre
3909+ * of gravity, in coordinates of the local vessel frame.
3910+ * \note If the vessel is not part of a superstructure, cg returns (0,0,0).
3911+ */
3912+ bool GetSuperstructureCG (VECTOR3 &cg) const;
3913+
3914+ /**
3915+ * \brief Returns the current rotation matrix for transformations
3916+ * from the vessel's local frame of reference to the global frame.
3917+ * \param R rotation matrix
3918+ * \note To transform a point rlocal from local vessel coordinates to a
3919+ * global point rglobal, the following formula is used: \n
3920+ * rglobal = R rlocal + pvessel, \n
3921+ * where pvessel is the vessel's global position.
3922+ * \note This transformation can be directly performed by a call to
3923+ * Local2Global.
3924+ * \sa Local2Global, SetRotationMatrix, GlobalRot
3925+ */
3926+ void GetRotationMatrix (MATRIX3 &R) const;
3927+
3928+ /**
3929+ * \brief Applies a rotation by replacing the vessel's local to global
3930+ * rotation matrix.
3931+ * \param R rotation matrix
3932+ * \note The rotation matrix maps from the orientation of the vessel's
3933+ * local frame of reference to the orientation of the global frame
3934+ * (ecliptic at 2000.0).
3935+ * \note The user is responsible for providing a valid rotation matrix.
3936+ * The matrix must be orthogonal and normalised: the norms of all
3937+ * column vectors of R must be 1, and scalar products between any
3938+ * column vectors must be 0.
3939+ * \sa GetRotationMatrix, Local2Global
3940+ */
3941+ void SetRotationMatrix (const MATRIX3 &R) const;
3942+
3943+ /**
3944+ * \brief Performs a rotation of a direction from the local vessel
3945+ * frame to the global frame.
3946+ * \param [in] rloc point in local vessel coordinates
3947+ * \param [out] rglob rotated point
3948+ * \note This function is equivalent to multiplying rloc with the
3949+ * rotation matrix returned by \ref GetRotationMatrix.
3950+ * \note Should be used to transform \e directions. To transform
3951+ * \e points, use \ref Local2Global, which additionally adds the
3952+ * vessel's global position to the rotated point.
3953+ * \sa GetRotationMatrix, Local2Global
3954+ */
3955+ void GlobalRot (const VECTOR3 &rloc, VECTOR3 &rglob) const;
3956+
3957+ /**
3958+ * \brief Performs a rotation from the local vessel frame to the
3959+ * current local horizon frame.
3960+ * \param [in] rloc vector in local vessel coordinates
3961+ * \param [out] rhorizon vector in local horizon coordinates
3962+ * \note The local horizon frame is defined as follows:
3963+ * - y is "up" direction (planet centre to vessel centre)
3964+ * - z is "north" direction
3965+ * - x is "east" direction
3966+ * \sa HorizonInvRot, GlobalRot, GetRotationMatrix, SetRotationMatrix
3967+ */
3968+ void HorizonRot (const VECTOR3 &rloc, VECTOR3 &rhorizon) const;
3969+
3970+ /**
3971+ * \brief Performs a rotation of a direction from the current local
3972+ * horizon frame to the local vessel frame.
3973+ * \param [in] rhorizon vector in local horizon coordinates
3974+ * \param [out] rloc vector in local vessel coordinates
3975+ * \note This function performs the inverse operation of \ref
3976+ * HorizonRot.
3977+ * \sa HorizonRot, GlobalRot, GetRotationMatrix, SetRotationMatrix
3978+ */
3979+ void HorizonInvRot (const VECTOR3 &rhorizon, VECTOR3 &rloc) const;
3980+
3981+ /**
3982+ * \brief Performs a transformation from local vessel coordinates to
3983+ * global coordinates.
3984+ * \param [in] local point in local vessel coordinates [<b>m</b>]
3985+ * \param [out] global transformed point in global coordinates [<b>m</b>]
3986+ * \note This function maps a point from the vessel's local coordinate
3987+ * system (centered at the vessel CG) into the global ecliptic
3988+ * system (centered at the solar system barycentre).
3989+ * \note The transform has the form
3990+ * \f[ \vec{p}_g = \mathsf{R}_v \vec{p}_l + \vec{p}_v \f]
3991+ * where R<sub>v</sub> is the vessel's global rotation matrix
3992+ * (as given by \ref GetRotationMatrix), and \f$\vec{p}_v\f$
3993+ * is the vessel position in the global frame.
3994+ * \sa GetRotationMatrix, Global2Local
3995+ */
3996+ void Local2Global (const VECTOR3 &local, VECTOR3 &global) const;
3997+
3998+ /**
3999+ * \brief Performs a transformation from global to local vessel
4000+ * coordinates.
4001+ * \param [in] global point in global coordinates [<b>m</b>]
4002+ * \param [out] local transformed point in local vessel coordinates [<b>m</b>]
4003+ * \note This is the inverse transform of \ref Local2Global. It maps
4004+ * a point from global ecliptic coordinates into the vessel's local
4005+ * frame.
4006+ * \note The transformation has the form
4007+ * \f[ \vec{p}_l = \mathsf{R}_v^{-1} (\vec{p}_g - \vec{p}_v) \f]
4008+ * where R<sub>v</sub> is the vessel's global rotation matrix
4009+ * (as given by \ref GetRotationMatrix), and \f$\vec{p}_v\f$ is the
4010+ * vessel position in the global frame.
4011+ * \sa GetRotationMatrix, Local2Global
4012+ */
4013+ void Global2Local (const VECTOR3 &global, VECTOR3 &local) const;
4014+
4015+ /**
4016+ * \brief Performs a transformation from local vessel coordinates
4017+ * to the ecliptic frame centered at the vessel's reference body.
4018+ * \param [in] local point in local vessel coordinates [<b>m</b>]
4019+ * \param [out] rel transformed point in reference body-relative
4020+ * ecliptic coordinates [<b>m</b>].
4021+ * \note This function maps a point from the vessel's local coordinate
4022+ * system into an ecliptic system centered at the centre of mass of
4023+ * the vessel's <i>gravity reference object</i> (the celestial body
4024+ * that is currently being orbited).
4025+ * \note A handle to the reference object can be obtained via
4026+ * \ref GetGravityRef. The reference object may change if the vessel
4027+ * enters a different object's sphere of influence.
4028+ * \note The transformation has the form
4029+ * \f[ \vec{p}_r = \mathsf{R}_v \vec{p}_l + \vec{p}_v - \vec{p}_\mathrm{ref} \f]
4030+ * where R<sub>v</sub> is the vessel's global rotation matrix (as given
4031+ * by \ref GetRotationMatrix), \f$\vec{p}_v\f$ is the vessel's global
4032+ * position, and \f$\vec{p}_\mathrm{ref}\f$ is the reference body's global
4033+ * position.
4034+ * \sa GetRotationMatrix, Global2Local, Local2Global, GetGravityRef
4035+ */
4036+ void Local2Rel (const VECTOR3 &local, VECTOR3 &rel) const;
4037+ //@}
4038+
4039+
4040+ /**
4041+ * \name Docking port management
4042+ * See also: \ref docking_management
4043+ */
4044+ //@{
4045+ /**
4046+ * \brief Create a new docking port.
4047+ * \param pos dock reference position in vessel coordinates [<b>m</b>]
4048+ * \param dir approach direction in vessel coordinates.
4049+ * \param rot longitudinal rotation alignment vector
4050+ * \return Handle for the new docking port.
4051+ * \note The \a dir and \a rot vectors should be normalised to length 1.
4052+ * \note The \a rot vector should be perpendicular to the \a dir vector.
4053+ * \note When two vessels connect at their docking ports, the relative
4054+ * orientation of the vessels is defined such that their respective
4055+ * approach direction vectors (dir) are anti-parallel, and their
4056+ * longitudinal alignment vectors (rot) are parallel.
4057+ * \sa DelDock, ClearDockDefinitions, GetDockParams, SetDockParams, DockCount,
4058+ * GetDockHandle, GetDockStatus, Dock, Undock
4059+ */
4060+ DOCKHANDLE CreateDock (const VECTOR3 &pos, const VECTOR3 &dir, const VECTOR3 &rot) const;
4061+
4062+ /**
4063+ * \brief Delete a previously defined docking port.
4064+ * \param hDock dock handle
4065+ * \return \e false indicates failure (invalid dock handle)
4066+ * \note Any object docked at the port will be undocked before the
4067+ * docking port is deleted.
4068+ * \sa CreateDock, ClearDockDefinitions, DockCount, Dock, Undock
4069+ */
4070+ bool DelDock (DOCKHANDLE hDock) const;
4071+
4072+ /**
4073+ * \brief Delete all docking ports defined for the vessel.
4074+ * \note Any docked objects will be undocked before deleting the
4075+ * docking ports.
4076+ * \sa CreateDock, DelDock, DockCount, Dock, Undock
4077+ */
4078+ void ClearDockDefinitions () const;
4079+
4080+ /**
4081+ * \brief Set the parameters for the vessel's primary docking port (port 0),
4082+ * or create a new dock if required.
4083+ * \param pos dock reference position in vessel coordinates [<b>m</b>]
4084+ * \param dir approach direction in vessel coordinates
4085+ * \param rot longitudinal rotation alignment vector
4086+ * \note This function creates a new docking port if none was previously
4087+ * defined.
4088+ * \note See \ref CreateDock for additional notes on the parameters.
4089+ * \sa SetDockParams(DOCKHANDLE,const VECTOR3&,const VECTOR3&,const VECTOR3&)const,
4090+ * GetDockParams, CreateDock, DelDock, DockCount, Dock, Undock
4091+ */
4092+ void SetDockParams (const VECTOR3 &pos, const VECTOR3 &dir, const VECTOR3 &rot) const;
4093+
4094+ /**
4095+ * \brief Reset the parameters for a vessel docking port.
4096+ * \param hDock dock handle
4097+ * \param pos new dock reference position [<b>m</b>]
4098+ * \param dir new approach direction
4099+ * \param rot new longitudinal rotation alignment vector
4100+ * \note This function should not be called while the docking
4101+ * port is engaged.
4102+ * \note The \a dir and \a rot direction vectors should be normalised
4103+ * to length 1.
4104+ * \sa SetDockParams(const VECTOR3&,const VECTOR3&,const VECTOR3&)const,
4105+ * GetDockParams, CreateDock, DelDock, DockCount, Dock, Undock
4106+ */
4107+ void SetDockParams (DOCKHANDLE hDock, const VECTOR3 &pos, const VECTOR3 &dir, const VECTOR3 &rot) const;
4108+
4109+ /**
4110+ * \brief Returns the paramters of a docking port.
4111+ * \param [in] hDock dock handle
4112+ * \param [out] pos dock reference position [<b>m</b>]
4113+ * \param [out] dir approach direction
4114+ * \param [out] rot longitudinal rotation alignment vector
4115+ * \sa CreateDock, SetDockParams(const VECTOR3&,const VECTOR3&,const VECTOR3&)const,
4116+ * SetDockParams(DOCKHANDLE,const VECTOR3&,const VECTOR3&,const VECTOR3&)const
4117+ */
4118+ void GetDockParams (DOCKHANDLE hDock, VECTOR3 &pos, VECTOR3 &dir, VECTOR3 &rot) const;
4119+
4120+ /**
4121+ * \brief Returns the number of docking ports defined for the vessel.
4122+ * \return Number of docking ports.
4123+ * \sa CreateDock, DelDock, ClearDockDefinitions
4124+ */
4125+ UINT DockCount () const;
4126+
4127+ /**
4128+ * \brief Returns a handle to a docking port.
4129+ * \param n docking port index (>= 0)
4130+ * \return Dock handle, or NULL if index is out of range.
4131+ * \sa CreateDock, DelDock, SetDockParams, GetDockParams, GetDockStatus, oapiGetDockHandle
4132+ */
4133+ DOCKHANDLE GetDockHandle (UINT n) const;
4134+
4135+ /**
4136+ * \brief Returns a handle to a docked vessel.
4137+ * \param hDock dock handle
4138+ * \return Handle of the vessel docked at the specified port, or
4139+ * NULL if the docking port is not engaged.
4140+ * \sa CreateDock, GetDockHandle, Dock, Undock, oapiGetDockStatus
4141+ */
4142+ OBJHANDLE GetDockStatus (DOCKHANDLE hDock) const;
4143+
4144+ /**
4145+ * \brief Returns a status flag for a docking port.
4146+ * \param port docking port index (>= 0)
4147+ * \return Docking status (0=free, 1=engaged)
4148+ * \note This method has the same functionality as
4149+ * \code (GetDockStatus (GetDockHandle(port)) ? 1:0) \endcode
4150+ * \sa GetDockStatus, GetDockHandle
4151+ */
4152+ UINT DockingStatus (UINT port) const;
4153+
4154+ /**
4155+ * \brief Dock to another vessel.
4156+ * \param target handle of docking target vessel
4157+ * \param n docking port index on vessel (>= 0)
4158+ * \param tgtn docking port index on target (>= 0)
4159+ * \param mode attachment mode (see notes)
4160+ * \return
4161+ * - 0=ok
4162+ * - 1=docking port \a n on the vessel already in use
4163+ * - 2=docking port \a tgtn on the target already in use
4164+ * - 3=target vessel already part of the vessel's superstructure
4165+ * \note This function is useful for designing scenario editors and during
4166+ * startup configuration, but its use should be avoided during a
4167+ * running simulation, because it can lead to unphysical situations:
4168+ * it allows to dock two vessels regardless of their current
4169+ * separation, by teleporting one of them to the location of the other.
4170+ * \note During a simulation, Orbiter will dock two vessels automatically
4171+ * when their docking ports are brought into close proximity.
4172+ * \note The mode parameter determines how the vessels are connected. The
4173+ * following settings are supported:
4174+ * - 0: calculate the linear and angular moments of the superstructure
4175+ * from the moments of the docking components. This should only be used
4176+ * if the two vessels are already in close proximity and aligned for
4177+ * docking.
4178+ * - 1: Keep this in place, and teleport the target vessel for docking
4179+ * - 2: Keep the target in place, and teleport this for docking.
4180+ * \sa Undock, GetDockHandle, GetDockStatus, DockCount
4181+ */
4182+ int Dock (OBJHANDLE target, UINT n, UINT tgtn, UINT mode) const;
4183+
4184+ /**
4185+ * \brief Release a docked vessel from a docking port.
4186+ * \param n docking port index (>= 0 or ALLDOCKS)
4187+ * \param exclude optional handle of a vessel to be excluded from undocking
4188+ * \return \e true if at least one vessel was released from a port.
4189+ * \note If \a n is set to ALLDOCKS, all docking ports are released
4190+ * simultaneously.
4191+ * \note If \a exclude is nonzero, this vessel will not be undocked. This
4192+ * is useful for implementing remote undocking in combination with
4193+ * ALLDOCKS.
4194+ * \sa Dock, GetDockHandle, GetDockStatus, DockCount
4195+ */
4196+ bool Undock (UINT n, const OBJHANDLE exclude = 0) const;
4197+
4198+ /**
4199+ * \brief Set the docking approach mode for all docking ports.
4200+ * \param mode docking mode (see notes)
4201+ * \note Defines the method Orbiter applies to establish a docking
4202+ * connection between two vessels. Supported values are:
4203+ * - 0: use legacy (2006) method: snap to dock as soon as two docking
4204+ * ports are within 0.5m and closing.
4205+ * - 1 (default): use new (2010) method: snap to dock as soon as one docking
4206+ * reference point passes through the reference plane of the other
4207+ * dock within 0.5m.
4208+ * \note If the two docking vessels use different docking modes, the
4209+ * method used is unpredictable, depending on which vessel initiates
4210+ * the docking event.
4211+ */
4212+ void SetDockMode (int mode) const;
4213+ //@}
4214+
4215+
4216+ /**
4217+ * \name Passive attachment management
4218+ * See also: \ref attachment_management
4219+ */
4220+ //@{
4221+ /**
4222+ * \brief Define a new attachment point for a vessel.
4223+ * \param toparent If \e true, the attachment can be used to connect to
4224+ * a parent (i.e. the vessel acts as a child). Otherwise, attachment is
4225+ * used to connect to a child (i.e. vessel acts as parent)
4226+ * \param pos attachment point position in vessel coordinates [<b>m</b>]
4227+ * \param dir attachment direction in vessel coordinates
4228+ * \param rot longitudinal alignment vector in vessel coordinates
4229+ * \param id compatibility identifier
4230+ * \param loose If \e true, allow loose connections (see notes)
4231+ * \return Handle to new attachment point
4232+ * \note A vessel can define multiple parent and child attachment points,
4233+ * and can subsequently have multiple children attached, but it can
4234+ * only be attached to a single parent at any one time.
4235+ * \note The \a dir and \a rot vectors should both be normalised to length
4236+ * 1, and they should be orthogonal.
4237+ * \note The identifier string can contain up to 8 characters. It can be
4238+ * used to define compatibility between attachment points.
4239+ * \note If the attachment point is defined as \a loose, then the relative
4240+ * orientation between the two attached objects is frozen to the
4241+ * orientation between them at the time the connection was established.
4242+ * Otherwise, the two objects snap to the orientation defined by their
4243+ * \a dir vectors.
4244+ * \sa SetAttachmentParams, GetAttachmentParams, GetAttachmentId,
4245+ * GetAttachmentStatus, AttachmentCount, GetAttachmentIndex, GetAttachmentHandle,
4246+ * AttachChild, DetachChild
4247+ */
4248+ ATTACHMENTHANDLE CreateAttachment (bool toparent, const VECTOR3 &pos, const VECTOR3 &dir, const VECTOR3 &rot, const char *id, bool loose = false) const;
4249+
4250+ /**
4251+ * \brief Delete an attachment point.
4252+ * \param attachment attachment handle
4253+ * \return \e false indicates failure (invalid attachment handle)
4254+ * \note The attachment handle can refer to either a child or parent
4255+ * attachment point.
4256+ * \note Any object attached to this point will be released.
4257+ * \note After this function returns successfully, the attachment handle
4258+ * is no longer valid.
4259+ * \sa CreateAttachment
4260+ */
4261+ bool DelAttachment (ATTACHMENTHANDLE attachment) const;
4262+
4263+ /**
4264+ * \brief Delete all attachment points defined for the vessel.
4265+ * \note Any attached parent or child vessels will be released.
4266+ * \note After this function returns, all previously defined attachment
4267+ * handles will no longer be valid.
4268+ */
4269+ void ClearAttachments () const;
4270+
4271+ /**
4272+ * \brief Reset attachment position and orientation for an existing
4273+ * attachment point.
4274+ * \param attachment attachment handle
4275+ * \param pos new attachment point position in vessel coordinates [<b>m</b>]
4276+ * \param dir new attachment direction in vessel coordinates
4277+ * \param rot new longitudinal alignment vector in vessel coordinates
4278+ * \note If the parameters of an attachment point are changed while a vessel
4279+ * is attached to that point, the attached vessel will be shifted to the
4280+ * new position automatically.
4281+ * \note The \a dir and \a rot vectors should both be normalised to length 1,
4282+ * and they should be orthogonal.
4283+ * \sa CreateAttachment, GetAttachmentParams, GetAttachmentId,
4284+ * GetAttachmentStatus, AttachmentCount, GetAttachmentIndex, GetAttachmentHandle,
4285+ * AttachChild, DetachChild
4286+ */
4287+ void SetAttachmentParams (ATTACHMENTHANDLE attachment, const VECTOR3 &pos, const VECTOR3 &dir, const VECTOR3 &rot) const;
4288+
4289+ /**
4290+ * \brief Retrieve the parameters of an attachment point.
4291+ * \param [in] attachment attachment handle
4292+ * \param [out] pos attachment point position in vessel coordinates [<b>m</b>]
4293+ * \param [out] dir attachment direction in vessel coordinates
4294+ * \param [out] rot longitudinal alignment vector in vessel coordinates
4295+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentId,
4296+ * GetAttachmentStatus, AttachmentCount, GetAttachmentIndex, GetAttachmentHandle,
4297+ * AttachChild, DetachChild
4298+ */
4299+ void GetAttachmentParams (ATTACHMENTHANDLE attachment, VECTOR3 &pos, VECTOR3 &dir, VECTOR3 &rot) const;
4300+
4301+ /**
4302+ * \brief Retrieve attachment identifier string.
4303+ * \param attachment attachment handle
4304+ * \return Pointer to attachment string [8 characters]
4305+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4306+ * GetAttachmentStatus, AttachmentCount, GetAttachmentIndex, GetAttachmentHandle,
4307+ * AttachChild, DetachChild
4308+ */
4309+ const char *GetAttachmentId (ATTACHMENTHANDLE attachment) const;
4310+
4311+ /**
4312+ * \brief Return the current status of an attachment point.
4313+ * \param attachment attachment handle
4314+ * \return Handle of tha attached vessel, or NULL if no vessel is attached
4315+ * to this point.
4316+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4317+ * GetAttachmentId, AttachmentCount, GetAttachmentIndex, GetAttachmentHandle,
4318+ * AttachChild, DetachChild
4319+ */
4320+ OBJHANDLE GetAttachmentStatus (ATTACHMENTHANDLE attachment) const;
4321+
4322+ /**
4323+ * \brief Return the number of child or parent attachment points defined
4324+ * for the vessel.
4325+ * \param toparent If \e true, return the number of attachment points to
4326+ * parents. Otherwise, return the number of attachment points to children.
4327+ * \return Number of defined attachment points to connect to parents or to
4328+ * children.
4329+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4330+ * GetAttachmentId, GetAttachmentStatus, GetAttachmentIndex, GetAttachmentHandle,
4331+ * AttachChild, DetachChild
4332+ */
4333+ DWORD AttachmentCount (bool toparent) const;
4334+
4335+ /**
4336+ * \brief Return the list index of the vessel's attachment point defined
4337+ * by its handle.
4338+ * \param attachment attachment handle
4339+ * \return List index (>= 0)
4340+ * \note A vessel defines separate lists for child and parent attachment
4341+ * points. Therefore two different attachment points may return the same
4342+ * index.
4343+ * \note The index for a given attachment point can change when the vessel
4344+ * deletes any of its attachments. The returned index should therefore be
4345+ * used only within the current frame.
4346+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4347+ * GetAttachmentId, GetAttachmentStatus, AttachmentCount, GetAttachmentHandle,
4348+ * AttachChild, DetachChild
4349+ */
4350+ DWORD GetAttachmentIndex (ATTACHMENTHANDLE attachment) const;
4351+
4352+ /**
4353+ * \brief Return the handle of an attachment point identified by its list
4354+ * index.
4355+ * \param toparent If \e true, return a handle for an attachment point to
4356+ * a parent. Otherwise, return a handle for an attachment point to a child.
4357+ * \param i attachment index (>= 0)
4358+ * \return Attachment handle, or NULL if index out of range.
4359+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4360+ * GetAttachmentId, GetAttachmentStatus, AttachmentCount, GetAttachmentIndex,
4361+ * AttachChild, DetachChild
4362+ */
4363+ ATTACHMENTHANDLE GetAttachmentHandle (bool toparent, DWORD i) const;
4364+
4365+ /**
4366+ * \brief Attach a child vessel to an attachment point.
4367+ * \param child handle of child vessel to be attached.
4368+ * \param attachment attachment point to which the child will be attached.
4369+ * \param child_attachment attachment point on the child to which we want
4370+ * to attach.
4371+ * \return \e true indicates success, \e false indicates failure (child
4372+ * refuses attachment)
4373+ * \note The \a attachment handle must refer to an attachment "to child"
4374+ * (i.e. created with toparent=false); the \a child_attachment handle
4375+ * must refer to an attachment "to parent" on the child object (i.e.
4376+ * created with toparent=true). It is not possible to connect two parent
4377+ * or two child attachment points.
4378+ * \note A child can only be connected to a single parent at any one time.
4379+ * If the child is already connected to a parent, the previous parent
4380+ * connection is severed.
4381+ * \note The child may check the parent attachment's id string and,
4382+ * depending on the value, refuse to connect. In that case, the function
4383+ * returns \e false.
4384+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4385+ * GetAttachmentId, GetAttachmentStatus, AttachmentCount, GetAttachmentIndex,
4386+ * GetAttachmentHandle, DetachChild
4387+ */
4388+ bool AttachChild (OBJHANDLE child, ATTACHMENTHANDLE attachment, ATTACHMENTHANDLE child_attachment) const;
4389+
4390+ /**
4391+ * \brief Break an existing attachment to a child.
4392+ * \param attachment attachment handle
4393+ * \param vel separation velocity [m/s]
4394+ * \return \e true when detachment is successful, \e false if no child was
4395+ * attached, or if child refuses to detach.
4396+ * \sa CreateAttachment, SetAttachmentParams, GetAttachmentParams,
4397+ * GetAttachmentId, GetAttachmentStatus, AttachmentCount, GetAttachmentIndex,
4398+ * GetAttachmentHandle, AttachChild
4399+ */
4400+ bool DetachChild (ATTACHMENTHANDLE attachment, double vel = 0.0) const;
4401+ //@}
4402+
4403+
4404+ /// \name Exhaust and entry render functions
4405+ //@{
4406+ /**
4407+ * \brief Add an exhaust render definition for a thruster.
4408+ * \param th thruster handle
4409+ * \param lscale exhaust flame length [m]
4410+ * \param wscale exhaust flame width [m]
4411+ * \param tex texture handle for custom exhaust flames
4412+ * \return Exhaust identifier
4413+ * \note Thrusters defined with \ref CreateThruster do not by default render
4414+ * exhaust effects, until an exhaust definition has been specified with
4415+ * AddExhaust.
4416+ * \note The size of the exhaust flame is automatically scaled by the thrust
4417+ * level.
4418+ * \note This version retrieves exhaust reference position and direction
4419+ * directly from the thruster setting, and will therefore automatically
4420+ * reflect any changes caused by \ref SetThrusterRef and \ref SetThrusterDir.
4421+ * \note To use a custom exhaust texture, set \a tex to a surface handle returned
4422+ * by \ref oapiRegisterExhaustTexture. If \a tex == 0, the default texture
4423+ * is used.
4424+ * \sa AddExhaust(THRUSTER_HANDLE,double,double,double,SURFHANDLE)const,
4425+ * AddExhaust(THRUSTER_HANDLE,double,double,const VECTOR3&,const VECTOR3&,SURFHANDLE)const,
4426+ * DelExhaust,CreateThruster,SetThrusterRef,SetThrusterDir,SetThrusterLevel,
4427+ * oapiRegisterExhaustTexture
4428+ */
4429+ UINT AddExhaust (THRUSTER_HANDLE th, double lscale, double wscale, SURFHANDLE tex = 0) const;
4430+
4431+ /**
4432+ * \brief Add an exhaust render definition for a thruster with additional
4433+ * offset.
4434+ * \param th thruster handle
4435+ * \param lscale exhaust flame length [m]
4436+ * \param wscale exhaust flame width [m]
4437+ * \param lofs longitudinal offset [m]
4438+ * \param tex texture handle for custom exhaust flames
4439+ * \return Exhaust identifier
4440+ * \note This method allows to add an additional longitudinal offset between
4441+ * thruster position and exhaust.
4442+ * \sa AddExhaust(THRUSTER_HANDLE,double,double,SURFHANDLE)const,
4443+ * AddExhaust(THRUSTER_HANDLE,double,double,const VECTOR3&,const VECTOR3&,SURFHANDLE)const,
4444+ * DelExhaust,CreateThruster,SetThrusterRef,SetThrusterDir,SetThrusterLevel,
4445+ * oapiRegisterExhaustTexture
4446+ */
4447+ UINT AddExhaust (THRUSTER_HANDLE th, double lscale, double wscale, double lofs, SURFHANDLE tex = 0) const;
4448+
4449+ /**
4450+ * \brief Add an exhaust render definition for a thruster with explicit
4451+ * reference position and direction.
4452+ * \param th thruster handle
4453+ * \param lscale exhaust flame length [m]
4454+ * \param wscale exhaust flame width [m]
4455+ * \param pos reference position in vessel coordinates [<b>m</b>]
4456+ * \param dir exhaust direction in vessel coordinates
4457+ * \param tex texture handle for custom exhaust flames
4458+ * \note This version uses the explicitly provided reference position
4459+ * and direction, rather than using the thruster parameters.
4460+ * \note This allows multiple exhaust render definitions to refer to a
4461+ * single thruster definition, e.g. where multiple thrusters have been
4462+ * combined into a single "logical" thruster definition. This
4463+ * technique can be used to simplify the description of thruster
4464+ * groups which are always addressed synchronously.
4465+ * \note The exhaust direction should be opposite to the thrust
4466+ * direction of the thruster it refers to.
4467+ * \note Exhaust positions and directions are fixed in this version, so
4468+ * they will not react to changes caused by \ref SetThrusterRef and
4469+ * \ref SetThrusterDir.
4470+ * \note To use a custom exhaust texture, set \a tex to a surface handle
4471+ * returned by \ref oapiRegisterExhaustTexture. If \a tex == 0, the
4472+ * default texture is used.
4473+ * \sa AddExhaust(THRUSTER_HANDLE,double,double,SURFHANDLE)const,
4474+ * AddExhaust(THRUSTER_HANDLE,double,double,double,SURFHANDLE)const,
4475+ * DelExhaust,CreateThruster,SetThrusterRef,SetThrusterDir,SetThrusterLevel,
4476+ * oapiRegisterExhaustTexture
4477+ */
4478+ UINT AddExhaust (THRUSTER_HANDLE th, double lscale, double wscale, const VECTOR3 &pos, const VECTOR3 &dir, SURFHANDLE tex = 0) const;
4479+
4480+ /**
4481+ * \brief Add an exhaust render definition defined by a parameter structure.
4482+ * \param spec exhaust specification
4483+ * \return Exhaust identifier
4484+ * \note This method is more versatile than the other AddExhaust versions.
4485+ * It allows dynamic custom control of exhaust level, position and direction,
4486+ * and it can be defined independently of thrusters.
4487+ * \note To let the exhaust appearance be automatically controlled by a thruster,
4488+ * set spec->th to the thruster handle. The fields spec->level, spec->lpos and
4489+ * spec->ldir can then be set to NULL, to indicate that they should be linked to
4490+ * the thruster parameters.
4491+ * \note If spec->th == NULL (thruster-independent exhaust definition), then
4492+ * spec->level, spec->lpos and spec->ldir must not be NULL. They must point to
4493+ * variables that continuously define the level, position and negative direction of the
4494+ * exhaust cone. The variables themselves must persist during the lifetime of the
4495+ * exhaust definition.
4496+ * \note An exeption is the definition of a constant parameter. For example, if the
4497+ * exhaust position is to be set to a fixed position, set the spec->flags
4498+ * field to EXHAUST_CONSTANTPOS. In this case, the value pointed to by spec->lpos
4499+ * is copied by Orbiter, and the variable can be discarded after the call to
4500+ * AddExhaust. In a similar fashion, the bit flags EXHAUST_CONSTANTDIR and
4501+ * EXHAUST_CONSTANTLEVEL can be added to indicate fixed direction and exhaust
4502+ * level, respectively.
4503+ * \note If the spec->ldir parameter is provided, it must specify the engine thrust
4504+ * direction (= the negative exhaust direction), in contrast to the other
4505+ * AddExhaust functions, which refer to the positive exhaust direction.
4506+ * \note spec->lsize and spec->wsize define the length and width of the exhaust
4507+ * flame [m].
4508+ * \note spec->lofs defines a longitudinal offset between the reference position
4509+ * and the exhaust flame.
4510+ * \note spec->modulate defines the amplitude of a random variation in exhaust
4511+ * level, between 0 (none) and 1 (max).
4512+ * \note spec->tex can be used to provide a custom exhaust texture. If spec->tex
4513+ * == NULL, then the default exhaust texture is used.
4514+ */
4515+ UINT AddExhaust (EXHAUSTSPEC *spec);
4516+
4517+ /**
4518+ * \brief Removes an exhaust render definition.
4519+ * \param idx exhaust identifier
4520+ * \return \e false if exhaust definition does not exist, \e true otherwise.
4521+ * \sa AddExhaust, GetExhaustCount
4522+ */
4523+ bool DelExhaust (UINT idx) const;
4524+
4525+ /**
4526+ * \brief Returns the number of exhaust render definitions for the vessel.
4527+ * \return Number of exhaust render definitions
4528+ * \sa AddExhaust, DelExhaust
4529+ */
4530+ DWORD GetExhaustCount () const;
4531+
4532+ /**
4533+ * \brief Returns the parameters of an exhaust definition.
4534+ * \param [in] idx exhaust identifier
4535+ * \param [out] lscale exhaust flame length [m]
4536+ * \param [out] wscale exhaust flame width [m]
4537+ * \param [out] pos reference position [<b>m</b>]
4538+ * \param [out] dir exhaust direction
4539+ * \param [out] tex texture handle for custom exhaust flames, if any
4540+ * \return \e false if \a idx out of range, \e true otherwise.
4541+ * \sa AddExhaust
4542+ */
4543+ bool GetExhaustSpec (UINT idx, double *lscale, double *wscale, VECTOR3 *pos, VECTOR3 *dir, SURFHANDLE *tex) const;
4544+
4545+ /**
4546+ * \brief Returns the parameters of an exhaust definition in a structure.
4547+ * \param [in] idx exhaust identifier
4548+ * \param [out] spec pointer to EXHAUSTSPEC structure
4549+ * \return \e false if \a idx is out of range, \e true otherwise.
4550+ * \note On return the parameters of the specified exhaust object are
4551+ * copied into the structure pointed to by spec.
4552+ */
4553+ bool GetExhaustSpec (UINT idx, EXHAUSTSPEC *spec);
4554+
4555+ /**
4556+ * \brief Returns the current level of an exhaust source.
4557+ * \param idx exhaust identifier
4558+ * \return Exhaust level (0..1)
4559+ * \note The exhaust level is equivalent to the thrust level of the thruster
4560+ * to which the exhaust definition is attached.
4561+ * \sa AddExhaust, GetThrusterLevel
4562+ */
4563+ double GetExhaustLevel (UINT idx) const;
4564+
4565+ /**
4566+ * \brief Select a previously registered texture to be used for rendering reentry flames.
4567+ * \param tex texture handle
4568+ * \param plimit friction power limit
4569+ * \param lscale texture length scaling factor
4570+ * \param wscale texture width scaling factor
4571+ * \note The texture handle is obtained by a previous call to \ref oapiRegisterReentryTexture.
4572+ * \note If a custom texture is not explicitly set, Orbiter uses a default
4573+ * texture (reentry.dds) for rendering reentry flames. To suppress reentry
4574+ * flames altogether for a vessel, call SetReentryTexture(NULL).
4575+ * \sa oapiRegisterReentryTexture
4576+ */
4577+ void SetReentryTexture (SURFHANDLE tex, double plimit=6e7, double lscale=1.0, double wscale=1.0) const;
4578+ //@}
4579+
4580+
4581+ /// \name Particle systems
4582+ //@{
4583+ /**
4584+ * \brief Adds a custom particle stream to a vessel.
4585+ * \param pss pointer to particle stream definition structure
4586+ * \param pos particle source position in vessel coordinates [<b>m</b>]
4587+ * \param dir particle emission direction in vessel coordinates
4588+ * \param lvl pointer to scaling factor
4589+ * \return Particle stream handle
4590+ * \note This function can be used to add venting effects and similar.
4591+ * For engine-specific effects such as exhaust and contrails, use the
4592+ * \ref AddExhaustStream functions instead.
4593+ * \note The \ref PARTICLESTREAMSPEC structure defined the properties of
4594+ * the particle stream.
4595+ * \note The position and direction variables are in vessel-relative
4596+ * coordinates. They cannot be redefined.
4597+ * \note \a lvl points to a variable which defines the strength of the
4598+ * particle emission. Its value should be set in the range from 0
4599+ * (particle generation off) to 1 (emission at full strength). It can
4600+ * be changed continuously to modulate the particle generation.
4601+ * \sa AddExhaustStream, AddReentryStream
4602+ */
4603+ PSTREAM_HANDLE AddParticleStream (PARTICLESTREAMSPEC *pss, const VECTOR3 &pos, const VECTOR3 &dir, double *lvl) const;
4604+
4605+ /**
4606+ * \brief Adds an exhaust particle stream to a vessel.
4607+ * \param th thruster handle
4608+ * \param pss particle stream specification
4609+ * \return Particle stream handle
4610+ * \note Exhaust streams can be emissive (to simulate "glowing" ionised
4611+ * gases) or diffuse (e.g. for simulating vapour trails).
4612+ * \note The \ref PARTICLESTREAMSPEC structure defined the properties of
4613+ * the particle stream.
4614+ * \note Multiple streams can be defined for a single engine. For
4615+ * example, an emissive stream with short lifetime may represent the
4616+ * ionised exhaust gases, while a diffuse stream with longer lifetime
4617+ * represents the vapour trail.
4618+ * \note To improve performance, closely packed engines may share a
4619+ * single exhaust stream.
4620+ * \note If the user has disabled particle streams in the launchpad
4621+ * dialog, this function will return NULL. The module must be able
4622+ * to cope with this case.
4623+ * \sa AddExhaustStream(THRUSTER_HANDLE,const VECTOR3&,PARTICLESTREAMSPEC*)const,
4624+ * AddParticleStream, AddReentryStream
4625+ */
4626+ PSTREAM_HANDLE AddExhaustStream (THRUSTER_HANDLE th, PARTICLESTREAMSPEC *pss = 0) const;
4627+
4628+ /**
4629+ * \brief Adds an exhaust particle stream to a vessel.
4630+ * \param th thruster handle
4631+ * \param pos particle emission reference point
4632+ * \param pss particle stream specification
4633+ * \return Particle stream handle
4634+ * \note This version allows to pass an explicit particle emission
4635+ * reference position, independent of the engine reference point.
4636+ * \note If the user has disabled particle streams in the launchpad
4637+ * dialog, this function will return NULL. The module must be able
4638+ * to cope with this case.
4639+ * \sa AddExhaustStream(THRUSTER_HANDLE,PARTICLESTREAMSPEC*)const,
4640+ * AddParticleStream, AddReentryStream
4641+ */
4642+ PSTREAM_HANDLE AddExhaustStream (THRUSTER_HANDLE th, const VECTOR3 &pos, PARTICLESTREAMSPEC *pss = 0) const;
4643+
4644+ /**
4645+ * \brief Adds a reentry particle stream to a vessel.
4646+ * \param pss particle stream specification
4647+ * \return Particle stream handle
4648+ * \note Vessels automatically define a default emissive particle stream,
4649+ * but you may want to add further stream to customise the appearance.
4650+ * \sa AddParticleStream, AddExhaustStream
4651+ */
4652+ PSTREAM_HANDLE AddReentryStream (PARTICLESTREAMSPEC *pss) const;
4653+
4654+ /**
4655+ * \brief Delete an existing particle stream.
4656+ * \param ch particle stream handle
4657+ * \return \e false indicates failure (particle stream not found)
4658+ * \note If a thruster is deleted (with ref DelThruster), any attached
4659+ * particle streams are deleted automatically.
4660+ * \note A deleted particle stream will no longer emit particles, but
4661+ * existing particles persist until they expire.
4662+ * \sa AddParticleStream, AddExhaustStream, AddReentryStream
4663+ */
4664+ bool DelExhaustStream (PSTREAM_HANDLE ch) const;
4665+ //@}
4666+
4667+
4668+ /// \name Nosewheel-steering and wheel brakes
4669+ //@{
4670+ /**
4671+ * \param activate \e true to activate, \e false to deactivate
4672+ * \note With nose-wheel steering active, the yaw controls will
4673+ * apply a lateral force on the front touchdown-point when in
4674+ * ground contact.
4675+ * \note By default, nose-wheel steering is inactive. This
4676+ * function should only be called for appropriate vessel types.
4677+ * \sa GetNosewheelSteering
4678+ */
4679+ void SetNosewheelSteering (bool activate) const;
4680+
4681+ /**
4682+ * \brief Returns the activation state of the nose-wheel steering
4683+ * system.
4684+ * \return \e true indicates nose-wheel steering is active,
4685+ * \e false indicates disabled.
4686+ * \sa SetNosewheelSteering
4687+ */
4688+ bool GetNosewheelSteering () const;
4689+
4690+ /**
4691+ * \brief Define the maximum force which can be provided by the
4692+ * vessel's wheel brake system.
4693+ * \param f maximum force [N]
4694+ * \sa SetWheelbrakeLevel, GetWheelbrakeLevel
4695+ */
4696+ void SetMaxWheelbrakeForce (double f) const;
4697+
4698+ /**
4699+ * \brief Apply the wheel brake.
4700+ * \param level wheelbrake level [0..1]
4701+ * \param which 0 = both, 1 = left, 2 = right main gear
4702+ * \param permanent \e true sets the level permanently, \e false
4703+ * only applies to current time step
4704+ * \sa SetMaxWheelbrakeForce, GetWheelbrakeLevel
4705+ */
4706+ void SetWheelbrakeLevel (double level, int which = 0, bool permanent = true) const;
4707+
4708+ /**
4709+ * \brief Returns the current wheel brake level.
4710+ * \param which 0 = average of both main gear levels, 1 = left, 2 = right
4711+ * \return wheel brake level [0..1]
4712+ * \sa SetMaxWheelbrakeForce, SetWheelbrakeLevel
4713+ */
4714+ double GetWheelbrakeLevel (int which) const;
4715+ //@}
4716+
4717+
4718+ /// \name Beacon management
4719+ //@{
4720+ /**
4721+ * \brief Add a light beacon definition to a vessel.
4722+ * \param bs structure defining the beacon parameters
4723+ * \note The BEACONLIGHTSPEC variable passed to AddBeacon (as well as
4724+ * the pos and col vectors pointed to by the structure) must remain
4725+ * valid until the beacon is removed (with DelBeacon, ClearBeacons,
4726+ * or by deleting the vessel). It should therefore either be defined
4727+ * static, or as a member of the derived vessel class.
4728+ * \note The BEACONLIGHTSPEC parameters can be modified at any time by
4729+ * the module after the call to AddBeacon, to modify the beacon
4730+ * appearance. The changes take effect immediately.
4731+ * \note To turn the beacon off temporarily, don't delete the beacon
4732+ * but simply set the \e active element to false.
4733+ * \note \a shape defines the appearance of the beacon. Currently
4734+ * supported are:
4735+ * - BEACONSHAPE_COMPACT (a compact blob)
4736+ * - BEACONSHAPE_DIFFUSE (a more diffuse blob)
4737+ * - BEACONSHAPE_STAR (a starlike appearance)
4738+ * \note \a falloff detemines how the render size of the beacon
4739+ * changes with distance. The value should be between 0 and 1, where
4740+ * 0 means that the apparent size of the beacon is proportional to
4741+ * 1/distance, and 1 means that the apparent size doesn't change at
4742+ * all with distance. The higher the value, the further away the
4743+ * beacon will remain visible. (but note that visibility is limited
4744+ * to the range defined by \ref SetVisibilityLimit).
4745+ * \note \a period, \a duration and \a tofs are used to define a
4746+ * periodically blinking beacon (strobe). To define a continuous
4747+ * beacon, set period = 0. The two other parameters are then ignored.
4748+ * \sa DelBeacon, ClearBeacons, SetVisibilityLimit
4749+ */
4750+ void AddBeacon (BEACONLIGHTSPEC *bs);
4751+
4752+ /**
4753+ * \brief Remove a beacon definition from the vessel.
4754+ * \param bs pointer to the BEACONLIGHTSPEC structure previously use to
4755+ * define the beacon with AddBeacon.
4756+ * \return \e true if the beacon definition was found and removed,
4757+ * \e false otherwise.
4758+ * \note DelBeacon removes the beacon reference from the vessel's list
4759+ * of beacons, but does not deallocate the beacon itself. If the
4760+ * vessel had defined the beacon specification dynamically, it should
4761+ * deallocate it after this call.
4762+ * \sa AddBeacon, ClearBeacons
4763+ */
4764+ bool DelBeacon (BEACONLIGHTSPEC *bs);
4765+
4766+ /**
4767+ * \brief Remove all beacon definitions from the vessel.
4768+ * \sa AddBeacon, DelBeacon
4769+ */
4770+ void ClearBeacons ();
4771+
4772+ /**
4773+ * \brief Returns a pointer to one of the vessel's beacon specifications.
4774+ * \param idx beacon list index (>= 0)
4775+ * \return Pointer to specification for vessel beacon at list index
4776+ * \a idx, or NULL if \a idx is out of range.
4777+ * \note The list index for a given beacon can change when the vessel
4778+ * adds or deletes beacons.
4779+ */
4780+ const BEACONLIGHTSPEC *GetBeacon (DWORD idx) const;
4781+ //@}
4782+
4783+
4784+ ///\ name Light emitters
4785+ //@{
4786+ /**
4787+ * \brief Add an isotropic point light source to the vessel.
4788+ * \param pos source position [<b>m</b>] in vessel coordinates
4789+ * \param range light source range [m]
4790+ * \param att0 attenuation coefficients (see notes)
4791+ * \param att1 attenuation coefficients (see notes)
4792+ * \param att2 attenuation coefficients (see notes)
4793+ * \param diffuse source contribution to diffuse object colours
4794+ * \param specular source contribution to specular object colours
4795+ * \param ambient source contribution to ambient object colours
4796+ * \return pointer to new emitter object
4797+ * \note The intensity \e I of the light source as a function of distance
4798+ * \e d is defined via the coefficients \att by
4799+ * \f[ I = \frac{1}{ \mathrm{att}_0 + d \mathrm{att}_1 + d^2 \mathrm{att}_2} \f]
4800+ */
4801+ LightEmitter *AddPointLight (const VECTOR3 &pos, double range, double att0, double att1, double att2, COLOUR4 diffuse, COLOUR4 specular, COLOUR4 ambient) const;
4802+
4803+ /**
4804+ * \brief Add a directed spot light source to the vessel.
4805+ * \param pos source position [<b>m</b>] in vessel coordinates
4806+ * \param dir light direction in vessel coordinates
4807+ * \param range light source range [m]
4808+ * \param att0 attenuation coefficients (see notes)
4809+ * \param att1 attenuation coefficients (see notes)
4810+ * \param att2 attenuation coefficients (see notes)
4811+ * \param umbra aperture of inner (maximum intensity) cone [rad]
4812+ * \param penumbra aperture of outer (zero intensity) cone [rad]
4813+ * \param diffuse source contribution to diffuse object colours
4814+ * \param specular source contribution to specular object colours
4815+ * \param ambient source contribution to ambient object colours
4816+ * \return pointer to new emitter object
4817+ * \note The intensity \e I of the light source as a function of distance
4818+ * \e d is defined via the coefficients \att by
4819+ * \f[ I = \frac{1}{ \mathrm{att}_0 + d \mathrm{att}_1 + d^2 \mathrm{att}_2} \f]
4820+ */
4821+ LightEmitter *AddSpotLight (const VECTOR3 &pos, const VECTOR3 &dir, double range, double att0, double att1, double att2, double umbra, double penumbra, COLOUR4 diffuse, COLOUR4 specular, COLOUR4 ambient) const;
4822+
4823+ /**
4824+ * \brief Returns the number of light sources defined for the vessel.
4825+ * \return Number of light sources.
4826+ */
4827+ DWORD LightEmitterCount () const;
4828+
4829+ /**
4830+ * \brief Returns a pointer to a light source object identified by index.
4831+ * \param i emitter index (>= 0)
4832+ * \return Pointer to light source object, or NULL if index out of range
4833+ * \note The index of a given source object can change if other objects in
4834+ * the list are deleted.
4835+ * \sa LightEmitterCount
4836+ */
4837+ const LightEmitter *GetLightEmitter (DWORD i) const;
4838+
4839+ /**
4840+ * \brief Deletes the specified light source from the vessel.
4841+ * \param le pointer to light emitter object
4842+ * \return \e true if the emitter was successfully deleted, \e false if
4843+ * the source was not recognised by the vessel.
4844+ * \note If the method returns \e true, the emitter (le) was deallocated
4845+ * and the pointer should no longer be used.
4846+ * \sa ClearLightEmitters, LightEmitterCount
4847+ */
4848+ bool DelLightEmitter (LightEmitter *le) const;
4849+
4850+ /**
4851+ * \brief Remove all light sources defined for the vessel.
4852+ * \sa AddPointLight, AddSpotLight, LightEmitterCount
4853+ */
4854+ void ClearLightEmitters () const;
4855+ //@}
4856+
4857+
4858+ /// \name File I/O
4859+ //@{
4860+ /**
4861+ * \brief Pass a line read from a scenario file to Orbiter for default processing.
4862+ * \param line line to be interpreted
4863+ * \param status status parameters (points to a VESSELSTATUSx variable).
4864+ * \note This function should be used within the body of \ref VESSEL2::clbkLoadStateEx.
4865+ * \note The parser clbkLoadStateEx should forward all lines not recognised
4866+ * by the module to Orbiter via ParseScenarioLineEx to allow processing of
4867+ * standard vessel settings.
4868+ * \note clbkLoadStateEx currently provides a VESSELSTATUS2 status definition.
4869+ * This may change in future versions, so status should not be used within
4870+ * clbkLoadStateEx other than passing it to ParseScenarioLineEx.
4871+ * \sa VESSEL2::clbkLoadStateEx
4872+ */
4873+ void ParseScenarioLineEx (char *line, void *status) const;
4874+ //@}
4875+
4876+
4877+ /// \name Obsolete methods
4878+ //@{
4879+ /**
4880+ * \brief Set the thrust level for an engine group.
4881+ * \deprecated This method has been replaced by \ref VESSEL::SetThrusterGroupLevel.
4882+ * \param eng engine group identifier
4883+ * \param level thrust level [0..1]
4884+ * \sa SetThrusterGroupLevel, IncEngineLevel
4885+ */
4886+ void SetEngineLevel (ENGINETYPE eng, double level) const;
4887+
4888+ /**
4889+ * \brief Increase or decrease the thrust level for an engine group.
4890+ * \deprecated This method has been replaced by \ref VESSEL::IncThrusterGroupLevel.
4891+ * \param eng engine group identifier
4892+ * \param dlevel thrust increment
4893+ * \note Use negative dlevel to decrease the engine's thrust level.
4894+ * \note Levels are clipped to valid range.
4895+ * \sa IncThrusterGroupLevel, SetEngineLevel
4896+ */
4897+ void IncEngineLevel (ENGINETYPE eng, double dlevel) const;
4898+
4899+ double GetMaxThrust (ENGINETYPE eng) const;
4900+ void SetMaxThrust (ENGINETYPE eng, double th) const;
4901+ double GetEngineLevel (ENGINETYPE eng) const;
4902+ double *GetMainThrustModPtr () const;
4903+
4904+ /**
4905+ * \deprecated This method no longer performs any action.
4906+ * It has been replaced by the VESSEL::AddExhaust methods.
4907+ * \sa AddExhaust(THRUSTER_HANDLE,double,double,SURFHANDLE)const,
4908+ * AddExhaust(THRUSTER_HANDLE,double,double,double,SURFHANDLE)const,
4909+ * AddExhaust(THRUSTER_HANDLE,double,double,const VECTOR3&,const VECTOR3&,SURFHANDLE)const
4910+ */
4911+ void SetExhaustScales (EXHAUSTTYPE exh, WORD id, double lscale, double wscale) const;
4912+
4913+ /**
4914+ * \brief Delete a thruster group and (optionally) all associated thrusters.
4915+ * \deprecated This method has been replaced by VESSEL::DelThrusterGroup(THGROUP_HANDLE,bool)const.
4916+ * \param thg thruster group handle (NULL on return)
4917+ * \param thgt thruster group type (see \ref thrusterparam)
4918+ * \param delth thruster destruction flag (see notes)
4919+ * \return \e true on success.
4920+ * \note If \a delth==true, all thrusters associated with the group will be
4921+ * destroyed. Note that this can have side effects if the thrusters were
4922+ * associated with multiple groups, since they are removed from all those
4923+ * groups as well.
4924+ * \sa DelThrusterGroup(THGROUP_TYPE,bool)const, CreateThrusterGroup,
4925+ * DelThruster, thrusterparam
4926+ */
4927+ bool DelThrusterGroup (THGROUP_HANDLE &thg, THGROUP_TYPE thgt, bool delth = false) const;
4928+
4929+ UINT AddExhaustRef (EXHAUSTTYPE exh, VECTOR3 &pos, double lscale = -1.0, double wscale = -1.0, VECTOR3 *dir = 0) const; // obsolete
4930+ void DelExhaustRef (EXHAUSTTYPE exh, WORD id) const; // obsolete
4931+ void ClearExhaustRefs (void) const; // obsolete
4932+ UINT AddAttExhaustRef (const VECTOR3 &pos, const VECTOR3 &dir, double wscale = 1.0, double lscale = 1.0) const; // obsolete
4933+ void AddAttExhaustMode (UINT idx, ATTITUDEMODE mode, int axis, int dir) const; // obsolete
4934+ void ClearAttExhaustRefs (void) const; // obsolete
4935+
4936+ /**
4937+ * \brief Returns the scaling factor for the yaw moment.
4938+ * \deprecated This method has been replaced by VESSEL::GetYawMomentScale.
4939+ * \return yaw moment scale factor
4940+ * \note The method is misnamed. It refers to the vessel's yaw moment.
4941+ * \sa GetYawMomentScale
4942+ */
4943+ double GetBankMomentScale () const;
4944+
4945+ /**
4946+ * \brief Sets the scaling factor for the yaw moment.
4947+ * \deprecated This method has been replaced by VESSEL::SetYawMomentScale.
4948+ * \param scale scale factor for slip angle moment.
4949+ * \note The method is misnamed. It refers to the vessel's yaw moment.
4950+ * \sa SetYawMomentScale
4951+ */
4952+ void SetBankMomentScale (double scale) const;
4953+
4954+ /**
4955+ * \brief Sets the channel of a NAV radio receiver.
4956+ * \deprecated This method has been replaced by VESSEL::SetNavChannel
4957+ * \param n receiver index (>= 0)
4958+ * \param ch channel (>= 0)
4959+ * \return \e false on error (index out of range), \e true otherwise
4960+ */
4961+ bool SetNavRecv (DWORD n, DWORD ch) const;
4962+
4963+ /**
4964+ * \brief Returns the current channel setting of a NAV radio receiver.
4965+ * \deprecated This method has been replaced by VESSEL::GetNavChannel
4966+ * \param n receiver index (>= 0)
4967+ * \return Receiver channel [0..639]. If index \a n is out of range, the
4968+ * return value is 0.
4969+ */
4970+ DWORD GetNavRecv (DWORD n) const;
4971+
4972+ /**
4973+ * \brief Set the altitude of the vessel's centre of gravity over ground level when
4974+ * landed.
4975+ * \param h elevation of the vessel's centre of gravity above the surface plane when
4976+ * landed [m].
4977+ * \deprecated This method is obsolete and should no longer be used. It has been replaced
4978+ * by \ref VESSEL::SetTouchdownPoints.
4979+ */
4980+ void SetCOG_elev (double h) const;
4981+
4982+ /**
4983+ * \brief Remove all mesh definitions for the vessel.
4984+ * \deprecated This version is obsolete and has been replaced by
4985+ * \ref VESSEL::ClearMeshes(bool)const .
4986+ * \note Equivalent to ClearMeshes(true). This method is only retained for
4987+ * backward compatibility, and may be removed in future versions.
4988+ * \sa ClearMeshes(bool)const
4989+ */
4990+ void ClearMeshes () const;
4991+
4992+ /**
4993+ * \brief Marks a mesh as visible from internal cockpit view.
4994+ * \param idx mesh index (>= 0)
4995+ * \param visible visibility flag
4996+ * \deprecated This method is obsolete and has been replaced by
4997+ * \ref VESSEL::SetMeshVisibilityMode.
4998+ * \note By default, a vessel is not rendered when the camera is in internal
4999+ * (cockpit) view. This function can be used to force rendering of some or
5000+ * all of the vessel's meshes.
5001+ * \sa SetMeshVisibilityMode
5002+ */
5003+ void SetMeshVisibleInternal (UINT idx, bool visible) const;
5004+
5005+ UINT RegisterAnimSequence (double defmeshstate) const; // obsolete
5006+ bool AddAnimComp (UINT seq, ANIMCOMP *comp); // obsolete
5007+ bool SetAnimState (UINT seq, double state); // obsolete
5008+
5009+ /**
5010+ * \brief Causes Orbiter to write default vessel parameters to a scenario file.
5011+ * \deprecated Use a call to the base class VESSEL2::clbkSaveState from within
5012+ * the overloaded callback function instead.
5013+ * \param scn scenario file handle
5014+ * \note This method saves the vessel's default state parameters (such as
5015+ * position, velocity, orientation, etc.) to a scenario file.
5016+ * \note This functionality is now included in the default implementation of
5017+ * VESSEL2::clbkSaveState. Therefore, vessel classes which overload this
5018+ * method to save custom vessel parameters should call the base class method
5019+ * to allow Orbiter to save the default vessel parameters.
5020+ * \sa VESSEL2::clbkSaveState
5021+ */
5022+ void SaveDefaultState (FILEHANDLE scn) const;
5023+
5024+ /**
5025+ * \brief Pass a line read from a scenario file to Orbiter for default
5026+ * processing.
5027+ * \deprecated This function is retained for backward compatibility only.
5028+ * New modules should overload the \ref VESSEL2::clbkLoadStateEx function and
5029+ * use \ref VESSEL::ParseScenarioLineEx for default state parsing.
5030+ * \param line line to be interpreted
5031+ * \param status state parameter set
5032+ * \sa ParseScenarioLineEx, VESSELSTATUS
5033+ */
5034+ void ParseScenarioLine (char *line, VESSELSTATUS *status) const;
5035+
5036+ /**
5037+ * \brief Vessel creation
5038+ * \deprecated This method has been replaced with \ref oapiCreateVessel
5039+ * and \ref oapiCreateVesselEx.
5040+ */
5041+ static OBJHANDLE Create (const char *name, const char *classname, const VESSELSTATUS &status);
5042+ //@}
5043+
5044+protected:
5045+ Vessel *vessel; ///< Orbiter internal vessel class
5046+ short flightmodel; ///< realism level
5047+ short version; ///< interface version
5048+};
5049+
5050+// ======================================================================
5051+// class VESSEL2
5052+// ======================================================================
5053+/**
5054+ * \brief Callback extensions to the VESSEL class
5055+ *
5056+ * The VESSEL2 class adds a variety of callback functions to the VESSEL
5057+ * interface (clbk*). These are called by Orbiter to notify the vessel
5058+ * about different types of events and allow it to react to them. The
5059+ * VESSEL2 class implements these as virtual functions which act as
5060+ * placeholders to be overwritten by derived classes whenever a non-default
5061+ * behaviour is required.
5062+ */
5063+// ======================================================================
5064+// NOTE: Do NOT add or remove methods to this class, or re-arrange the
5065+// order of the exisiting methods, to avoid breaking addons (incompatible
5066+// virtual tables)!
5067+// ======================================================================
5068+
5069+class OAPIFUNC VESSEL2: public VESSEL {
5070+public:
5071+ /**
5072+ * \brief Creates a VESSEL2 interface for a vessel object.
5073+ *
5074+ * An instance of a vessel class derived from VESSEL2 is typically
5075+ * called during the initialisation of a vessel module (during ovcInit)
5076+ * to create an interface to the vessel instance controlled by the
5077+ * module. However, a VESSEL2 instance for any existing vessel can be
5078+ * created by any module.
5079+ * \param hVessel vessel object handle
5080+ * \param fmodel requested level of realism (0=simple, 1=realistic)
5081+ * \note This function creates an interface to an \e existing vessel.
5082+ * It does not create a new vessel. New vessels are created with the
5083+ * oapiCreateVessel and oapiCreateVesselEx functions.
5084+ * \note The VESSEL2 interface instance created in ovcInit should be
5085+ * deleted in ovcExit.
5086+ * \sa oapiCreateVessel, oapiCreateVesselEx, ovcInit
5087+ */
5088+ VESSEL2 (OBJHANDLE hVessel, int fmodel=1);
5089+
5090+ // ===== Callback functions =====
5091+
5092+ /**
5093+ * \brief Initialisation of vessel capabilities
5094+ *
5095+ * Called after vessel creation, this function allows to set vessel
5096+ * class capabilities and parameters. This can include definition of
5097+ * physical properties (size, mass, docking ports, etc.), creation of
5098+ * propellant resources and engines, aerodynamic parameters, including
5099+ * airfoil definitions, lift and drag properties, or active control
5100+ * surfaces.
5101+ * \param cfg handle for the vessel class configuration file
5102+ * \default None.
5103+ * \note This function is called after the vessel has been created, but
5104+ * before its state is read from the scenario file. This means that
5105+ * its state (position, velocity, fuel level, etc.) is undefined at
5106+ * this point.
5107+ * \note Use this function to set vessel class capabilities, not vessel
5108+ * state parameters.
5109+ * \note Orbiter will scan the vessel class configuration file for generic
5110+ * parameters (like mass or size) after clbkSetClassCaps returns.
5111+ * This allows to override generic caps defined in the module by
5112+ * editing the configuration file.
5113+ * \note The configuration file handle is also passed to clbkSetClassCaps,
5114+ * to allow reading of vessel class-specific parameters from file.
5115+ */
5116+ virtual void clbkSetClassCaps (FILEHANDLE cfg);
5117+
5118+ /**
5119+ * \brief Called when the vessel needs to save its current status to a
5120+ * scenario file.
5121+ * \param scn scenario file handle
5122+ * \default Saves the generic vessel state parameters.
5123+ * \note clbkSaveState is called by Orbiter at the end of a simulation
5124+ * session while creating the save scenario for the current
5125+ * simulation state.
5126+ * \note This function only needs to be overloaded if the vessel must
5127+ * save nonstandard parameters.
5128+ * \note If clbkSaveState is overloaded, generic state parameters will only
5129+ * be written if the base class VESSEL2::clbkSaveState is called.
5130+ * \note To write custom parameters to the scenario file, use the
5131+ * oapiWriteLine function.
5132+ */
5133+ virtual void clbkSaveState (FILEHANDLE scn);
5134+
5135+ /**
5136+ * \brief Called when the vessel needs to load its initial state from a
5137+ * scenario file.
5138+ * \param scn scenario file handle
5139+ * \param status pointer to VESSELSTATUSx structure (x >= 2)
5140+ * \default Loads the generic vessel state parameters.
5141+ * \note This callback function allows to read custom vessel status
5142+ * parameters from a scenario file.
5143+ * \note The function should define a loop which parses lines from the
5144+ * scenario file via oapiReadScenario_nextline.
5145+ * \note You should not call the base class clbkLoadStateEx to parse
5146+ * generic parameters, because this will skip over any custom
5147+ * scenario entries. Instead, any lines which the module parser does
5148+ * not recognise should be forwarded to Orbiter's default scenario
5149+ * parser via VESSEL::ParseScenarioLineEx.
5150+ * \sa VESSELSTATUS2, ParseScenarioLineEx, oapiReadScenario_nextline
5151+ */
5152+ virtual void clbkLoadStateEx (FILEHANDLE scn, void *status);
5153+
5154+ /**
5155+ * \brief Set state parameters during vessel creation
5156+ * \param status pointer to a VESSELSTATUSx structure
5157+ * \default Invokes Orbiter's default state initialisation.
5158+ * \par Calling sequence:
5159+ * This function is called when the vessel is being created with
5160+ * oapiCreateVesselEx, after its clbkSetClassCaps has been invoked and
5161+ * before its clbkPostCreation method is invoked. Vessels that are
5162+ * created during simulation start as a result of parsing the scenario
5163+ * file invoke clbkLoadStateEx instead.
5164+ * \note This callback function receives the VESSELSTATUSx structure
5165+ * passed to oapiCreateVesselEx. It must therefore be able to process
5166+ * the interface version used by those functions.
5167+ * \note This function remains valid even if future versions of Orbiter
5168+ * introduce new VESSELSTATUSx interfaces.
5169+ * \note If an overloaded method does not call VESSEL2::clbkSetStateEx,
5170+ * no default state initialisation is performed. Default state
5171+ * initialisation can also be done by calling VESSEL::DefSetStateEx.
5172+ */
5173+ virtual void clbkSetStateEx (const void *status);
5174+
5175+ /**
5176+ * \brief Called after a vessel has been created and its state has been
5177+ * set.
5178+ * \default None.
5179+ * \par Calling sequence:
5180+ * This function is called during vessel creation after clbkSetStateEx
5181+ * or clbkLoadStateEx have been called and before the vessel enters the
5182+ * update loop, i.e. before its clbkPreStep is invoked for the first
5183+ * time.
5184+ * Vessels that are created at the start of the simulation (i.e. are
5185+ * listed in the scenario) call their clbkPostCreation after all
5186+ * scenario vessels have been created.
5187+ * \note This function can be used to perform the final setup steps for
5188+ * the vessel, such as animation states and instrument panel states.
5189+ * When this function is called, the vessel state (e.g. position,
5190+ * thruster levels, etc.) have been defined.
5191+ */
5192+ virtual void clbkPostCreation ();
5193+
5194+ /**
5195+ * \brief Called after a vessel gained or lost input focus.
5196+ * \param getfocus true if the vessel gained focus, false if it lost focus
5197+ * \param hNewVessel handle of vessel gaining focus
5198+ * \param hOldVessel handle of vessel losing focus
5199+ * \default None.
5200+ * \note Whenever the input focus is switched to a new vessel (e.g. via
5201+ * user selection F3), this method is called for both the vessel
5202+ * losing focus (getfocus=false) and the vessel gaining focus
5203+ * (getfocus=true).
5204+ * \note In both calls, hNewVessel and hOldVessel are the vessel handles
5205+ * for the vessel gaining and the vessel losing focus, respectively.
5206+ * \note This method is also called at the beginning of the simulation for
5207+ * the initial focus object. In this case hOldVessel is NULL.
5208+ */
5209+ virtual void clbkFocusChanged (bool getfocus, OBJHANDLE hNewVessel, OBJHANDLE hOldVessel);
5210+
5211+ /**
5212+ * \brief Time step notification before state update.
5213+ *
5214+ * Called at each simulation time step before the state is updated to
5215+ * the current simulation time. This function allows to define actions
5216+ * which need to be controlled continuously.
5217+ * \param simt next simulation run time [s]
5218+ * \param simdt step length over which the current state will be
5219+ * integrated [s]
5220+ * \param mjd next absolute simulation time (days) in Modified Julian
5221+ * Date format
5222+ * \default None
5223+ * \note This function is called at each frame of the simulation, after the
5224+ * integration step length has been determined, but before the time
5225+ * integration is applied to the current simulation state.
5226+ * \note This method is useful when the step length Dt is required in
5227+ * advance of the time integration, for example to apply a force that
5228+ * produces a given Dv, since the AddForce request will be applied in
5229+ * the next update. Using clbkPostStep for this purpose would be
5230+ * wrong, because its Dt parameter refers to the previous step length.
5231+ * \sa clbkPostStep
5232+ */
5233+ virtual void clbkPreStep (double simt, double simdt, double mjd);
5234+
5235+ /**
5236+ * \brief Time step notification after state update
5237+ *
5238+ * Called at each simulation time step after the state has been updated
5239+ * to the current simulation time. This function allows to define
5240+ * actions which need to be controlled continuously.
5241+ * \param simt current simulation run time [s]
5242+ * \param simdt last time step length [s]
5243+ * \param mjd absolute simulation time (days) in Modified Julian Date
5244+ * format.
5245+ * \default None.
5246+ * \note This function, if implemented, is called at each frame for each
5247+ * instance of this vessel class, and is therefore time-critical.
5248+ * Avoid any unnecessary calculations here which may degrade
5249+ * performance.
5250+ * \sa clbkPreStep
5251+ */
5252+ virtual void clbkPostStep (double simt, double simdt, double mjd);
5253+
5254+ /**
5255+ * \brief Playback event notification
5256+ *
5257+ * Called during playback of a recording session when a custom event
5258+ * tag in the vessel's articulation stream is encountered.
5259+ * \param simt current simulation time [s]
5260+ * \param event_t recorded event time [s]
5261+ * \param event_type event tag string
5262+ * \param event event data string
5263+ * \return Should return true if the event type is recognised and
5264+ * processed, false otherwise.
5265+ * \default Do nothing, return false.
5266+ * \note This function can be used to process any custom vessel events that
5267+ * have been recorded with VESSEL::RecordEvent during a recording
5268+ * session.
5269+ */
5270+ virtual bool clbkPlaybackEvent (double simt, double event_t, const char *event_type, const char *event);
5271+
5272+ /**
5273+ * \brief Called after a vessel visual has been created by the renderer.
5274+ * \param vis handle for the newly created visual
5275+ * \param refcount visual reference count
5276+ * \default None.
5277+ * \note The logical interface to a vessel exists as long as the vessel is
5278+ * present in the simulation. However, the visual interface exists
5279+ * only when the vessel is within visual range of the camera. Orbiter
5280+ * creates and destroys visuals as required. This enhances simulation
5281+ * performance in the presence of a large number of objects in the
5282+ * simulation.
5283+ * \note Whenever Orbiter creates a vessel's visual it reverts to its
5284+ * initial configuration (e.g. as defined in the mesh file). The
5285+ * module can use this function to update the visual to the current
5286+ * state, wherever dynamic changes are required.
5287+ * \note More than one visual representation of an object may exist. The
5288+ * refcount parameter defines how many visual interfaces to the
5289+ * object exist.
5290+ */
5291+ virtual void clbkVisualCreated (VISHANDLE vis, int refcount);
5292+
5293+ /**
5294+ * \brief Called before a vessel visual is destroyed.
5295+ * \param vis handle for the visual to be destroyed
5296+ * \param refcount visual reference count
5297+ * \default None.
5298+ * \note Orbiter calls this function before it destroys a visual
5299+ * representation of the vessel. This may be in response to the
5300+ * destruction of the actual vessel, but in general simply means that
5301+ * the vessel has moved out of visual range of the current camera
5302+ * location.
5303+ */
5304+ virtual void clbkVisualDestroyed (VISHANDLE vis, int refcount);
5305+
5306+ /**
5307+ * \brief HUD redraw notification
5308+ *
5309+ * Called when the vessel's head-up display (HUD) needs to be redrawn
5310+ * (usually at each time step, unless the HUD is turned off).
5311+ * Overwriting this function allows to implement vessel-specific
5312+ * modifications of the HUD display (or to suppress the HUD altogether).
5313+ * \param mode HUD mode (see HUD_* constants in OrbiterAPI.h)
5314+ * \param hps pointer to a HUDPAINTSPEC structure
5315+ * \param hDC GDI drawing device context
5316+ * \default Draws a standard HUD display with Orbiter's default display
5317+ * layout.
5318+ * \deprecated This method contains a device-dependent drawing context and
5319+ * may not work with all graphics clients. It has been superseded by
5320+ * VESSEL3::clbkDrawHUD.
5321+ * \note For vessels derived from VESSEL3 orbiter will not call this method,
5322+ * but will call the VESSEL3::clbkDrawHUD method instead. The VESSEL3
5323+ * version uses a generic \e Sketchpad drawing context instead of a HDC.
5324+ * \sa VESSEL3::clbkDrawHUD
5325+ */
5326+ virtual void clbkDrawHUD (int mode, const HUDPAINTSPEC *hps, HDC hDC);
5327+
5328+ /**
5329+ * \brief Reaction Control System mode change notification.
5330+ *
5331+ * Called when a vessel's RCS (reaction control system) mode changes.
5332+ * Usually the RCS consists of a set of small thrusters arranged so as
5333+ * to allow controlled attitude changes. In Orbiter, the RCS can be
5334+ * driven in either rotational mode (to change the vessel's angular
5335+ * velocity) or in linear mode (to change its linear velocity), or be
5336+ * switched off.
5337+ * \param mode new RCS mode: 0=disabled, 1=rotational, 2=linear
5338+ * \default None.
5339+ * \note This callback function is invoked when the user switches RCS mode
5340+ * via the keyboard ("/" or "Ctrl-/" on numerical keypad) or after a
5341+ * call to VESSEL::SetAttitudeMode or VESSEL::ToggleAttitudeMode.
5342+ * \note Not all vessel types may support a reaction control system. In
5343+ * that case, the callback function can be ignored by the module.
5344+ */
5345+ virtual void clbkRCSMode (int mode);
5346+
5347+ /**
5348+ * \brief Aerodynamic control surface mode change notification.
5349+ *
5350+ * Called when user input mode for aerodynamic control surfaces
5351+ * (elevator, rudder, aileron) changes.
5352+ * \param mode control mode
5353+ * \default None.
5354+ * \note The returned control mode contains bit flags as follows:
5355+ * - bit 0: elevator enabled/disabled
5356+ * - bit 1: rudder enabled/disabled
5357+ * - bit 2: ailerons enabled/disabled
5358+ * .
5359+ * Therefore, mode=0 indicates control surfaces disabled, mode=7
5360+ * indicates fully enabled.
5361+ */
5362+ virtual void clbkADCtrlMode (DWORD mode);
5363+
5364+ /**
5365+ * \brief HUD mode change notification
5366+ *
5367+ * Called after a change of the vessel's HUD (head-up-display) mode.
5368+ * \param mode new HUD mode
5369+ * \default None.
5370+ * \note For currently supported HUD modes see HUD_* constants in
5371+ * OrbiterAPI.h
5372+ * \note mode HUD_NONE indicates that the HUD has been turned off.
5373+ * \sa Section hudmode for a list of default mode identifiers.
5374+ */
5375+ virtual void clbkHUDMode (int mode);
5376+
5377+ /**
5378+ * \brief MFD mode change modification
5379+ *
5380+ * Called when the user has switched one of the MFD (multi-functional
5381+ * display) instruments to a different display mode.
5382+ * \param mfd MFD instrument identifier
5383+ * \param mode new MFD mode identifier
5384+ * \default None.
5385+ * \note This callback function can be used to refresh the MFD button
5386+ * labels after the MFD mode has changed, or if a mode requires a
5387+ * dynamic label update.
5388+ * \note The mode parameter can be one of the MFD mode identifiers
5389+ * MFD_* listed in OrbiterAPI.h, or MFD_REFRESHBUTTONS. The latter
5390+ * is sent as a result of a call to oapiRefreshMFDButtons. It
5391+ * indicates not a mode change, but the need to refresh the button
5392+ * labels within a mode (i.e. a mode that dynamically changed its
5393+ * labels).
5394+ * \sa Section mfdmode for a list of default mode identifiers.
5395+ */
5396+ virtual void clbkMFDMode (int mfd, int mode);
5397+
5398+ /**
5399+ * \brief Navigation mode change notification
5400+ *
5401+ * Called when an automated "navigation mode" is activated or
5402+ * deactivated for a vessel. Most navigation modes engage the vessel's
5403+ * RCS to attain a specific attitude, including pro/retrograde, normal
5404+ * to the orbital plane, level with the local horizon, etc.
5405+ * \param mode navmode identifier
5406+ * \param active true if activated, false if deactivated
5407+ * \default None.
5408+ * \sa Section navmode for a list of available navigation modes.
5409+ */
5410+ virtual void clbkNavMode (int mode, bool active);
5411+
5412+ /**
5413+ * \brief Docking event notification
5414+ *
5415+ * Called after a docking or undocking event at one of the vessel's
5416+ * docking ports.
5417+ * \param dock docking port index
5418+ * \param mate handle to docked vessel, or NULL for undocking event
5419+ * \default None.
5420+ * \note dock is the index (>= 0) of the vessel's docking port at which
5421+ * the docking/undocking event takes place.
5422+ * \note mate is a handle to the vessel docking at the port, or NULL to
5423+ * indicate an undocking event.
5424+ */
5425+ virtual void clbkDockEvent (int dock, OBJHANDLE mate);
5426+
5427+ /**
5428+ * \brief Manual animation notification
5429+ *
5430+ * Called at each simulation time step if the module has registered at
5431+ * least one animation notification request and if the vessel's visual
5432+ * exists.
5433+ * \param simt simulation time [s]
5434+ * \default None.
5435+ * \note This callback allows the module to animate the vessel's visual
5436+ * representation (moving undercarriage, cargo bay doors, etc.)
5437+ * \note It is only called as long as the vessel has registered an
5438+ * animation request (between matching VESSEL::RegisterAnimation and
5439+ * VESSEL::UnregisterAnimation calls) and if the vessel's visual
5440+ * exists.
5441+ * \note This callback is \e not used for the "semi-automatic"
5442+ * animation mechanism (VESSEL::CreateAnimation,
5443+ * VESSEL::AddAnimationComponent)
5444+ * \sa VESSEL::RegisterAnimation, VESSEL::UnregisterAnimation,
5445+ * VESSEL::CreateAnimation, VESSEL::AddAnimationComponent
5446+ */
5447+ virtual void clbkAnimate (double simt);
5448+
5449+ /**
5450+ * \brief Keyboard status notification
5451+ *
5452+ * Called at each simulation time step to allow the module to
5453+ * query the current keyboard status. This callback can be used to
5454+ * install a custom keyboard interface for the vessel.
5455+ * \param kstate keyboard state
5456+ * \return A nonzero return value will completely disable default
5457+ * processing of the key state for the current time step. To disable
5458+ * the default processing of selected keys only, use the RESETKEY
5459+ * macro (see OrbiterAPI.h) and return 0.
5460+ * \default None, returns 0.
5461+ * \note The keystate contains the current keyboard state. Use the
5462+ * KEYDOWN macro in combination with the key identifiers as defined
5463+ * in OrbiterAPI.h (OAPI_KEY_*) to check for particular keys being
5464+ * pressed. Example:
5465+ * \code
5466+ * if (KEYDOWN (kstate, OAPI_KEY_F10)) {
5467+ * // perform action
5468+ * RESETKEY (kstate, OAPI_KEY_F10);
5469+ * // optional: prevent default processing of the key
5470+ * }
5471+ * \endcode
5472+ * \note This function should be used where a key state, rather than a
5473+ * key event is required, for example when engaging thrusters or
5474+ * similar. To test for key events (key pressed, key released) use
5475+ * clbkConsumeBufferedKey() instead.
5476+ */
5477+ virtual int clbkConsumeDirectKey (char *kstate);
5478+
5479+ /**
5480+ * \brief Keyboard event notification
5481+ *
5482+ * This callback function notifies the vessel of a buffered key event
5483+ * (key pressed or key released).
5484+ * \param key key scan code (see OAPI_KEY_* constants in OrbiterAPI.h)
5485+ * \param down true if key was pressed, false if key was released
5486+ * \param kstate current keyboard state
5487+ * \return The function should return 1 if Orbiter's default processing
5488+ * of the key event should be skipped, 0 otherwise.
5489+ * \default None, returns 0.
5490+ * \note The key state (kstate) can be used to test for key modifiers
5491+ * (Shift, Ctrl, etc.). The KEYMOD_xxx macros defined in OrbiterAPI.h
5492+ * are useful for this purpose.
5493+ * \note This function may be called repeatedly during a single frame,
5494+ * if multiple key events have occurred in the last time step.
5495+ */
5496+ virtual int clbkConsumeBufferedKey (DWORD key, bool down, char *kstate);
5497+
5498+ /**
5499+ * \brief Generic cockpit view mode request notification
5500+ *
5501+ * Called when the vessel's generic "glass cockpit" view (consisting of
5502+ * two "floating" MFD instruments and a HUD, displayed on top of the
5503+ * 3-D render window) is selected by the user pressing F8, or by a
5504+ * function call.
5505+ * \return The function should return true if it supports generic
5506+ * cockpit view, false otherwise.
5507+ * \default Sets camera direction to "forward" (0,0,1) and returns true.
5508+ * \note The generic cockpit view is available for all vessel types by
5509+ * default, unless this function is overwritten to return false.
5510+ * \note Only disable the generic view if the vessel supports either
5511+ * 2-D instrument panels (see clbkLoadPanel) or a virtual cockpit
5512+ * (see clbkLoadVC). If no valid cockpit view at all is available for
5513+ * a vessel, Orbiter will crash.
5514+ * \note Even if the vessel supports panels or virtual cockpits, you
5515+ * shouldn't normally disable the generic view, because it provides
5516+ * the best performance on slower computers.
5517+ * \sa clbkLoadPanel, clbkLoadVC
5518+ */
5519+ virtual bool clbkLoadGenericCockpit ();
5520+
5521+ /**
5522+ * \brief 2-D instrument panel view mode request notification
5523+ *
5524+ * Called when Orbiter tries to switch the cockpit view to a 2-D
5525+ * instrument panel.
5526+ * \param id panel identifier (>= 0)
5527+ * \return The function should return true if it supports the requested
5528+ * panel, false otherwise.
5529+ * \default None, returns false.
5530+ * \note In the body of this function the module should define the
5531+ * panel background bitmap and panel capabilities, e.g. the position
5532+ * of MFDs and other instruments, active areas (mouse hotspots) etc.
5533+ * \note A vessel which implements panels must at least support panel
5534+ * id 0 (the main panel). If any panels register neighbour panels
5535+ * (see oapiSetPanelNeighbours), all the neighbours must be
5536+ * supported, too.
5537+ * \sa oapiRegisterPanelBackground, oapiRegisterPanelArea,
5538+ * oapiRegisterMFD, clbkLoadGenericCockpit, clbkLoadVC
5539+ */
5540+ virtual bool clbkLoadPanel (int id);
5541+
5542+ /**
5543+ * \brief Mouse event notification for 2-D panel views.
5544+ *
5545+ * Called when a mouse-activated panel area receives a mouse event.
5546+ * \param id panel area identifier
5547+ * \param event mouse event (see \ref panel_mouse)
5548+ * \param mx,my relative mouse position in area at event
5549+ * \return The function should return true if it processes the event,
5550+ * false otherwise.
5551+ * \default None, returns false.
5552+ * \note Mouse events are only sent for areas which requested
5553+ * notification during definition (see oapiRegisterPanelArea).
5554+ */
5555+ virtual bool clbkPanelMouseEvent (int id, int event, int mx, int my);
5556+
5557+ /**
5558+ * \brief Redraw event notification for 2-D panel views.
5559+ *
5560+ * Called when a registered panel area needs to be redrawn.
5561+ * \param id panel area identifier
5562+ * \param event redraw event (see \ref panel_redraw)
5563+ * \param surf area surface handle
5564+ * \return The function should return true if it processes the event,
5565+ * false otherwise.
5566+ * \default None, returns false.
5567+ * \note This callback function is only called for areas which were
5568+ * not registered with the PANEL_REDRAW_NEVER flag.
5569+ * \note All redrawable panel areas receive a PANEL_REDRAW_INIT redraw
5570+ * notification when the panel is created, in addition to any
5571+ * registered redraw notification events.
5572+ * \note The surface handle surf contains either the current area
5573+ * state, or the area background, depending on the flags passed
5574+ * during area registration.
5575+ * \note The surface handle may be used for blitting operations, or to
5576+ * receive a Windows device context (DC) for Windows-style redrawing
5577+ * operations.
5578+ * \sa oapiGetDC, oapiReleaseDC, oapiTriggerPanelRedrawArea
5579+ */
5580+ virtual bool clbkPanelRedrawEvent (int id, int event, SURFHANDLE surf);
5581+
5582+ /**
5583+ * \brief 3-D virtual cockpit view mode request notification
5584+ *
5585+ * Called when Orbiter tries to switch the cockpit view to a 3-D
5586+ * virtual cockpit mode (for example in response to the user switching
5587+ * cockpit modes with F8).
5588+ * \param id virtual cockpit identifier (>= 0)
5589+ * \return true if the vessel supports the requested virtual cockpit,
5590+ * false otherwise.
5591+ * \default None, returning false (i.e. virtual cockpit mode not
5592+ * supported).
5593+ * \note Multiple virtual cockpit camera positions (e.g. for pilot and
5594+ * co-pilot) can be defined. In this case, the body of clbkLoadVC
5595+ * should examine the value of id and set the VC parameters
5596+ * accordingly. Multiple positions are defined by specifying the
5597+ * neighbour positions of the current position via a call to
5598+ * oapiVCSetNeighbours.
5599+ * \note In the body of this function the module should define MFD
5600+ * display targets (with oapiVCRegisterMFD) and other active areas
5601+ * (with oapiVCRegisterArea) for the requested virtual cockpit.
5602+ * \sa clbkLoadGenericCockpit, clbkLoadPanel, oapiVCSetNeighbours,
5603+ * oapiVCRegisterArea
5604+ */
5605+ virtual bool clbkLoadVC (int id);
5606+
5607+ /**
5608+ * \brief Mouse event notification for 3-D virtual cockpit views.
5609+ *
5610+ * Called when a mouse-activated virtual cockpit area receives a mouse
5611+ * event.
5612+ * \param id area identifier
5613+ * \param event mouse event (see \ref panel_mouse)
5614+ * \param p parameter vector (area type-dependent, see notes)
5615+ * \return The function should return true if it processes the event,
5616+ * false otherwise.
5617+ * \default None, returning false.
5618+ * \note To generate a mouse-activated area in a virtual cockpit, you
5619+ * must do the following when registering the area during clbkLoadVC:
5620+ * - register the area with a call to oapiVCRegisterArea with a
5621+ * mouse mode other than PANEL_MOUSE_IGNORE.
5622+ * - define a mouse-click area in the vessel's local frame. Use one
5623+ * of the oapiVCRegisterAreaClickmode_XXX functions. You can define
5624+ * spherical or quadrilateral click areas.
5625+ * \note Parameter p returns information about the mouse position at
5626+ * the mouse event. The type of information returned depends on the
5627+ * area type for which the event was generated:
5628+ * - spherical area:
5629+ * - p.x is distance of mouse event from area centre
5630+ * - p.y and p.z not used
5631+ * - quadrilateral area:
5632+ * - p.x and p.y are the area-relative mouse x and y positions (top
5633+ * left = (0,0), bottom right = (1,1)
5634+ * - p.z not used
5635+ * \sa clbkLoadVC, clbkPanelMouseEvent, oapiVCRegisterArea
5636+ */
5637+ virtual bool clbkVCMouseEvent (int id, int event, VECTOR3 &p);
5638+
5639+ /**
5640+ * \brief Redraw event notification for 3-D virtual cockpit views.
5641+ *
5642+ * Called when a registered virtual cockpit area needs to be redrawn.
5643+ * \param id area identifier
5644+ * \param event redraw event (see \ref panel_redraw)
5645+ * \param surf associated texture handle
5646+ * \return The function should return true if it processes the event,
5647+ * false otherwise.
5648+ * \default None, returning false.
5649+ * \note To allow an area of the virtual cockpit to be redrawn
5650+ * dynamically, the area must be registered with oapiVCRegisterArea
5651+ * during clbkLoadVC, using a redraw mode other than
5652+ * PANEL_REDRAW_NEVER.
5653+ * \note When registering the area with oapiVCRegisterArea, you must
5654+ * also provide a handle to the texture onto which the redrawn
5655+ * surface is mapped. This texture must be part of the virtual
5656+ * cockpit mesh, and it must be listed in the mesh file with the 'D'
5657+ * ("dynamic") flag (see 3DModel.pdf).
5658+ * \note "Redrawing" an area is not limited to dynamically updating
5659+ * textures. It may also involve mesh transforms (e.g. to animate
5660+ * levers and switches rendered in 3D).
5661+ */
5662+ virtual bool clbkVCRedrawEvent (int id, int event, SURFHANDLE surf);
5663+};
5664+
5665+// ======================================================================
5666+// class VESSEL3
5667+// ======================================================================
5668+/**
5669+ * \brief Callback extensions to the VESSEL class
5670+ *
5671+ * The VESSEL3 class extends VESSEL2 with additional functionality.
5672+ * Developers should use this class for new projects. Existing vessel
5673+ * addons can make use of the new features by switching the base
5674+ * class from VESSEL2 to VESSEL3.
5675+ */
5676+// ======================================================================
5677+// NOTE: Do NOT add or remove methods to this class, or re-arrange the
5678+// order of the exisiting methods, to avoid breaking addons (incompatible
5679+// virtual tables)!
5680+// ======================================================================
5681+
5682+class OAPIFUNC VESSEL3: public VESSEL2 {
5683+public:
5684+ /**
5685+ * \brief Creates a VESSEL3 interface for a vessel object.
5686+ * \sa VESSEL2
5687+ */
5688+ VESSEL3 (OBJHANDLE hVessel, int fmodel=1);
5689+
5690+ /**
5691+ * \brief Set the background surface for a 2-D instrument panel.
5692+ * \param hPanel panel handle
5693+ * \param hSurf array of surface handles
5694+ * \param nsurf number of surfaces
5695+ * \param hMesh mesh handle defining the billboard geometry
5696+ * \param width panel width [pixel]
5697+ * \param height panel height [pixel]
5698+ * \param baseline base line for edge attachment
5699+ * \param scrollflag panel attachment and scrolling bitflags
5700+ * \return Always returns 0.
5701+ * \note This method should be applied in the body of \ref clbkLoadPanel2D.
5702+ * \note The mesh defines the size and layout of the billboard mesh used for
5703+ * rendering the panel surface. Its vertex coordinates are interpreted as
5704+ * transformed, i.e. in terms of screen coordinates (pixels). The z-coordinate
5705+ * should be zero. Normals are ignored. Texture coordinates define which part
5706+ * of the surfaces are rendered.
5707+ * \note The groups are rendered in the order they appear in the mesh. Later
5708+ * groups cover earlier ones. Therefore the groups should be arranged from
5709+ * backmost to frontmost elements.
5710+ * \note In the simplest case, the mesh consists of a single rectangular area
5711+ * (4 nodes, 2 triangles) and a single surface, but can be more elaborate.
5712+ * \note The texture indices of the mesh groups (TexIdx) are interpreted as
5713+ * indices into the hSurf list (zero-based).
5714+ * \note This method increases the reference counters for the surfaces, so the
5715+ * caller should release them at some point.
5716+ * \note The surfaces can contain an alpha channel to handle transparency.
5717+ */
5718+ int SetPanelBackground (PANELHANDLE hPanel, SURFHANDLE *hSurf, DWORD nsurf, MESHHANDLE hMesh, DWORD width, DWORD height, DWORD baseline = 0, DWORD scrollflag = 0);
5719+
5720+ /**
5721+ * \brief Set scaling factors for 2-D instrument panel.
5722+ * \param hPanel panel handle
5723+ * \param defscale default scale factor
5724+ * \param extscale additional scale factor
5725+ * \return Always returns 0.
5726+ * \note The scaling factors define the scaling between mesh coordinates
5727+ * and screen pixels.
5728+ * \note \a defscale is the default factor, \a extscale is an additional scale
5729+ * which can be selected by the user via the mouse wheel.
5730+ * \note Examples: scale=1: one mesh unit corresponds to one screen pixel,
5731+ * scale=viewW/panelW: panel fits screen width
5732+ */
5733+ int SetPanelScaling (PANELHANDLE hPanel, double defscale, double extscale);
5734+
5735+ /**
5736+ * \brief Define an MFD display in the panel mesh.
5737+ * \param hPanel panel handle
5738+ * \param MFD_id MFD identifier (>= 0)
5739+ * \param nmesh panel mesh index (>= 0)
5740+ * \param ngroup mesh group index (>= 0)
5741+ * \return Always returns 0.
5742+ * \note This method reserves a mesh group for rendering the contents of
5743+ * an MFD display. The group should define a square area (typically
5744+ * consisting of 4 nodes and 2 triangles) with appropriate texture
5745+ * coordinates. When rendering the panel, the texture for this group is
5746+ * set to the current contents of the MFD display.
5747+ * \note The order of mesh groups defines the rendering order. To render
5748+ * the MFD display on top of the panel, define it as the last group in
5749+ * the mesh. Alternatively, the MFD can be rendered first, if the panel
5750+ * texture contains a transparent area through which to view the MFD.
5751+ */
5752+ int RegisterPanelMFDGeometry (PANELHANDLE hPanel, int MFD_id, int nmesh, int ngroup);
5753+
5754+ /**
5755+ * \brief Register an area of the panel to receive mouse and redraw events.
5756+ * \param hPanel panel handle
5757+ * \param id area identifier
5758+ * \param pos area boundary coordinates (mesh coordinates)
5759+ * \param texpos area boundary (texture coordinates)
5760+ * \param draw_event event flags for redraw event triggers
5761+ * \param mouse_event event flags for mouse event triggers
5762+ * \param bkmode flag for texture background provided to redraw callback function
5763+ * \return Always returns 0.
5764+ * \note This method activates a rectangular area of the panel for receiving mouse
5765+ * and redraw events.
5766+ * \note \a pos specifies the borders of the area in 'logical' coordinates
5767+ * (0,0,width,height) as specified by \ref SetPanelBackground. Registered mouse
5768+ * events within this area will trigger a call to \ref VESSEL2::clbkPanelMouseEvent.
5769+ * \note If the area needs to update one of the panel textures, the texture handle
5770+ * should be passed in \a hTgt, and the affected area (in pixels) of the texture
5771+ * bitmap should be passed in \a texpos.
5772+ */
5773+ int RegisterPanelArea (PANELHANDLE hPanel, int id, const RECT &pos, const RECT &texpos, int draw_event, int mouse_event, int bkmode);
5774+
5775+ /**
5776+ * \brief Register an area of the panel to receive mouse and redraw events.
5777+ * \param hPanel panel handle
5778+ * \param id area identifier
5779+ * \param pos area boundary coordinates (mesh coordinates)
5780+ * \param draw_event event flags for redraw event triggers
5781+ * \param mouse_event event flags for mouse event triggers
5782+ * \param surf surface handle passed to the redraw callback function
5783+ * \param context user-defined data passed to the mouse and redraw callback functions
5784+ * \return Always returns 0.
5785+ * \note This version passes the provided surface handle directly to the redraw
5786+ * callback, rather making a copy of the area. This is useful if the area
5787+ * either doesn't need to modify any surfaces, or blits parts of the same
5788+ * surface (e.g. a texture that contains both the panel background and various
5789+ * elements (switches, dials, etc.) to be copied on top.
5790+ * \note Since the surface returned to the redraw function is not restricted to
5791+ * the registered area, it is the responsibility of the caller not to draw
5792+ * outside the area.
5793+ * \note The area boundaries defined in \a pos are only used for generating
5794+ * mouse events. If the area does not process mouse events (PANEL_MOUSE_IGNORE),
5795+ * the pos parameter is ignored.
5796+ */
5797+ int RegisterPanelArea (PANELHANDLE hPanel, int id, const RECT &pos, int draw_event, int mouse_event, SURFHANDLE surf = NULL, void *context = NULL);
5798+
5799+ /**
5800+ * \brief Mouse event notification for 2-D panel views.
5801+ *
5802+ * Called when a mouse-activated panel area receives a mouse event.
5803+ * \param id panel area identifier
5804+ * \param event mouse event (see \ref panel_mouse)
5805+ * \param mx,my relative mouse position in area at event
5806+ * \param context user-supplied pointer to context data (defined in \ref RegisterPanelArea)
5807+ * \return The function should return true if it processes the event,
5808+ * false otherwise.
5809+ * \default None, returns false.
5810+ * \note If a vessel class overloads this method, it should return true. On a
5811+ * \e false return, Orbiter will try VESSEL2::clbkPanelMouseEvent instead.
5812+ * \note Mouse events are only sent for areas which requested
5813+ * notification during definition (see RegisterPanelArea).
5814+ * \sa RegisterPanelArea
5815+ */
5816+ virtual bool clbkPanelMouseEvent (int id, int event, int mx, int my, void *context);
5817+
5818+ /**
5819+ * \brief Redraw event notification for 2-D panel views.
5820+ *
5821+ * Called when a registered panel area needs to be redrawn.
5822+ * \param id panel area identifier
5823+ * \param event redraw event (see \ref panel_redraw)
5824+ * \param surf area surface handle
5825+ * \param context user-supplied pointer to context data (defined in \ref RegisterPanelArea)
5826+ * \return The function should return true if it processes the event,
5827+ * false otherwise.
5828+ * \default None, returns false.
5829+ * \note This callback function is only called for areas which were
5830+ * not registered with the PANEL_REDRAW_NEVER flag.
5831+ * \note If a vessel class overloads this method, it should return true. On a
5832+ * \e false return, Orbiter will try VESSEL2::clbkPanelRedrawEvent instead.
5833+ * \note All redrawable panel areas receive a PANEL_REDRAW_INIT redraw
5834+ * notification when the panel is created, in addition to any
5835+ * registered redraw notification events.
5836+ * \note The surface handle surf contains either the current area
5837+ * state, or the area background, depending on the flags passed
5838+ * during area registration.
5839+ * \note The surface handle may be used for blitting operations, or to
5840+ * receive a Windows device context (DC) for Windows-style redrawing
5841+ * operations.
5842+ * \sa RegisterPanelArea, oapiGetDC, oapiReleaseDC, oapiTriggerPanelRedrawArea
5843+ */
5844+ virtual bool clbkPanelRedrawEvent (int id, int event, SURFHANDLE surf, void *context);
5845+
5846+ /**
5847+ * \brief Generic multi-purpose callback function.
5848+ * \param msgid message identifier (see \ref vmsg)
5849+ * \param prm message parameter
5850+ * \param context pointer to additional message data
5851+ * \return Result flag.
5852+ */
5853+ virtual int clbkGeneric (int msgid = 0, int prm = 0, void *context = NULL);
5854+
5855+ /**
5856+ * \brief Request for a 2D instrument panel definition in cockpit view.
5857+ * \param id panel identifier (>= 0)
5858+ * \param hPanel panel handle
5859+ * \param viewW viewport width [pixel]
5860+ * \param viewH viewport height [pixel]
5861+ * \return The function should return \e true if it supports the requested
5862+ * panel, false otherwise.
5863+ * \default None, returns false.
5864+ * \note This method replaces \ref VESSEL2::clbkLoadPanel. It defines the
5865+ * panels via SURFHANDLES instead of bitmaps.
5866+ */
5867+ virtual bool clbkLoadPanel2D (int id, PANELHANDLE hPanel, DWORD viewW, DWORD viewH);
5868+
5869+ /**
5870+ * \brief HUD redraw notification
5871+ *
5872+ * Called when the vessel's head-up display (HUD) needs to be redrawn
5873+ * (usually at each time step, unless the HUD is turned off).
5874+ * Overwriting this function allows to implement vessel-specific
5875+ * modifications of the HUD display (or to suppress the HUD altogether).
5876+ * \param mode HUD mode (see HUD_* constants in OrbiterAPI.h)
5877+ * \param hps pointer to a HUDPAINTSPEC structure (see notes)
5878+ * \param skp drawing context instance
5879+ * \return Overloaded methods should return \e true. If the return value
5880+ * is \e false, orbiter assumes that this method is disabled and will
5881+ * try VESSEL2::clbkDrawHUD.
5882+ * \default Draws a standard HUD display with Orbiter's default display
5883+ * layout and returns \e true.
5884+ * \note If a vessel overwrites this method, Orbiter will draw the
5885+ * default HUD only if the base class VESSEL3::clbkDrawHUD is called.
5886+ * \note hps points to a HUDPAINTSPEC structure containing information
5887+ * about the HUD drawing surface. It has the following format:
5888+ * \code
5889+ * typedef struct {
5890+ * int W, H;
5891+ * int CX, CY;
5892+ * double Scale;
5893+ * int Markersize;
5894+ * } HUDPAINTSPEC;
5895+ * \endcode
5896+ * where W and H are width and height of the HUD drawing surface in
5897+ * pixels, CX and CY are the x and y coordinates of the HUD centre
5898+ * (the position of the "forward marker", which is not guaranteed to
5899+ * be in the middle of the drawing surface or even within the drawing
5900+ * surface!), Scale represents an angular aperture of 1 deg. expressed in
5901+ * HUD pixels, and Markersize is a "typical" size which can be used
5902+ * to scale objects like direction markers.
5903+ * \note The device context passed to clbkDrawHUD contains the
5904+ * appropriate settings for the current HUD display (font, pen,
5905+ * colours). If you need to change any of the GDI settings, make sure
5906+ * to restore the defaults before calling the base class clbkDrawHUD.
5907+ * Otherwise the default display will be corrupted.
5908+ * \note clbkDrawHUD can be used to implement entirely new vessel-
5909+ * specific HUD modes. In this case, the module would maintain its
5910+ * own record of the current HUD mode, and ignore the mode parameter
5911+ * passed to clbkDrawHUD.
5912+ * \note In glass cockpit and 2-D panel mode, the HUD display can be a
5913+ * combination of drawn elements (via clbkDrawHUD) and rendered elements
5914+ * (via \ref clbkRenderHUD). In VC mode, the HUD is always drawn.
5915+ * \note To disable all default HUD display elements, a derived vessel
5916+ * should overload both clbkDrawHUD and clbkRenderHUD.
5917+ * \sa clbkRenderHUD, Section hudmode for a list of default mode identifiers.
5918+ */
5919+ virtual bool clbkDrawHUD (int mode, const HUDPAINTSPEC *hps, oapi::Sketchpad *skp);
5920+
5921+ /**
5922+ * \brief HUD render notification
5923+ *
5924+ * Called when the vessel's head-up display (HUD) needs to be rendered
5925+ * (usually at each time step, unless the HUD is turned off).
5926+ * Overwriting this function allows to implement vessel-specific
5927+ * modifications of the HUD display (or to suppress the HUD altogether).
5928+ * \param mode HUD mode (see HUD_* constants in OrbiterAPI.h)
5929+ * \param hps pointer to a HUDPAINTSPEC structure
5930+ * \param hDefaultTex handle for default HUD texture
5931+ * \default Renders a standard HUD display with Orbiter's default display
5932+ * layout.
5933+ * \note This function is only called in glass cockpit or 2-D panel mode,
5934+ * not in VC (virtual cockpit mode).
5935+ * \note In glass cockpit or 2-D panel mode, the programmer has a choice of
5936+ * using clbkRenderHUD or \ref clbkDrawHUD to display vessel-specific HUD
5937+ * elements. The use of clbkRenderHUD is preferred, because it provides
5938+ * smoother animation, better performance and is better supported by
5939+ * external render engines.
5940+ * \note To disable all default HUD display, a derived vessel class should
5941+ * overload both clbkRenderHUD and \ref clbkDrawHUD.
5942+ * \note To render custom HUD elements, the \ref oapiRenderHUD function should
5943+ * be called from within this callback function.
5944+ * \sa clbkDrawHUD, oapiRenderHUD, Section hudmode for a list of default mode identifiers.
5945+ */
5946+ virtual void clbkRenderHUD (int mode, const HUDPAINTSPEC *hps, SURFHANDLE hDefaultTex);
5947+
5948+ /**
5949+ * \brief Returns force due to radiation pressure.
5950+ * \param[in] mflux momentum flux vector [N/m^2] at current spacecraft position,
5951+ * transformed into vessel frame
5952+ * \param[out] F radiation force vector [<b>N</b>] in vessel frame
5953+ * \param[out] pos force attack point [<b>m</b>] in vessel frame
5954+ * \default Sets F = mflux * size^2 * a, where a (albedo coefficient) is fixed
5955+ * to 1.5. Sets pos = (0,0,0). This simple formula ignores any attitude-dependent
5956+ * variations in surface area, and any non-radial force components due to oblique
5957+ * reflections. Does not induce any torque. For more sophisticated treatment,
5958+ * vessels should re-implement this method.
5959+ * \note This method is called by orbiter when perturbation forces due to
5960+ * radiation pressure need to be evaluated. The implementation should take
5961+ * into account geometric factors (cross sections), surface factors (absorption,
5962+ * reflection) and spacecraft attitude relative to the sun.
5963+ * \note The momentum flux parameter, \a mflux, takes into account shadow
5964+ * effects from the closest planet, or from the closest moon and its parent
5965+ * planet, if applicable.
5966+ * \note If the returned force attack point \a pos is not set to the centre
5967+ * of gravity, (0,0,0), then a torque may be induced as well as a linear
5968+ * force.
5969+ * \note If the vessel contains multiple distinct surfaces, the returned
5970+ * force should be the vector sum of all individual contributions, and the
5971+ * returned position should be the weighted barycentre of all individual
5972+ * contributions w.r.t. the vessel centre of gravity.
5973+ */
5974+ virtual void clbkGetRadiationForce (const VECTOR3 &mflux, VECTOR3 &F, VECTOR3 &pos);
5975+};
5976+
5977+// ======================================================================
5978+// class AnimState
5979+// Auxiliary class for defining animation states
5980+// ======================================================================
5981+
5982+class AnimState {
5983+public:
5984+ enum Action {STOPPED, CLOSED, OPEN, CLOSING, OPENING} action;
5985+ double pos;
5986+ void Set (Action a, double p) { action = a, pos = p; }
5987+ bool Move (double dp) {
5988+ if (!Moving()) return false;
5989+ if (Closing()) {
5990+ if ((pos = max (0.0, pos-dp)) == 0.0) action = CLOSED;
5991+ } else {
5992+ if ((pos = min (1.0, pos+dp)) == 1.0) action = OPEN;
5993+ }
5994+ return true;
5995+ }
5996+ bool Moving() const { return action >= CLOSING; }
5997+ bool Static() const { return action < CLOSING; }
5998+ bool Stopped() const { return action == STOPPED; }
5999+ bool Closed() const { return action == CLOSED; }
6000+ bool Open() const { return action == OPEN; }
6001+ bool Closing() const { return action == CLOSING; }
6002+ bool Opening() const { return action == OPENING; }
6003+ friend OAPIFUNC void WriteScenario_state (FILEHANDLE f, char *tag, const AnimState &s);
6004+ friend OAPIFUNC void sscan_state (char *str, AnimState &s);
6005+};
6006+
6007+#endif // !__VESSELAPI_H
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/samples/Orbiter.NET/Orbiter.Interfaces/Orbiter.Interfaces.csproj
--- a/Orbitersdk/samples/Orbiter.NET/Orbiter.Interfaces/Orbiter.Interfaces.csproj Tue Nov 03 19:38:45 2009 +0100
+++ b/Orbitersdk/samples/Orbiter.NET/Orbiter.Interfaces/Orbiter.Interfaces.csproj Mon Feb 21 22:48:14 2011 +0100
@@ -1,4 +1,4 @@
1-<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
1+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="3.5">
22 <PropertyGroup>
33 <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
44 <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
@@ -13,6 +13,11 @@
1313 <AssemblyOriginatorKeyFile>
1414 </AssemblyOriginatorKeyFile>
1515 <DelaySign>false</DelaySign>
16+ <FileUpgradeFlags>
17+ </FileUpgradeFlags>
18+ <OldToolsVersion>2.0</OldToolsVersion>
19+ <UpgradeBackupLocation>
20+ </UpgradeBackupLocation>
1621 </PropertyGroup>
1722 <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
1823 <DebugSymbols>true</DebugSymbols>
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/samples/Orbiter.NET/Orbiter.Launcher/Orbiter.Launcher.vcproj
--- a/Orbitersdk/samples/Orbiter.NET/Orbiter.Launcher/Orbiter.Launcher.vcproj Tue Nov 03 19:38:45 2009 +0100
+++ b/Orbitersdk/samples/Orbiter.NET/Orbiter.Launcher/Orbiter.Launcher.vcproj Mon Feb 21 22:48:14 2011 +0100
@@ -1,10 +1,11 @@
11 <?xml version="1.0" encoding="Windows-1252"?>
22 <VisualStudioProject
33 ProjectType="Visual C++"
4- Version="8,00"
4+ Version="9,00"
55 Name="Orbiter.Launcher"
66 ProjectGUID="{81AAB3CF-6309-421E-9126-E4CB147DC3DD}"
77 RootNamespace="Orbiter.Launcher"
8+ TargetFrameworkVersion="131072"
89 >
910 <Platforms>
1011 <Platform
@@ -76,6 +77,8 @@
7677 SubSystem="2"
7778 EntryPointSymbol=""
7879 ResourceOnlyDLL="false"
80+ RandomizedBaseAddress="1"
81+ DataExecutionPrevention="0"
7982 ImportLibrary="..\..\..\lib\$(ProjectName).lib"
8083 TargetMachine="1"
8184 />
@@ -101,9 +104,6 @@
101104 Name="VCAppVerifierTool"
102105 />
103106 <Tool
104- Name="VCWebDeploymentTool"
105- />
106- <Tool
107107 Name="VCPostBuildEventTool"
108108 CommandLine=""
109109 />
@@ -113,10 +113,10 @@
113113 <AssemblyReference
114114 RelativePath="System.dll"
115115 AssemblyName="System, Version=2.0.0.0, PublicKeyToken=b77a5c561934e089, processorArchitecture=MSIL"
116+ MinFrameworkVersion="131072"
116117 />
117118 <ProjectReference
118119 ReferencedProjectIdentifier="{60302E15-B213-40EC-8A8D-7EFAFFFF262D}"
119- RelativePathToProject=".\Orbiter.Interfaces\Orbiter.Interfaces.csproj"
120120 />
121121 </References>
122122 <Files>
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/samples/Orbiter.NET/Orbiter.NET.sln
--- a/Orbitersdk/samples/Orbiter.NET/Orbiter.NET.sln Tue Nov 03 19:38:45 2009 +0100
+++ b/Orbitersdk/samples/Orbiter.NET/Orbiter.NET.sln Mon Feb 21 22:48:14 2011 +0100
@@ -1,6 +1,17 @@
11 
2-Microsoft Visual Studio Solution File, Format Version 9.00
3-# Visual Studio 2005
2+Microsoft Visual Studio Solution File, Format Version 10.00
3+# Visual Studio 2008
4+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Signatures", "Signatures", "{77127280-6566-41D0-ADC0-4394F7CFD582}"
5+ ProjectSection(SolutionItems) = preProject
6+ Orbiter.NET.snk = Orbiter.NET.snk
7+ EndProjectSection
8+EndProject
9+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Scripts", "Scripts", "{1561FD7B-C159-49E8-92E1-B9AC22B2E8C7}"
10+ ProjectSection(SolutionItems) = preProject
11+ SDKDeploy.bat = SDKDeploy.bat
12+ VesselDeploy.bat = VesselDeploy.bat
13+ EndProjectSection
14+EndProject
415 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "Orbiter.Wrapper", "Orbiter.Wrapper\Orbiter.Wrapper.vcproj", "{326F9CD9-06DC-4749-999C-CDCC8C50042A}"
516 EndProject
617 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Orbiter.Interfaces", "Orbiter.Interfaces\Orbiter.Interfaces.csproj", "{60302E15-B213-40EC-8A8D-7EFAFFFF262D}"
@@ -9,11 +20,6 @@
920 EndProject
1021 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "Orbiter.Launcher", "Orbiter.Launcher\Orbiter.Launcher.vcproj", "{81AAB3CF-6309-421E-9126-E4CB147DC3DD}"
1122 EndProject
12-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Signatures", "Signatures", "{77127280-6566-41D0-ADC0-4394F7CFD582}"
13- ProjectSection(SolutionItems) = preProject
14- Orbiter.NET.snk = Orbiter.NET.snk
15- EndProjectSection
16-EndProject
1723 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ShuttlePBdotNET", "ShuttlePBdotNET\ShuttlePBdotNET.csproj", "{141C7AC2-DAB6-4113-8622-5D19FA514521}"
1824 ProjectSection(ProjectDependencies) = postProject
1925 {81AAB3CF-6309-421E-9126-E4CB147DC3DD} = {81AAB3CF-6309-421E-9126-E4CB147DC3DD}
@@ -32,12 +38,6 @@
3238 {6C9A07FA-4EE5-4C73-A56B-9A19201F8635} = {6C9A07FA-4EE5-4C73-A56B-9A19201F8635}
3339 EndProjectSection
3440 EndProject
35-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Scripts", "Scripts", "{1561FD7B-C159-49E8-92E1-B9AC22B2E8C7}"
36- ProjectSection(SolutionItems) = preProject
37- SDKDeploy.bat = SDKDeploy.bat
38- VesselDeploy.bat = VesselDeploy.bat
39- EndProjectSection
40-EndProject
4141 Global
4242 GlobalSection(SolutionConfigurationPlatforms) = preSolution
4343 Debug|Any CPU = Debug|Any CPU
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/samples/Orbiter.NET/Orbiter.StockVessels/Orbiter.StockVessels.csproj
--- a/Orbitersdk/samples/Orbiter.NET/Orbiter.StockVessels/Orbiter.StockVessels.csproj Tue Nov 03 19:38:45 2009 +0100
+++ b/Orbitersdk/samples/Orbiter.NET/Orbiter.StockVessels/Orbiter.StockVessels.csproj Mon Feb 21 22:48:14 2011 +0100
@@ -1,4 +1,4 @@
1-<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
1+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="3.5">
22 <PropertyGroup>
33 <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
44 <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
@@ -12,6 +12,11 @@
1212 <SignAssembly>false</SignAssembly>
1313 <AssemblyOriginatorKeyFile>
1414 </AssemblyOriginatorKeyFile>
15+ <FileUpgradeFlags>
16+ </FileUpgradeFlags>
17+ <OldToolsVersion>2.0</OldToolsVersion>
18+ <UpgradeBackupLocation>
19+ </UpgradeBackupLocation>
1520 </PropertyGroup>
1621 <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
1722 <DebugSymbols>true</DebugSymbols>
diff -r e23423af0d94 -r 89b6657c2c11 Orbitersdk/samples/Orbiter.NET/Orbiter.Wrapper/Orbiter.Wrapper.vcproj
--- a/Orbitersdk/samples/Orbiter.NET/Orbiter.Wrapper/Orbiter.Wrapper.vcproj Tue Nov 03 19:38:45 2009 +0100
+++ b/Orbitersdk/samples/Orbiter.NET/Orbiter.Wrapper/Orbiter.Wrapper.vcproj Mon Feb 21 22:48:14 2011 +0100
@@ -1,10 +1,11 @@
11 <?xml version="1.0" encoding="Windows-1252"?>
22 <VisualStudioProject
33 ProjectType="Visual C++"
4- Version="8,00"
4+ Version="9,00"
55 Name="Orbiter.Wrapper"
66 ProjectGUID="{326F9CD9-06DC-4749-999C-CDCC8C50042A}"
77 RootNamespace="Orbiter.Wrapper"
8+ TargetFrameworkVersion="131072"
89 >
910 <Platforms>
1011 <Platform
@@ -42,7 +43,7 @@
4243 Optimization="0"
4344 InlineFunctionExpansion="1"
4445 AdditionalIncludeDirectories="..\..\..\include"
45- PreprocessorDefinitions="WIN32;DEBUG;_WINDOWS"
46+ PreprocessorDefinitions="WIN32;DEBUG;_WINDOWS; USESDOTNETWORKAROUNDS"
4647 GeneratePreprocessedFile="0"
4748 StringPooling="true"
4849 RuntimeLibrary="2"