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 3DSIA-Server, also called Matrix Daemon.

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

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. Altered specifications will be added to the request for proposal and will be handed in later.


2.2. The Matrix Daemon (The Server)



2.2.1. Short Definition





2.2.2. Detailed Definition



System Daemon

Sets up and manages environment

Sets up and maintains connections

Run Applications

System Logging


2.2.3. Internal Construction



Main

Matrix-Control Thread

Construction Thread

User-Control Thread

User Thread

Communication Thread

Server Control Thread

2.2.4 Proceedings during runtime



Main() creates

and waits until all those threads exit.

The User Control Thread is actually the "boss thread" that delegates all work that has to be done. The UCT listens for connections on the port. A new connection results in the creation of a new thread, the User Thread.

The UT creates two more threads, the in- and the output thread. Additional the UT creates an in- and an output buffer, which are used for communication between the UT and its Communication Threads. (The Buffer is a first in first out stack.)

The User Thread is responsible for routing all data from the Control Threads to the destination modules. (This is specified in the Communication Documentation)

When a request for the change of a room comes in, the UT sends the Matrix Control Thread a message.

The MCT then builds, for each request a new one, the Construction Thread, which is responsible for building up the matrix for the requested directory. Utilizing fork, it probes using the UID of the user if there is access permission and then collects all needed data to construct the matrix-sector.

There are two ways to perform:
  1. The Construction Thread informs the Matrix Control Thread when the construction is finished, which then informs the User Thread that it now can read from the matrix-sector.
  2. The Constructino Thread writes to the output buffer of the User Thread and to the matrix sector at once.
    Advantage for 1) It is a clean way to do.
    Advantage for 2) The user does not need to wait, and receives the room bit for bit while it is beeing constructed.


    2.3. The Client


    The client can also be described as a visualization engine with enhanced functionality.

    Its main purpose is to visualize the data received from the server and to transfer to the server all data it requires.

    The clients structures consists of 6 main function groups.

    The Communication, User Input, Task Control, Avatar, Matrix and Visualization functions.


    2.3.1. Communication


    The Communication functions are responsible, as the name says, for communication with the server. They handle the handshake, the authentication process and during runtime all network transfers. Furthermore it is responsible for decoding the packages and transferring the data to the destination modules and functions.


    2.3.2. User Input


    The purpose of the User Input functions are 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 Task 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.


    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.

    2.3.5. The Matrix


    The Matrix is the place where everything happens. It is in fact a copy of the current User Matrix, which is stored and maintained on the server. The local and remote User Matrix can be viewed as almost identical, as all alterations are updated on server and of course client-side. Whereas the server stores many Matrixes the client only stores one matrix, which is the current user context.

    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.7. Explanation of proceedings during runtime


    The Communication Thread initiates the connection to the server. After the handshake and the authentication it receives following data packages:

    The client connects to the server and receives at opening its start coordinates and the position in the environment (System Entry). Following this the server starts describing the environment by transmitting immediately relevant information in binary coded script language.

    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.


    3. Interfaces



    will be handed in immediately when finished.

    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. Communication


    POSIX IPC is used for inter process communication. It provides a fast way of internal communication between local processes.

    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:
      • Name of the file
      • Developer who created the file
      • Date
      • Purpose of the included functions
      • List of developers who contributed to the file
      • Date when contributed.
      • Character of contribution, details, function

      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/bin.
    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.

    During the development, all entries have to be written in separated log- files in the following format:

    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