From 99a85c780c970eb5f1865112dd6f5f1c872a32c6 Mon Sep 17 00:00:00 2001
From: ehofman <ehofman>
Date: Fri, 15 Aug 2003 16:17:37 +0000
Subject: [PATCH] Add a description for using extensions and a description of
 the generic protocol configuration file

---
 docs-mini/README.extensions | 91 +++++++++++++++++++++++++++++++++++++
 docs-mini/README.protocol   | 81 +++++++++++++++++++++++++++++++++
 2 files changed, 172 insertions(+)
 create mode 100644 docs-mini/README.extensions
 create mode 100644 docs-mini/README.protocol

diff --git a/docs-mini/README.extensions b/docs-mini/README.extensions
new file mode 100644
index 000000000..6b1dbc0f7
--- /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
index 000000000..96c4aa55b
--- /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>