Initial revision

git-svn-id: file:///usr/local/opt/svn/repos/glagen@3 0f7e0d06-a6f9-0310-a55f-d5f984f55e4c

1 files changed, 237 insertions, 0 deletions

diff --git a/trunk/glagen/dll/README b/trunk/glagen/dll/README
new file mode 100644
index 0000000..36d270e
--- /dev/null
+++ b/trunk/glagen/dll/README
@@ -0,0 +1,237 @@
+
+	=============================
+	Dynamic Library Loader Module
+	=============================
+	GLAGEN - 2002 - Hugues HIEGEL
+
+
+
+
+	I. What is it ?
+
+
+The Dynamic Library Loader Module (DLL Module) is part of the GLAGEN
+Engine. It goals is to provide to the end-user a flexible usage of
+external C/C++ libraries (*.so) .
+
+At this time, only C++ libraries are supported, because the main DLL
+Module is already written in C++. It should be easy to allow C-written
+libraries, but du to a lack of time, it should appear.. later.
+
+
+	II. How does it work ?
+
+
+The DLL Engine reads all libraries, especially their Names and
+Dependancies, and then builds a dependancies tree. This last would be
+used by the Network module (written by lam_m), and should determine in
+which order each library would be executed in the main loop.
+For example:
+
+    library A needs nobody, alike library B. Libraries AC and AD needs
+    A, BE and BF need B, ACG needs AC and BFH needs BF.
+    We would obtain such a tree:
+
+      (root)
+	\__________________
+         |                |
+	 A                B
+	 \_______	  \_____
+	  |    	|      	   |   |
+	  AC	AD	   BE  BF
+ 	  \_  		       \_
+	   |			|
+	   ACG			BFH
+
+
+    Then the execution order would be done in such an order, reading
+    the tree top-to-bottom, then left-to-right:
+    A-AC-ACG-AD-B-BE-BF-BFH
+
+    Like that, we are certain that any library would be able to read
+    the results of one of its dependancies.
+
+I did a Library class that contains a lot of infos about each
+library.so. For each library file, I effectively create a new Library
+instance, and initialize it by opening the library, ang trying to get
+infos using dlsym and some canonical symbols (See section above for
+more info about libraries' symbols). If the library do answer to the
+required ones, then it is stored, else it is immediately closed and
+forgotten.
+
+Along the program, we will mainly work with list of Libraries, for
+this class is our swiss tool.
+
+
+
+	III. The Library class
+
+In this section, I will explain the main characteristics of this class
+and the method used.
+
+  III.0 Hello, Bye
+
+First of all, we allow the user to make two functions in its library :
+GLG_Hello and GLG_Bye, in which he could put an hello and bye message
+to the standard out. For example. He also could wathever he wants in
+them, but no initialisation. These would be desribed in the next
+chapter. Hello and Bye are there just to give flexibility and a bit of
+fun.
+
+  III.1 Initialisation
+
+Creating a new Library class and Loading it consists in giving a
+library filename, trying to open it, then trying to obtain a DL
+handler.
+If a handler is obtained, we load some Symbols to check if it is
+a real GLAGEN library : the .so must return a name as a string in
+respond to the call at GLG_Name(). Then we try to get its dependancies.
+These infos are finally used to generate the dependances tree ahead.
+The dependancies are given under a list of string, that make the
+treatment easier.
+
+Each library is allowed to use as many properties it wants for every
+3d engine's dot. Each dot has a list of properties, and this list is
+created by a recursive call of every library's GLG_Init symbol. Each
+library class associated with each library file retains for each
+property requested its position in the global list of properties.
+For example:
+
+    Library Foo needs to use and/or share three sorts of data in the
+    whole glagen process, for example a surface information, a color
+    one and the age of the captain.
+    Foo should have a GLG_Init() function like this :
+
+	GLG_Init(...)
+	{
+	  ...
+	  palloc(surface, ...);
+	  palloc(color, ...);
+	  palloc(captainage, ...);
+	  ...
+	}
+
+     The library class linked with this library would then ask the
+     server for some memory rooms, and then stores three (because of
+     the three palloc()) keys in some deep owned property.
+     During the main loop, the library should only ask to read or
+     write its third room to obtain or modify the captainage.
+     It doesn't even know the captainage is really stored in some
+     42nd room in the whole 'memory'.
+
+palloc() is a function that calls itself a method of the current
+calling library, so this library can stores the global acces method on
+the local machine.
+For that, the initialize() method gives a pointer to (this) to the
+GLG_Init of the dll. Then this dll has nothing to do qith this
+pointer, just give it as a parameter to palloc(). This palloc(),
+defined out of the library class, calls then the REF->_palloc() method.
+I didn't found a simpliest method to do that, because I didn't want
+the dll developper hav to know anything about the Library class.
+If I forced him to call REF->_palloc() instead of palloc(REF), he
+would have to know the REF* prototype for its GLG_Init definition,
+then he would have to use the libraryclass header.
+My goal is to provide him a 'totally' independant code. So, I choose
+to make him take a void* REF in its GLG_Init(), and then give this 
+void* REF to palloc, which takes it as a Libary*.
+See code for more details : ./dll/classes/libclass.hh and a sample
+library code.
+
+
+  III.2 Global properties accesses
+
+Two functions allow libraries to access dots properties, in read or
+write mode. 
+For example:
+
+    Library17 has 3 dots properties, declared in order (the 1st in
+    first place, the 2nd in second place and the 3rd in last). 
+    The library's user know what is the first property, what is the
+    second, and what is the third. For example, he decides the first
+    property is the color, the second the height, and
+    god-know-whatever is the third. When he wants to access the color
+    property, he would only call a GLG_read(2, ...) function.
+    This function will then call a method of the current class to get
+    the REAL position of this 2nd element in the whole list of
+    properties, shared by many other libraries..
+    And then, the access of the '2nd' element would be transparent to
+    the user.
+
+There is also a GLG_write function based on same principle. They both
+looks like read and write standard C functions, which is absolutely
+natural.
+
+The main difficulty of these functions were that I didn't know in
+which level the efficient read and write should be done. In the
+library engine ? In which level ? Client-side ? Server-side ? If
+ti is in Client-side, how would the server know ? If it is in
+Server-side, how would the Client know ??
+
+So, we decided to keep one dot property tab in each computer (clients
+and server), make all inits, reads and writes in the local computer.
+A first initialisation is made in the server, to know the global size
+of a dot property tab. Then a second is done in each client, which
+returns to the server the total size found. Then the server knows what
+it will allocate for each client.
+Example:
+
+    The server loads libraries A, AC and B. A needs 4 bytes, AC needs
+    3, and B needs 5. The server knows that A and AC will be sent to
+    the client1. Then he allocates 4+3 then 7 bytes to client1, and
+    the 5 last bytes to client2. Client1 receives A and AC, reads them
+    and finds 7 bytes to allocate locally. Client2 will find 5 bytes
+    to allocate locally. After each main loop, client1 will send its 7
+    bytes to the server, who will put them in right place. Client2
+    sends its 5 bytes, and the server puts them in back of the 7 first
+    bytes.
+
+That is trivial. Although this is the network part, I did the routine
+to make that. The source code can be found in
+create_dotproperty_init.cc file. It has to be included in right place
+in the clients and server main functions.
+
+
+  III.3 Main loop
+
+Not yet fully implemented.
+The main loop call is called GLG_Main, and would take as argument a
+Dot* pointer. Then the user has to include the dot.hh header, found in
+the 3d engine directory or in the ./classes folder.
+In this main loop, the user just has to read and write properties in
+the given Dot. The time and other dot-independant informations should
+be given in a method that has not really been specified at this time.
+The read function calls should be done specifiying a library name, and
+the result will be given only if the current library has read access
+to the given one. There, the dependancies takes all its meaning. 
+But why would we do more processing by checking the permissions ? This
+permitts Glagen to be a clean processus.
+However, a library could read its dependancies properties and
+recursively the dependancies of its dependancies. That would look more
+natural in this way.
+Note that there are two 'system' properties, such as primary color and
+primary height of the dot. 'Primary', because one 'dot' should
+represent superposed surfaces' dots.
+Finally, some Perlin noise functions should have been given in this
+level, allowing the user to make realistic world renderings.
+Just see the sun example in our website to be convinced ;)
+
+
+       IV. Conclusion
+
+This part is not yet finished, due to some difficulties to understand
+how would my module work in the global project. The mainloop call
+is not realy finished, but some minor changes have to be done. 
+The main squeletton is already the module itself, so I am globally
+satisfied about my work, although I would be more satisfied if it were
+really included in the final project.
+Since it is under GPL, I would not abandon it. I spent too much time
+on it to give forfeit. Without the pressure of the school, I would
+certainly end my module and best it in great state of spirit.
+
+The main reason, I think, that I didn't finish my part in time, is
+that I spent to much time on making a clean code. A program that
+doesn't bug without reason. This is the most important to me.
+If I made a code in the only goal to make a finished product, I would
+certainly hav missed lots of bugs, and the final result code would
+have been so awful I would never continue it.
+did