Add a description for using extensions and a description of the generic protocol...

diff --git a/docs-mini/README.extensions b/docs-mini/README.extensions
new file mode 100644 (file)
index 0000000..6b1dbc0
--- /dev/null
+++ b/docs-mini/README.extensions
@@ -0,0 +1,91 @@
+Using Extensions
+----------------
+
+
+To use an OpenGL extension in the code is is necessary to include a refference
+to the extensions.hxx header file and add the following to the code (as an
+example):
+
+
+/* global variables */
+glPointParameterfProc glPointParameterfPtr = 0;
+glPointParameterfvProc glPointParameterfvPtr = 0;
+bool glPointParameterIsSupported = false;
+
+
+To be able to use these extensions the functions pointers have to be initialized
+by something like the following examplde code:
+
+
+if (SGIsOpenGLExtensionSupported("GL_EXT_point_parameters") )
+{
+  glPointParameterIsSupported = true;
+  glPointParameterfPtr =  (glPointParameterfProc)
+                          SGLookupFunction("glPointParameterfEXT");
+  glPointParameterfvPtr = (glPointParameterfvProc)
+                          SGLookupFunction("glPointParameterfvEXT");
+
+} else if ( SGIsOpenGLExtensionSupported("GL_ARB_point_parameters") ) {
+  glPointParameterIsSupported = true;
+  glPointParameterfPtr =  (glPointParameterfProc)
+                          SGLookupFunction("glPointParameterfARB");
+  glPointParameterfvPtr = (glPointParameterfvProc)
+                          SGLookupFunction("glPointParameterfvARB");
+} else
+  glPointParameterIsSupported = false;
+
+
+If a function is supported the function pointers are now initialized.
+
+When using the functions (note that glPointParameterfvPtr() is used instead of
+glPointParameterfvEXT() )it is important to check whether the
+glPointParameterIsSupported is set to true:
+
+
+if ( distance_attenuation && glPointParameterIsSupported )
+{
+  // Enable states for drawing points with GL_extension
+  glEnable(GL_POINT_SMOOTH);
+
+  float quadratic[3] = {1.0, 0.001, 0.0000001};
+
+  // makes the points fade as they move away
+  glPointParameterfvPtr(GL_DISTANCE_ATTENUATION_EXT, quadratic);
+  glPointParameterfPtr(GL_POINT_SIZE_MIN_EXT, 1.0);
+}
+
+
+
+Adding Extensions
+-----------------
+
+To add an extension to the SimGear extension support code you normally only need
+to edit the extensions.hxx header file in the screen directory.
+
+Currently there are two extensions supported:
+* glPointParameterf
+* glActiveTexture
+
+Adding a new extension involves adding the defines assosiated with the extension
+(surrounded by the appropriate extension test):
+
+
+#ifndef GL_EXT_point_parameters
+# define GL_EXT_point_parameters 1
+# define GL_POINT_SIZE_MIN_EXT                                  0x8126
+# define GL_DISTANCE_ATTENUATION_EXT                            0x8129
+#endif
+
+
+
+This is needed because not all OpenGL implementations define them correctly.
+The following step is to add a typedef for the function pointer:
+
+
+typedef void (APIENTRY * glPointParameterfProc)(GLenum pname, GLfloat param);
+
+
+
+The APIENTRY refference is only used by windows machines but is defined empty
+for all other platforms and hence needs to be added for cross platfrom
+compatibillity.

diff --git a/docs-mini/README.protocol b/docs-mini/README.protocol
new file mode 100644 (file)
index 0000000..96c4aa5
--- /dev/null
+++ b/docs-mini/README.protocol
@@ -0,0 +1,81 @@
+The generic communication protocol for FlightGear provides a powerfull way
+of adding a simple ASCII based output only protocol, just by defining an
+XML encoded configuration file and placing it in the $FG_ROOT/data/Protocols
+directory.
+
+The definition of the protocol consists of variable separators, line separators,
+and chuncks of text.
+
+Each chunck defines:
+
+<name>         for ease of use
+<node>         the property tree node which provides the data
+<type>         the value type (needed for formatting)
+<format>       defines the actual piece of text which should be sent.
+               it can include formatting options like:
+                               <type>
+                       %s      string
+                       %i      integer (default)
+                       %f      float
+
+<factor>       an optionale multiplication factor which can be used for
+               unit conversion. (for example, radians to degrees).
+<offset>       an optional offset which can be used for unit conversion.
+               (for example, degrees Celsius to degrees Fahrenheit).
+
+
+The output section also could define the variable separator and line separator.
+
+The separators can be either a control character such as a tab or newline, or a
+user specified string or other single charachter. The currently supported
+control charachters are:
+
+<var_separator>:
+<line_separator>:
+Name           Charachter
+
+newline                '\n'
+tab            '\t'
+formfeed       '\f'
+carriagereturn '\r'
+verticaltab    '\v'
+
+any other charachters just need to be added to "Network/generic.cxx"
+
+The var_separator is placed between each variable, while the line_separator is
+placed at the end of each lot of variables.
+
+
+A simple protocol configuration file then could look something like the
+following:
+
+<?xml version="1.0"?>
+
+<PropertyList>
+ <output>
+
+   <line_separator>newline</line_separator>
+   <var_separator>newline</var_separator>
+
+   <chunk>
+    <name>speed</name>
+    <format>V=%d</format>
+    <node>/velocities/airspeed-kt</node>
+   </chunk>
+
+   <chunk>
+    <name>heading (rad)</name>
+    <format>H=%02d</format>
+    <node>/orientation/heading-deg</node>
+    <factor>57.29578</factor>  <!-- degrees to radians -->
+   </chunk>
+
+   <chunk>
+    <name>pitch angle (deg)</name>
+    <format>P=%05.1f</format>
+    <type>float</type>
+    <node>/orientation/pitch-deg</node>
+   </chunk>
+
+ </output>
+</PropertyList>