Conversion of existing documentation to LaTeX sources

.gitignore

@@ -20,3 +20,7 @@ Sound/XRSound/**/Debug-with-OrbiterRelease/
 Sound/XRSound/**/Release-with-OrbiterRelease/
 
 Extern/irrKlang
+
+Doc/**/*.log
+Doc/**/*.pdf
+Doc/**/*.gz

Doc/Orbiter Developer Manual/CONFIG.tex

@@ -0,0 +1,25 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{Orbiter configuration files}
+% TODO
+
+\subsection{Main configuration file}
+% TODO
+
+\subsection{Planetary systems}
+% TODO
+
+\subsection{Planets}
+% TODO
+
+\subsection{Surface bases}
+% TODO
+
+\subsection{Custom markers}
+% TODO
+
+\subsection{Vessels}
+% TODO
+
+\end{document}

Doc/Orbiter Developer Manual/INTRODUCTION.tex

@@ -0,0 +1,7 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{Introduction}
+This document contains guidelines on developing new 3D models for spacecraft visualisation in ORBITER. It is aimed at addon developers, or anyone who wants to extend ORBITER’s functionality.
+
+\end{document}

Doc/Orbiter Developer Manual/KEYMAP.tex

@@ -0,0 +1,8 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{The keymap.cfg key mapping file}
+
+% TODO
+
+\end{document}

Doc/Orbiter Developer Manual/MESH.tex

@@ -0,0 +1,214 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{The mesh file}
+ORBITER uses a proprietary mesh file format. Mesh files are ASCII text files. (A binary format may be introduced in the future). Mesh files are located in the Meshes subdirectory unless the MeshDir entry in Orbiter.cfg points to a different directory.\\
+\\
+ORBITER meshes are defined in a left-handed coordinate system. Vessel meshes should be oriented such that the \textit{vessel’s nose} (or more precisely, its \textit{main thrust direction}) points in the positive z-direction, the positive x-axis points \textit{right}, and the positive y-axis points \textit{up}.\\
+\\
+The units for vertex coordinates are \textit{meters} [m].\\
+\\
+Mesh file format:
+\begin{lstlisting}[language=OSFS]
+MSHX1	;header
+GROUPS <n>	;<n>: number of groups
+<group 1>	;group spec 1
+<group 2>	;group spec 2
+...
+<group n>	;group spec n
+
+MATERIALS <m>	;<m>: number of materials
+<mtrl-name 1>	;material name 1
+<mtrl-name 2>	;material name 2
+...
+<mtrl-name m>	;material name m
+<material 1>	;material spec 1
+<material 2>	;material spec 2
+...
+<material m>	;material spec m
+
+TEXTURES <t>	;<t>: number of textures
+<tex-name 1>	;texture name 1
+<tex-name 2>	;texture name 2
+...
+<tex-name t>	;texture name t
+\end{lstlisting}
+
+\noindent
+Group specs:
+
+\begin{lstlisting}[language=OSFS]
+[LABEL <label>]		;group label, optional
+[MATERIAL <i>]		;material index, optional
+[TEXTURE <j>]		;texture index, optional
+[TEXWRAP <wrap>]	;texture wrap mode, <wrap> = U or V or UV, optional
+[NONORMAL]			;"no normals" flag; see below, optional
+[FLAG <f>]			;multi-purpose bit-flags; see below, optional
+GEOM <nv> <nt>	;<nv>: vertex count, <nt>: triangle count
+<vtx 0>			;vertex spec 0
+<vtx 1>			;vertex spec 1
+...
+<vtx nv-1>	;vertex spec nv-1
+<tri 0>		;triangle spec 0
+<tri 1>		;triangle spec 1
+...
+<tri nt-1>	;triangle spec nt-1
+\end{lstlisting}
+
+\noindent
+Vertex specs:
+
+\begin{lstlisting}[language=OSFS]
+<x> <y> <z> [<nx> <ny> <nz> [<tu> <tv>]]
+	;<x> <y> <z>: vertex position
+	;<nx> <ny> <nz>: vertex normal (optional)
+	;<tu> <tv>: texture coordinates (optional)
+\end{lstlisting}
+
+\noindent
+Missing normals are automatically calculated as the mean of the normals of adjacent faces. Texture coordinates are only required if the group uses a texture.\\
+\\
+Triangle specs:
+
+\begin{lstlisting}[language=OSFS]
+<i> <j> <k>	;vertex indices (zero-based). Left-hand face is rendered.
+\end{lstlisting}
+
+\noindent
+Material specs:
+
+\begin{lstlisting}[language=OSFS]
+MATERIAL <mtrl-name>	;material header
+<dr> <dg> <db> <da>		;Diffuse colour (RGBA)
+<ar> <ag> <ab> <aa>		;Ambient colour (RGBA)
+<sr> <sg> <sb> <sa> <pow>	;Specular colour (RGBA) and specular power (float)
+<er> <eg> <eb> <ea>		;Emissive colour (RGBA)
+\end{lstlisting}
+
+
+\subsection{Mesh groups}
+Meshes are divided into groups. Each group can define its own material and texture specification. For example, if you want different parts of the object to have different material properties, you need to split the mesh into groups accordingly.\\
+\\
+Each group contains
+
+\begin{itemize}
+\item An optional label (tag LABEL). The label must be a single word without white spaces. It has no direct effect on the mesh, but can be used to associate a name with a mesh group. Named groups are easier to access from within a vessel module code than group indices (e.g. for defining animations etc.)
+\item An optional material index. Indices $\geq 1$ select a material of the mesh’s material list. Index 0 means “default material” (which is white, diffuse and opaque). If the group doesn’t specify a material index it inherits the previous group’s material. The first group in the mesh \textit{must} specify a material index, otherwise the result is undefined.
+\item An optional texture index. Indices $\geq 1$ select a texture from the mesh’s texture list. Index 0 means “no texture”. If the group doesn’t specify a texture index it inherits the previous group’s texture. The first group in the mesh \textit{must} specify a texture index, otherwise the result is undefined.
+\item An optional TEXWRAP flag. This defines how textures wrap around the object. “U” causes textures to wrap in the u-coordinate direction in texel space, “V” wraps in v-coordinate direction, and “UV” wraps in both directions. Default is no wrapping.
+\item An optional NONORMAL flag. This indicates that vertex definitions in this group don’t contain normal definitions, and the first two numbers after the vertex coordinate (x,y,z) triplet is interpreted as texture coordinate (u,v) pair.
+\item An optional FLAG entry. This allows to specify a user-defined 32-bit flag (in hex format) whose interpretation is context-dependent. Below is a list of flags currently recognised by Orbiter:
+
+\begin{table}[H]
+	\centering
+	\begin{tabular}{ |c|c|c| }
+	\hline\rule{0pt}{2ex}
+	\textbf{Mesh type} & \textbf{Flag} & \textbf{Interpretation} \\
+	\hline\rule{0pt}{2ex}
+	Vessel & 0x00000001 & Do not use this group to render ground shadows\\
+	\hline\rule{0pt}{2ex}
+	Vessel & 0x00000002 & Do not render this group\\
+	\hline\rule{0pt}{2ex}
+	Vessel & 0x00000004 & Do not apply lighting when rendering this group\\
+	\hline\rule{0pt}{2ex}
+	Vessel & 0x00000008 & Texture blending directive: additive with background\\
+	\hline
+	\end{tabular}
+\end{table}
+
+\item A GEOM specification, defining the number of vertices and triangles in the group.
+\item A vertx list (see below)
+\item A triangle list (see below)
+\end{itemize}
+
+\noindent
+\textbf{Vertex lists}\\
+Each group contains a vertex list, defining the positions, and optionally normal directions and texture coordinates of the vertices in the group.\\
+Each line in the list defines a vertex, and contains up to 8 floating point numbers (separated by spaces)
+
+\begin{itemize}
+\item The first 3 numbers contain the cartesian vertex coordinates (x,y,z) in the object local coordinate space. Units are meters [m]
+\item The next 3 numbers (if present) contain the vertex normal direction (nx,ny,nz) (unless the group has set the NONORMAL flag). The normal direction is the direction perpendicular to the mesh surface at the vertex position. Orbiter needs this to generate correct lighting effects. If no normals are specified (or if the NONORMAL flag is set) Orbiter guesses the normal direction as the average of the normals of the surrounding triangles. This works well for smooth surfaces, but should be avoided for surfaces which contain sharp edges. Normal directions should be normalised, i.e. $\sqrt{nx^{2}+ny^{2}+nz^{2}} = 1$.
+\item The next 2 numbers (if present) contain the vertex texture coordinates (u,v). Texture coordinates are only required if the group uses a texture (i.e. has texture index $\geq 1$). Texture coordinates define how a rectangular 2D texture is mapped onto the object surface. Texture coordinate (0,0) refers to the lower left corner of the texture, (1,1) refers to the upper right corner. Coordinates > 1 are allowed and cause textures to repeat periodically.
+\end{itemize}
+
+\noindent
+\underline{Notes:}
+
+\begin{itemize}
+\item Vertices located at sharp edges or corners require multiple entries in the vertex list, because they have multiple normal directions (in other words, the surfaces are \textit{non-differentiable} at edges). In that case you should always define the normals in the mesh file, and not leave it to Orbiter to generate them for you. Otherwise the edges will appear unrealistically smooth.
+\item Likewise, vertices with multiple vertex coordinates (e.g. at the edge between two texture maps) need multiple entries in the vertex list.
+\end{itemize}
+
+\noindent
+\textbf{Triangle lists}\\
+The group’s triangle list follows immediately below the vertex list. It defines the triangles which compose the group’s mesh surface.
+
+\begin{itemize}
+\item Each line in the list defines a triangle and consists of 3 integer numbers (i,j,k). Each of the numbers specifies a vertex from the group’s vertex list (starting from 0)
+\item Only the “clockwise” (CW) side of each triangle is rendered: the side which, if you look at it, has the vertices arranged in a clockwise order. The opposite “counterclockwise” (CCW) side is invisible.
+\item If you need to render both sides of a triangle (e.g. for a thin plate) you need to define two triangles.
+\item If you want to flip the rendered side of a triangle (e.g. to correct for “inside out” artefacts) you need to rearrange the triangle indices in the following way: (i,j,k) $\to$ (i,k,j)
+\end{itemize}
+
+
+\subsection{Material list}
+Materials allow to specify the homogeneous lighting properties of a mesh group. The material lists consists of
+
+\begin{itemize}
+\item A header line, MATERIALS <m>, defining the number <m> of materials.
+\item A list of material \textit{names}.
+\item A list of material \textit{properties}.
+\end{itemize}
+
+\noindent
+Each material property specification consists of 4 RGBA quadruplets, where R, G and B define the red, green and blue components, and A is the opacity. RGB values should be between 0 and 1, but can be > 1 for special effects. A \textit{must} be between 0 (fully transparent) and 1 (fully opaque).
+
+\begin{itemize}
+\item The first line specifies the \textit{diffuse material colour}. This is the colour that is diffusely (in all directions) reflected from an illuminated surface.
+\item The second line specifies the \textit{ambient material colour}. This is the colour of an unlit surface.
+\item The third line specifies the \textit{specular colour}. This is the colour of light reflected by a polished surface into a narrow beam. The \textit{power} entry specifies the width of the cone into which specular light is reflected. Higher values mean a narrower cone, i.e. sharper reflections. Typical values are around 10. If omitted, the default value for power is 0.
+\item The fourth line specifies the \textit{emissive colour}. This is the colour of light emitted by a glowing surface.
+\end{itemize}
+
+
+\subsection{Texture list}
+The texture list contains the names of texture files used by the various mesh groups. Texture names should contain file extensions “.dds” but no directory paths. Textures must be located in Orbiter’s Textures subdirectory.\\
+\\
+\underline{Notes:}
+
+\begin{itemize}
+\item Textures must be in DDS format (“Direct Draw Surface”). A DirectX SDK tool, dxtex, which is included in the Orbiter SDK package, allows to convert BMP bitmaps into DDS.
+\item You should store the textures either in DXT1 compressed format (opaque textures or textures with binary transparency), or in DXT5 compressed format (for textures with continuous transparency).
+\item For maximum compatibility, avoid textures larger than 256x256 pixels, because of limitations of some older graphics cards.
+\item If a texture is to be dynamically updated during the simulation (e.g. instrument panels in virtual cockpits), the texture name should be followed by the flag ‘D’. Orbiter will decompress these textures to allow more efficient dynamic updates.
+\end{itemize}
+
+
+\subsection{Performance optimisation}
+To achieve the best results with your new mesh, consider the following points:
+
+\begin{itemize}
+\item Texture groups which use the same texture should be stored in sequence in the mesh. Unnecessary switching between textures can degrade performance if textures must be swapped in and out of video memory.
+\item Within a sequence of groups using the same textures, groups which use the same material should be stored in sequence. Again, this avoids the need of switching render parameters.
+\item Avoid large numbers of very small groups. If small groups use the same parameters (material, texture, etc.) they should be merged into a single group.
+\item Groups which use transparent materials or textures should be sorted to the end of the mesh. If transparent groups overlap, the innermost ones should be listed before the outer ones.\\
+In order to render transparency correctly, DirectX requires the scene seen through the transparent object to be fully built before the transparent object itself is rendered. Any objects rendered after the transparent object will be masked by it.
+\item Objects with transparency and specular reflection are more expensive to render than opaque and diffusive objects, so use these features sparingly.
+% TODO add section link
+\item And most importantly, \textit{keep the vertex count low!} (See section TODO)
+\end{itemize}
+
+
+\subsection{Mesh converters}
+If you want to convert an existing model into an Orbiter mesh, check the Orbiter web forum for mesh converters created by other users. There is currently a converter which converts from Truespace asc format, which many 3D editors can export. If you have written your own mesh editor or converter, publish it!
+
+
+\subsection{Mesh utilities}
+The Orbiter SDK contains a few utilities that help to extract data from mesh files. They are located in the Orbitersdk\textbackslash utils folder.\\
+\\
+\textbf{shipedit}: extracts geometric information from a mesh that are useful for defining physical parameters for vessel modules. These include the bounding box extents, volume, cross-sectional areas, and inertia tensor for homogeneous density distribution.\\
+\\
+\textbf{meshc}: mesh compiler. Eventually this may be extended to convert mesh files from text to a binary format (for more compact storage and faster loading) but currently it only extracts mesh parameters into a C header file that can be included in a vessel module project for convenient access to named mesh groups.
+
+\end{document}

Doc/Orbiter Developer Manual/NEW_SPACECRAFT.tex

@@ -0,0 +1,25 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{How to create a new spacecraft class}
+To add a new spacecraft class to ORBITER, the following steps must be performed:
+
+\begin{itemize}
+\item Define the physical parameters of the new spacecraft class in a configuration file in the Config subdirectory.
+\item Create a surface mesh which defines the ship’s visual appearance, in the Meshes subdirectory.
+\item Optionally, add any textures used by the vessel, to the Textures subdirectory.
+\item Add a scenario which includes one or more spacecraft of the new class in the Scenarios subdirectory.
+\end{itemize}
+
+\noindent
+The above steps allow you to create a basic ship with generic parameters. To fully customize your new spacecraft one more step is required:
+
+\begin{itemize}
+\item Add a DLL module for the new vessel class which customises its behaviour (moving parts, custom cockpit panels, custom flight model, etc.) in the Modules subdirectory.
+\end{itemize}
+
+Refer to the OrbiterAPI document for information on writing vessel modules for Orbiter. A number of sample modules with source code is contained in the Orbitersdk\textbackslash samples folder.\\
+\\
+Note that every spacecraft class \textit{must} have a configuration file, even if all its parameters are defined in a DLL module. (In this case, the only entry in the configuration file may be the module name.)
+
+\end{document}

Doc/Orbiter Developer Manual/Orbiter Developer Manual.tex

@@ -0,0 +1,81 @@
+% import macros and common styles
+\input{..//common_definitions}
+
+
+\graphicspath{{Images//}}
+
+
+
+\renewcommand*\familydefault{\sfdefault}
+\sffamily
+
+
+\pagestyle{fancy}
+\renewcommand{\footrulewidth}{0.4pt}
+
+
+% define page header/footer
+\lhead{}
+\chead{}
+\rhead{}
+\lfoot{Orbiter Developer Manual}
+\cfoot{\thepage}
+
+
+\titleformat{\paragraph}[hang]{\bfseries}{\theparagraph}{1em}{}
+
+
+
+\begin{document}
+
+\begin{titlepage}
+\begin{center}
+
+
+\textsc{\fontsize{60}{60} \textbf{Orbiter}}\\
+\vspace{0.5cm}
+
+\textsc{\Huge Space Flight Simulator}\\
+\vspace{2.0cm}
+
+\includegraphics[width=0.75\textwidth]{..//orbiterlogo.png}
+\vspace{2.0cm}
+
+\textsc{\LARGE Orbiter Developer Manual}
+
+\end{center}
+\end{titlepage}
+
+
+\newpage
+\pagenumbering{roman}
+
+\tableofcontents
+\newpage
+
+\pagenumbering{arabic}
+
+\newpage
+\subfile{INTRODUCTION}
+\newpage
+\subfile{CONFIG}
+\newpage
+\subfile{SCENARIO}
+\newpage
+\subfile{PLANETS}
+\newpage
+\subfile{KEYMAP}
+\newpage
+\subfile{NEW_SPACECRAFT}
+\newpage
+\subfile{VESSEL_CFG}
+\newpage
+\subfile{SPACECRAFT}
+\newpage
+\subfile{MESH}
+\newpage
+\subfile{PUBLISH}
+\newpage
+\subfile{REFERENCES}
+
+\end{document}

Doc/Orbiter Developer Manual/PLANETS.tex

@@ -0,0 +1,16 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles} 
+\begin{document}
+
+\section{Planets and moons}
+% TODO
+
+\subsection{Planet texture maps}
+% TODO
+
+\subsection{Planet modules}
+% TODO
+
+\subsection{Defining an atmosphere}
+% TODO
+
+\end{document}