The 3dsia Project


Request for proposal
Authors: Jan Brodacz, Alexander Feder & Gerald Scheidl
Date: 99/12/15
Rev: 0.1.0



Index

  1. GOALS
    1. PURPOSE OF THE PRODUCT
      1. Introduction
    2. USERS
      1. Leading idea
      2. Target group
  2. FUNCTIONS
    1. IDEA
    2. THE MATRIX DAEMON (THE SERVER)
      1. Short Definition
      2. Detailed Definition
      3. Internal Construction
      4. Detailed Construction
    3. THE CLIENT
      1. Communication
      2. User Input
      3. Task Control
      4. The Avatar
      5. The Matrix
      6. Visualization
      7. Explanation of proceedings during runtime
  3. INTERFACES
  4. REQUIREMENTS
    1. MEMORY REQUIREMENTS
      1. Server Side
      2. Client Side
    2. HARDWARE REQUIREMENTS
      1. Server Side
      2. Client Side
    3. OPERATION SYSTEM
    4. USED LIBRARIES
      1. Graphic
      2. OS Related
      3. Communication
      4. Security
  5. QUALITY DEMANDS
    1. USABILITY
      1. A day in the life of a user
      2. Comments
    2. RELIABILITY
    3. EFFICIENCY
    4. MAINTAINABILITY
    5. EXTENDIBILITY
    6. PORTABILITY
  6. IMPLEMENTATION CONDITIONS
    1. HARDWARE
    2. OPERATING SYSTEM
    3. USED STANDARD SOFTWARE
    4. PROGRAMMING LANGUAGES
    5. TOOLS
    6. STYLE OF SOURCE-CODE
      1. Definitions
      2. Function-names
      3. Variable-names
      4. Spaces and Brackets
      5. Comments and Descriptions
      6. Directories and Filenames
  7. DOCUMENTATION
    1. LAYOUT OF DOCUMENTATION
      1. Headers/Footers
      2. Fonts / Size
      3. Headlines
      4. Examples
      5. Glossary Words
    2. PROJECT DOCUMENTATION
    3. LANGUAGE OF DOCUMENTATION
    4. SPECIFICATIONS FOR INLINE-DOCUMENTATION
    5. METHODS OF DOCUMENTATION


1. Goals



1.1. Purpose of the Product


1.1.1. Introduction

As we live in a three-dimensional world, our abilities are perfectly designed to work best and most efficient in a three dimensional environment. Limitations in the past have made us think, that the only effective way of processing data would be in a two dimensional form, but this is simply not true.

New technologies open a new chapter in human history, as we leave our real world and immerse into a complete artificial environment that enables us to exploit most of our abilities using utilities that interact with us and don't demand to be interacted with.

Yet there is a long way to go. At the moment, affordable computer systems just provide a minimum of the computation power necessary to process all data needed in real-time, hence the graphical environment will not look like reality in the first steps.

However, as the computation power rises, the graphical detail does, and thus makes the system more appealing to the user.



1.2. Users



1.2.1. Leading idea



The User is the most important factor in the development of our product, instead of, as the so often sad history of graphical user interfaces teaches us, trying to force the user to adapt to complete new environments, which have no patterns of reality in any form. Windows, buttons, dialogs, cryptic error codes. We all know those forms too well.

But we got used to it, hence we accepted it as the only way of working. Of course, in the past, other forms would have been impossible, but now, as computation power reached a mark where all those chains that prevent efficient working could have been broken already.

Now, the 3Dsia System will enable the user to exploit the ability humans are best in: Intuition.

1.2.2. Target group


Of course, everybody can make use of the 3Dsia System in any thinkable way, but there is group of people who can exploit the system best: They are the System Administrators, Coders, Visual and Musical Artists, Analytical Data Examiners, Engineers and of course Gamers and probably many many more.


2. Functions



2.1. Idea


The main idea of the 3Dsia System is to provide a multi-user environment, that can be accessed either locally or over any distance in LANs or the Internet, using the needed protocols specified by POSIX [1] standard and TCP/IP provided by the operation system. In general, the 3Dsia System aims to make use of any operation system functionality wherever it makes sense, such as the utilization of fully multitasking and various security issues.

The computer to be visualized hosts the Matrix Server. Requests for a specific resource are handled by the 3Dsia Daemon.


Leading Idea 

/*--------------------------------------

hier das picture vom layer aufbau

und das verhältnis server/client

---------------------------------------*/

[hacker ignore it please]

As the system is based on server/client methods, we need to specify those parts separately.

We cannot describe each function separately, as the 3Dsia is a virtual reality system, comparable to an operating system, and not a sequential program with user input functions, error-messages, output functions or structured layouts.

The idea of the description of features differs extremely from historical user-programs as the 3Dsia system itself differs extremely from historical user interface methods in general.

[/hacker]

Since the 3Dsia Project starts as a design study, some specifications will for sure be altered during the development process.


2.2. The Matrix Server



2.2.1. Short Definition





2.2.2. Detailed Definition



Object Request Broker Provides the Matrix
Starts Applications

System Interface and Logging


Maintains the Client-Stub


2.2.3. Internal Construction



Server Chart - Overview
Main

Client-Control Thread

Client Thread

Communication Threads

Matrix Thread

2.2.4 Proceedings during runtime



Main() creates

and waits until all those threads exit (which won't happen ever).
The Matrix Thread creates an empty matrix and tells the root application to fill it. Deamon muss es der root appl. sagen. the matrix thread remains passive.
The Client Control Thread creates the Client Thread when a Client connects to the server.
The CT creates two more threads, the in- and the output thread. Additional the CT creates an in- and an output buffer, which are used for communication between the CT and its Communication Threads. (The Buffer is a first in first out stack.) The incoming buffer is also used by the matrix thread to send data to the client stub. After the authentication the CT send the matrix a register-entity message. An entity is a special object type which will be specified later. Then it switches to passive mode and waits to process requests to the client.

2.3. The Client



Introduction

As the leading idea nr 8 says
a client can be almost anything.

This section will just discusses the client which is used by humans.

The client can also be described as a visualization engine with enhanced functionality.
Its main purpose is to visualize the data received from the Client Stub, to process the user-input and to send the Client Stub all data it requires.

The client's structure consists of 6 to n main Threads



2.3.1. Communication Threads


The Communication Threads consist of an outgoing and incoming thread and are responsible, as the name says, for communication between the client and the Client Stub on the server. The outgoing thread handles the handshake and during runtime all network transfer. Furthermore it is responsible for decoding the packages and transferring the data to the Matix Thread.


2.3.2.Input Thread


The purpose of the Client Input Thread is firstly to wait for any incoming data on the defined input-handlers (either the GLUT [6] Input Functions for Mouse and Keyboard or other modules written for special devices), and secondly to wrap the input into commands for the Core Thread.
DA GEH™RT NOCH WAS HER!!!

2.3.3 Output Thread


The Output Thread has three main responsibilties

2.3.6. Visualization


The Visualization is responsible to render all visible objects, using the view-port defined by the Avatar. The Visualization engine just translates the binary packages into OpenGL [5] codes.

2.3.5. The Matrix Thread


The Matrix Thread holds all objects that have been requested by the server.
HIER GEH™RT AUCH NOCH WAS HER!!!!!!!!!!!!!!!

2.3.7. Explanation of proceedings during runtime


The Core Thread initiates the connection to the server. After the handshake and the authentication the client-stub on the server asks the matrix to register the client as an entity. Then the returned ID of this entity is used by the client to control the avatar.

Following, the Quarz Thread begins to send update-requests, through the outgoing buffer, to the Client Thread.
These updates were queried by the Core Thread (from the incoming buffers), and forwarded to the Matrix Thread.
Finally, the Quarz in the Visiualisation Thread, or additionally another plugin request the updates from the Matrix.

During runtime, the client transmits position changes of the avatar to the server.

The client receives the geographical data in the form of small data-grams, 3Dsia Protocol encoded. Those packages are interpreted by the object-parser in real-time. Thus the user gets the impression of a "filling" world over some seconds (to minutes, depending on the bandwidth).

The client connects all received objects to the local matrix, the one matrix the client works with.

Objects which are completely described can be interacted with using simple action commands. Those action commands could be shell commands which perform a special visualization. The command "copy" for example, duplicates the object visually and the client just transmits a plain shell command to the server.

The visualization and navigation mechanisms are kept extremely simple. The received object and world describing packages contain binary encoded OpenGL commands, which are stored in the various matrix- nodes. The matrix itself is in fact a collision detection template and a volume clipping map, a simple buffer-structure, a floor for the cyberspace room.

The user controls the avatar using any input device. The avatar is an object in the matrix and it defines the view-port of the 3D rendering.


System Daemon

Sets up environment

Sets up and maintains connections

4. Requirements



4.1. Memory Requirements



4.1.1. Server Side


Concerning the Runtime-Memory, there is one rule: As much as possible. The more memory the 3Dsia System is able to access, the faster the access-times and the more users can be served at the same time.

Space used on Hard-disk differs extremely, depending on how many standard textures and objects, predefined and designed rooms, possible stored User-data, code plug-ins and so on are stored locally. It ranges from about less than one megabyte up to more than a gigabyte.


4.1.2. Client Side


The space used as Runtime-Memory differs depending on the size of the room, the number of running background-processes started by the 3Dsia client and the detail of graphics.

The used space on Hard-disk depends on various factors such as how many standard textures and objects, stored User-data, code plug-ins and so on are stored locally. It ranges from about less than one megabyte up to more than a gigabyte.

4.2. Hardware Requirements



4.2.1. Server Side


To be able to provide all connected clients with sufficient data, such as geographical and object-related 3D-Data, the server needs at least following components: (for about 4 users)

4.2.2. Client Side


The client needs to be a fast machine that is able to render 3D-Graphics in real-time. As this is the most processor intensive task, following components are required as a minimum configuration:

4.3. Operation System


The operating system of our choice is GNU/Linux, the free and most stable operating system available for personal computers. GNU [8] As it is a fully compatible UNIX, the 3Dsia System will run on any UNIX- Implementation with minor changes, such as IRIX, Solaris, FreeBSD and more. As the development uses standards like POSIX, a port to other non- UNIX operating systems is very likely, such as BeOS, MacOS and even Windows.

4.4. Used Libraries



4.4.1. Graphic


The used Graphic-Library is OpenGL. The implementation of use is Mesa, a free product available on most platforms. (UNIX as well as non-UNIX). Furthermore SGI GLUT is used which is a toolkit that makes the Code more portable. OpenGL is the product of an industry consortium built by worlds major software companies.

4.4.2. OS Related


The pthreads [2] library (POSIX Threads) for multithreading is used, which enables the server to run on multiprocessor systems efficiently, but also increases the performance on single-processor systems.

POSIX Signal API for UNIX signal handling.


4.4.3. Database


The 3Dsia system uses the ODB (Object DataBase) library from Manfred Morgner, a member of the 3Dsia developer team. His database concept suids perfectly our needs.


4.4.3. Communication


TCP/IP is used for network-communication, when the server and client are not on the same machine. Furthermore it enables the server to act as a multi-user system.

4.4.4. Security


For many reasons, the PAM API (Pluggable Authentication Modules) might be used for the use of user authentication.
It provides an authentication system, where any method can be chosen. That could be for example: All those methods and much more are possible using PAM, without changing a single line in the source code.

5. Quality Demands




5.1. Usability


5.1.1. A day in the life of a user


The program is activated and unfolds, and fills the void with something like a wooden floor. Several pyramids pop out on the right, constructing themselves, slowly growing and building up the scenery, the matrix. Their shape indicates that they are the hidden configuration files I want to work on today.

I wait until the last text scroll I have worked on the whole week materialized and grab it to put it into my storage application. A bird appeared from the distant and moves with funny wooden flaps straight to my position. New mail. I select the bird and place it on hold - the mail can wait. Somehow, I want to work on my home directory, I think I want a new look, and maybe I should clean up a bit. This configuration files will need to have a new place. I cannot put them in a chest, this would create a new sub-node and the system would not find them. I could make a new room and move my system-entry-point, or I simply place them out of sight, in one of the 23 corners of this room. The links for my development environment are not in the right place and the OpenGL-Picture has to be on the wall to the right. Maybe I should write a new room-construction algorithm. Suddenly Mike knocked on my directory and asked for access permission - his thoughts about the room design are highly welcome so I open the room for read-access (thoughts ONLY!). The authentication system tells me that he really is Mike, so I let him materialize. His Avatar appeared in front of my View-port and he passed me a scroll: "Here are the new Matrix sources for the object-exchange concept we talked about." I send it to the CVS-script and gaze at the compiler producing a new plug-in. In the meantime, we start some small-talk "The voice system we implemented last week is really cool...." CVS [9]


5.1.2 Comments


In fact this scene might occur at an early project stage, but things will be a bit more basic in the first place. The visual compiling is surely a way ahead, as well the full plug-in technology won&acc;t be usable before 3rd or 4th quarter of 2000. But as the project will surely be continued after the final exam, it will grow to a fully usable virtual reality system. Basically, the project is a design study of the future of three dimensional cyberspace, which is an abstraction of a UNIX System from a very different perspective.

As an open-source project it is estimated to be picked up and developed, by many members of the internet open-source community, to its full power, which will surely need 2 years. It may influence the future designs of home and business computer systems, as the growing technological complexity opens gates we never dared to thing of.

In the first steps, the interaction speed with the computer will basically not improve, as we firstly cannot focus on design studies for human/computer interaction, secondly the hardware is not advanced enough and thirdly a 3D-System demands special input-devices which are not affordable yet.


5.2. Reliability


One of the most important points the development focuses on is reliability. The system has to be accessed whenever needed, as it will act as the main user-shell in the future.

Reliability is based on three pillars:

5.3. Efficiency


As the 3Dsia System has to share system resources with many applications and services on the system, the kernel, and of course internal threads (graphic, computation and communication threads), each part of the 3Dsia has to be very efficient. Redundant operations or the blocking of system resources is very harmful to a multitasking/multi-user system.

5.4. Maintainability


As the code is Open-Source maintainability is the last thing to worry about. The code will be public, so everyone interested can either look at the code, participate in improving or contribute bug-fixes.

5.5. Extendibility


The system itself might be extendible in three ways:

5.6. Portability


As the perspective of all used libraries is to be as portable as possible, the 3Dsia will be as portable as the libraries are.

6. Implementation Conditions



6.1. Hardware


As long as the development consists of writing the code and creating the main structures of the 3Dsia System, the hardware is not very important, as long as it is capable of 3d-rendering in real time. A Pentium 200 will do this job. When it comes to do complex graphical visualizations, when the system is in use, and many applications run in background, the demand for faster hardware of course will be the result.

6.2. Operating System


The operating system used for development is the same as used for the system itself: Linux, due to its reliable and very economical character. Furthermore all Linux development tools needed are Open Source and thus free of charge.

6.3. Used Standard Software


Following standard software is used for development:

6.4. Programming Languages


The Programming Languages are C and C++, and maybe some scripting language like Perl to simplify conversation with the operating system.

6.5. Tools


Following tools are used for development:

6.6. Style of Source-Code


The style of Source code is a very important chapter in the development of a program, where more then one individual contributes.

6.6.1. Definitions


Definitions of any sort have to be in upper-case characters only, and the meaning of the definition must be clear.

For example: #define SERVER_PORT 1234

6.6.2. Function-names


All function names have to start with a upper-case character and the meaning of the function must be clear.

For example: Create3dsiaObject();

6.6.3. Variable-names


All variable names have to start with a lower case character and the meaning of the function must be clear:

For example: nrOfUsersOnline

6.6.4. Spaces and Brackets


Spaces are very important when it comes to keep the code clear and thus error-free.

The tab-stop has to be 4 characters.

The function name, the function brackets and the arguments have to be separated by one space, except if there is just one numerical argument.

For example:

    if ( whatever == 0 )
        Create3dsiaObject ( pos, name, flags );
Brackets have to be set like following example shows:

for ( i = 0; i < 10; i++ )
    {
    if ( whatever == 0 )
        {
        if ( Create3dsiaObject ( pos, name, flags ) )
            exit (1)
        }
    }

6.6.5. Comments and Descriptions


Commenting is a vital part to keep the code readable and maintainable. Thus there are three important parts where commenting is absolutely necessary:
  1. Header
    There has to be a header in all .c and .cc files, which states following information:

    Example: 
    /*
    network.cc
    Created by: Deve Loper, 9.9.99
    Purpose:    Network functions for server/client
                communication
    Changes:
    Deve Loper,    10.9.99, Bugfix, more then 4 user can
                 connect now simultaneously, LoginFunc()
    Deve Loper,    11.9.99, Added, simple handshake,
                                         HandShakeFunc()
    Cony Tributer, 13.9.99, Bugfix, handshake works now
                                         HandShakeFunc()
    [...]
*/
  2. Functions
    On top of every function should be a header including the creator, the date of creation, the purpose of the function and an explanation of the arguments and return value.

    For example: 
    /*
Create3dsiaObject ( float pos[3], char *name, int flags );
Created by: Deve Loper, 11.10.98
Purpose: Creates a 3Dsia Object and adds it to the
         current User Matrix.
Arguments: float pos[3]: specifies to position in the
                         user matrix
           char *name: the name of the object
           int flags: the various binary flags
                     those are [...]
Return Value: 0 on success
              -1 [...]
*/

  3. Algorithms
    All algorithms or other methods have to be explained step by step if its way of working is not obvious.

6.6.6. Directories and Filenames


The source-tree has to be in /opt/3dsia/src.
Binaries will be stored in /opt/3dsia.
New Functionality means new directory.

For example:
Filenames have to give an idea of the content.

For example:

7. Documentation



7.1. Layout of Documentation


7.1.1. Headers/Footers


On the left side of the header has to be firstly the abbreviation of the 3Dsia ( [3Dsia] ), and in the center the leading topic. On the right side of the header has to be the number of the page. In the footer has to be the name of the author.

7.1.2. Fonts / Size


The font side to use for standard text is Arial 12pt.

7.1.3. Headlines


Main Headlines have to be in Arial 18pt, bold, with leading digits.
Second Level Headlines have to be in Arial 14pt, bold , with leading digits.
Third Level Headlines in Arial 12pt, bold, with leading digits.
Fourth Level Headlines in Arial 12pt bold without leading digits.
Fifth Level Headlines in Arial 12pt plain without leading digits.

7.1.4. Examples


Examples of source code or any specifications have to be in Courier New 12pt.

7.1.5. Glossary Words


Glossary words have to be in Arial 12pt cursive, connected with an index- number in brackets, Arial 10pt:

Example:

The pthreads [1] library (POSIX [2] Threads) for multithreading [1] is used, which enables the server to run on multiprocessor systems efficiently, but also increases the performance on single-processor systems.

The Glossary Index itself has to consist of following elements:

Example:
[1] threads/pthreads/multithreading: Threads are a model for dividing a program into subtasks whose execution can be interleaved or run in parallel. Pthreads are the standardized model of the Threads concept. The P comes from POSIX [2]. Thus, multithreading is a program that makes use of more than one thread. See also: Pthreads programming, O'Reilly
[2] [.....]

7.2. Project Documentation


The project documentation is a vital part in the 3Dsia Development, because of the continuous progress of contribution where it is important to keep track of all enhancement, bug-fixes, add-ons, minor changes in specification and other project-steps.

The log file has to contain following information:

Example:
/*
    Changes in network.cc
    1. Improved performance in encoding and decoding
       routine of PackageHandling().
    2. Changed protocol struct. Added a new integer
       value in [struct ProtocolStruct]

    Changes in server.cc
    [...]
*/

7.3. Language of Documentation


The language of documentation will be English, for two reasons. Firstly, as the project will be an international project in near future, it his highly necessary that all participants understand the content. Secondly, because some members of the project-team want to present the project at the final exam in the English language, and thus it is important to maintain the project in one language.

7.4. Specifications for inline-documentation


As specified in section 6.6.5 (Style of Source-Code/Comments and Descriptions), it is important to explain all non-obvious program routines and algorithms in order to make the code readable to all contributors.

7.5. Methods of Documentation


The documentation can either be in HTML, TXT, RTF or WinWord 95 DOC, since those file-formats are readable by most word-processors on most platforms. Due to the intended portability of the 3Dsia System, the documentation should be readable on all supported platforms.

A. Appendix: Glossary


[1] POSIX: Portable Operating System Interface is the family of the IEEE operating system standards.
[2] POSIX IPC: POSIX Inter Process Communication is a standardized way for processes to communicate between each other.
[3] threads/pthreads/multithreading: Threads are a model for dividing a program into subtasks whose execution can be interleaved or run in parallel. Pthreads are the standardized model of the Threads concept. The P comes from POSIX. Thus, multithreading is a program that makes use of more than one thread. See also: Pthreads programming, O'Reilly
[4] POSIX Signals: A standardized way for the operating system to send a defined set of signals to the processes.
[5] OpenGL: The Open Graphic Library is industry's standard for graphical visualization defined by an consortium built by worlds major software companies such as SGI, IBM and Microsoft.
[6] GLUT: OpenGL Toolkit by SGI to make applications that utilize OpenGL more portable.
[7] MESA: A free implementation of OpenGL developed by Brian Paul.
[8] GNU: GNU is Not Unix, Open-Source Evangelists and maintainers of thousands of important projects.
[9] CVS: CVS is the most commonly used Version Control System.

B. Appendix: Bibliography

Matrix-Control Thread

Construction Thread

Server Control Thread

2.3.3. Task Control


The Task Control is responsible for controlling which task is active and for the transfer of signals and user-input data to those tasks. For example during the authentication process, the authentication routine needs to receive the username and password, which was transferred from the User Input function to the Task Control.


3. Interfaces



will be handed in immediately when finished.

2.3.4. The Avatar



The Avatar represents the User in the System. Thus it fulfils a very important purpose. There are three main tasks.
In the future, when data gloves are affordable, the Avatar will eliminate the Task Control and the User Input functions, as the user then should be able to immerse completely into the matrix, and input has not to be shifted from one task to another, as the hands themselves define which process receives the input data.