Updating and correcting the new documentation

Doc/Orbiter Developer Manual/CONFIG.tex

@@ -29,15 +29,11 @@ \subsubsection*{General parameters}
 	\hline\rule{0pt}{2ex}
 	Name & String & A name for the planetary system\\
 	\hline\rule{0pt}{2ex}
-	MarkerPath & String & Directory path containing surface marker lists for the planet. Default: .\textbackslash Config\textbackslash <\textit{Solsys-name}>\textbackslash Marker\textbackslash \\
+	MarkerPath & String & Directory path containing celestial marker lists for the planetary system (see section \ref{ssec:custom_markers}). Default: .\textbackslash Config\textbackslash <\textit{Solsys-name}>\textbackslash Marker\textbackslash \\
 	\hline
 	\end{longtable}
 %\end{table}
 
-\noindent
-%TODO handle legacy model link? or just mention it and don't detail it? or mention old documentation?
-The MarkerPath entry is used only for legacy-style marker definitions (see Chapter TODO). For new quadtree-based markers, see section \ref{sssec:label_tile_format}.
-
 \subsubsection*{Object list}
 The object list defines the celestial bodies populating the planetary system and their hierarchy.\\
 \\
@@ -293,7 +289,7 @@ \subsubsection*{Visualisation parameters}
 %\end{table}
 
 
-\subsubsection*{Surface marker parameters (optional)}
+\subsubsection*{Surface marker parameters (legacy)}
 %\begin{table}[H]
 	%\centering
 	\begin{longtable}{ |p{0.25\textwidth}|p{0.09\textwidth}|p{0.58\textwidth}| }
@@ -306,8 +302,7 @@ \subsubsection*{Surface marker parameters (optional)}
 %\end{table}
 
 \noindent
-%TODO handle legacy model link? or just mention it and don't detail it? or mention old documentation?
-This entry refers to legacy surface markers (see Chapter TODO). For new quadtree-based marker definitions, see section \ref{sssec:label_tile_format}.
+This entry refers to legacy surface markers (see section \ref{ssec:custom_markers}). For new quadtree-based marker definitions, see section \ref{sssec:label_tile_format}.
 
 
 \subsubsection*{Surface bases (optional)}
@@ -918,15 +913,16 @@ \subsubsection*{Adding objects to surface bases}
 \end{itemize}
 
 
-\subsection{Custom markers (legacy)}
-\alertbox{As regards markers for planetary surface featues, this section contains information for old-style (pre-Orbiter 2016) marker definitions. These are retained for backward compatibility. For new, quadtree-based marker definitions, see section \ref{sssec:label_tile_format}.}
+\subsection{Custom markers}
+\label{ssec:custom_markers}
+\alertbox{As regards markers for planetary surface features, this section contains information for old-style (pre-Orbiter 2016) marker definitions. These are retained for backward compatibility. For new, quadtree-based marker definitions, see section \ref{sssec:label_tile_format}.}
 
 \noindent
-Labels can be defined to mark objects on the celestial sphere (e.g. bright stars, navigation stars, nebulae, etc.) or on planetary surfaces to locate natural landmarks, points of interest, historic landing sites, navigational aids, etc.\\
-The user can display these markers during the simulation with the Visual helpers option (\keystroke{F9} or \Ctrl\keystroke{F9}).\\
+Labels can be defined to mark objects on the celestial sphere (e.g. bright stars, navigation stars, nebulae, etc.) or on planetary surfaces (legacy) to locate natural landmarks, points of interest, historic landing sites, navigational aids, etc.\\
+The user can display these markers during the simulation with the Visual helpers option (\keystroke{F9} or \Alt\keystroke{F9}).\\
 By default, all files for celestial and planetary surface markers are placed in a subdirectory\\
 \indent .\textbackslash Config\textbackslash <\textit{name}>\textbackslash Marker\\
-where <\textit{name}> is the name of the planetary system (for celestial markers) or the celestial body (for surface markers) they are referring to. A different location for marker files can be specified with the MarkerPath option in the planet's or planetary system's configuration file (see sections \ref{ssec:planetery_sys} and \ref{ssec:planets}). Marker files are text files with extension .mkr. Multiple files can be defined for a single planet or planetary system, which the user can turn on and off individually. The format is
+where <\textit{name}> is the name of the planetary system (for celestial markers) or the celestial body (for legacy surface markers) they are referring to. A different location for marker files can be specified with the MarkerPath option in the planetary system's or planet's configuration file (see sections \ref{ssec:planetery_sys} and \ref{ssec:planets}). Marker files are text files with extension .mkr. Multiple files can be defined for a single planet or planetary system, which the user can turn on and off individually. The format is
 
 \begin{lstlisting}[language=OSFS]
 BEGIN_HEADER
@@ -960,7 +956,6 @@ \subsection{Custom markers (legacy)}
 	\hline\rule{0pt}{2ex}
 	2 & $\Diamond$ & diamond\\
 	\hline\rule{0pt}{2ex}
-%TODO nabla and delta symbols switched, check code to confirm what ID is what symbol
 	3 & $\nabla$ & nabla\\
 	\hline\rule{0pt}{2ex}
 	4 & $\Delta$ & delta\\
@@ -978,18 +973,17 @@ \subsection{Custom markers (legacy)}
 	%\centering
 	\begin{longtable}{ |p{0.04\textwidth}|p{0.04\textwidth}|p{0.2\textwidth}| }
 	\hline\rule{0pt}{2ex}
-%TODO check code for actual colors
-	0 & \cellcolor{yellow!100} & yellow\\
+	0 & \cellcolor[HTML]{FFFF00} & yellow\\
 	\hline\rule{0pt}{2ex}
-	1 & \cellcolor{cyan!50} & cyan (default)\\
+	1 & \cellcolor[HTML]{00FFFF} & cyan (default)\\
 	\hline\rule{0pt}{2ex}
-	2 & \cellcolor{red!100} & red\\
+	2 & \cellcolor[HTML]{FF3F3F} & red\\
 	\hline\rule{0pt}{2ex}
-	3 & \cellcolor{purple!50} & purple\\
+	3 & \cellcolor[HTML]{FF00FF} & purple\\
 	\hline\rule{0pt}{2ex}
-	4 & \cellcolor{green!100} & green\\
+	4 & \cellcolor[HTML]{3FFF3F} & green\\
 	\hline\rule{0pt}{2ex}
-	5 & \cellcolor{blue!50} & blue\\
+	5 & \cellcolor[HTML]{007FFF} & blue\\
 	\hline
 	\end{longtable}
 %\end{table}

Doc/Orbiter Developer Manual/FLOW.tex

@@ -0,0 +1,19 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles}
+\begin{document}
+
+\section{Orbiter program flow and module callback order}
+This section defines the program flow of the Orbiter frame loop and the order in which module callback functions are called by Orbiter.
+
+
+\subsection{The frame update loop and vessel module callback functions}
+
+The program flow diagram below illustrates the events in the Orbiter frame update loop and the calling order of VESSEL2 callback functions.\\
+The clbkPreStep and clbkPostStep methods are called for every vessel at each frame update. Other callback functions are only called when the associated event has occurred. Some callback functions such as clbkPanelRedrawEvent may be called multiple times for a vessel in a single frame.
+
+\begin{figure}[H]
+	\centering
+	\subfigure{\includegraphics[width=0.65\textwidth]{progflow1.png}}
+	\caption{Orbiter frame update loop and position of VESSEL2 callback functions.}
+\end{figure}
+
+\end{document}

Doc/Orbiter Developer Manual/GRAPHICS_CLIENT.tex

@@ -0,0 +1,54 @@
+\documentclass[Orbiter Developer Manual.tex]{subfiles}
+\begin{document}
+
+\section{Graphics Client Development}
+
+\subsection{Introduction}
+This page contains information for developers of plug-in graphics clients for the non-graphics version of Orbiter (Orbiter\_NG).\\
+Graphics clients are DLL modules which contain the implementation of a client class derived from oapi::GraphicsClient. They handle the device-specific aspects of rendering a 3-D window into the "Orbiter world".
+
+
+\subsection{Particle Streams}
+Particle streams are a component of Orbiter graphics clients.\\
+Particle streams can be used to create visual effects for contrails, exhaust and plasma streams, reentry heating, condensation, etc. The management of particle streams is almost entirely the responsibility of the graphics client. The orbiter core notifies the client only
+\begin{itemize}
+\item to request a new particle stream for a vessel object
+\item to detach a stream from its object (e.g. if the object is deleted)
+\end{itemize}
+
+\noindent
+The implementation details for the particle streams, including render options, are left to the client.
+
+
+\subsubsection{Adding particle stream support}
+
+To add particle stream support to a graphics client, the following steps are required:
+\begin{itemize}
+\item Create one or more classes derived from oapi::ParticleStream
+\item Overload the particle stream-related callback methods of oapi::GraphicsClient, including
+\begin{itemize}
+\item oapi::GraphicsClient::clbkCreateParticleStream()
+\item oapi::GraphicsClient::clbkCreateExhaustStream()
+\item oapi::GraphicsClient::clbkCreateReentryStream()
+\end{itemize}
+\end{itemize}
+
+\noindent
+By default, these methods return NULL pointers, i.e. don't provide particle stream support. Your overloaded methods should create an instance of an appropriate derived particle stream class and return a pointer to it.
+
+\alertbox{The client must keep track of all particle streams created. In particular, the orbiter core never deletes any particle streams it has obtained from the client. Particle stream management and cleanup must be provided by the client.}
+
+
+\subsubsection{Attaching and detaching streams}
+Once a particle stream has been created, it must be connected to a vessel instance (provided by the hVessel parameter in each of the particle stream-related callback functions of the graphics client). To connect the particle stream to the vessel, use one of the oapi::ParticleStream::Attach() methods using the provided vessel handle.\\
+The particle emission point and emission direction are relative to the associated vessel.\\
+Sometimes Orbiter will call the oapi::ParticleStream::Detach() method for a stream. This is usually in response to deletion of the vessel. Therefore, the stream should no longer make use of the vessel reference after it has been detached. In particular, no new particles should be generated.
+
+\infobox{After Orbiter has detached a particle stream, it will no longer access it. The client is free to delete the particle stream instance once it has been detached. Generally, the stream should be deleted after all the remaining particles in the stream have expired.}
+
+
+\subsubsection{Deleting streams}
+Generally, streams should only be deleted after they have been detached and after all remaining particles have expired. Deleting a stream with active particles will create a visual inconsistency and should be avoided. The only exception is the cleanup at the end of a simulation session.\\
+When a stream is deleted while still attached to its object, Orbiter will call the stream's Detach method during the destruction process.
+
+\end{document}

Doc/Orbiter Developer Manual/INTRODUCTION.tex

@@ -2,6 +2,10 @@
 \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.
+This document is aimed at addon developers, or anyone who wants to extend Orbiter's functionality.\\
+It details what is needed to create new vessels, both the simpler "configuration file" type, and the more capable "code module" type, as well as the 3D model for vessel visualisation during the simulation.
+In this document you will also find information on how to modify, or adding, surface bases, moons, planets and entire planetary systems.\\
+In addition, guidance is provided on how you can improve Orbiter's source code, by adding new features or fixing bugs.
+
 
 \end{document}