Select Git revision
doxygen_index.h
Forked from
einsteinathome / graphicsframework
145 commits behind the upstream repository.
-
Oliver Bock authored* Added section "Supported Platforms" * Added section "Libraries used" * Added libraries to "Requirements" * Added a note where to find the compiled executable ;-)
Oliver Bock authored* Added section "Supported Platforms" * Added section "Libraries used" * Added libraries to "Requirements" * Added a note where to find the compiled executable ;-)
doxygen_index.h 10.97 KiB
/**
* \mainpage Overview
*
* \section cha_intro Introduction
*
* This application is part of the Einstein\@Home project and aims to provide an extensible, refurbished version of
* the well-known %Starsphere graphics application (screensaver).
* \n
* The new version focuses on the following topics:
*
* - Refurbished visuals and extended features
* - Generalized API for community-driven implementations
* - %Resource embedding (e.g. fonts, images)
* - Migration from GLUT to SDL
* - Self-consistent build script (Linux, Mac OS X, Windows/MinGW)
* - Full doxygen documentation
*
* \subsection sec_status Current Status
*
* The graphics application is currently in its beta stage and has still to be considered as work-in-progress.
* This means that not all desired features are fully implemented yet and the code might still contain some bugs.
* However, we think the application is stable enough to be used on a daily basis. You're invited to test and
* discuss the current version at the Einstein\@Home
* \htmlonly<a href="http://einstein.phys.uwm.edu/forum_forum.php?id=3">\endhtmlonly
* Cruncher's Corner
* \htmlonly</a>\endhtmlonly.
*
* The most important feature that's not fully supported right now is the persistent configuration of the graphics
* application. It is intended to let users customize the application's options using the BOINC project preferences.
* However, in order to do this we have to change our project's server setup and configuration web pages. This task
* is still pending but is scheduled for August/September 2008. As soon as these changes are completed users will be
* able to set the following options:
*
* - Common options:
* - Window width (default: 800 pixels)
* - Window height (default: 600 pixels)
* - Frame rate (default: 20 fps)
* - Quality (default: low / also available: medium, high)
* - %Starsphere options:
* - Enabled screen elements (see \ref sec_app_usage)
*
* Please note that we're using conservative default values (for the common options) to ensure that the graphics
* applications runs with reasonable CPU consumption on most systems. This means that the visual improvements are
* \b not activated and the graphics look more or less the same as before. If you have hardware accelerated 3D
* support on your machine please feel free to increase the settings as soon as the web pages mentioned above become
* available. For example: on a recent Linux PC the %Starsphere application consumes less than 10% CPU power when
* running at typical desktop resolutions (e.g. 1280x1024), 30 frames per second and high quality.
*
* \subsection sec_platforms Supported Platforms
*
* The binary versions as well as the build script support the following platforms:
* - Linux (Intel, 32 Bit)
* - Windows (Intel, 32 Bit, cross compiled with MinGW)
* - Mac OS X (Tiger/Leopard, Intel/PowerPC, 32 Bit)
*
* \subsection sec_future The Future
*
* - Community involvement: build and share \b your \b own graphics application!
* - Provide different backgrounds and search visualizations
* - Full Linux screensaver support (X11, KDE, Gnome)
* - True XML support (libxml2 integration)
* - Help dialog (on screen display)
*
* \section sec_doc_user User Documentation
*
* \subsection cha_app Starsphere Graphics Application
*
* \subsubsection sec_app_overview Overview
*
* The new %Starsphere application is based on the original version currently shipped with Einstein\@Home. * For more information about what it shows please refer to our
* \htmlonly<a href="http://einstein.phys.uwm.edu/starsphere.php">\endhtmlonly
* project page
* \htmlonly</a>\endhtmlonly.
* \n
* With regard to features the following extensions have been made so far:
* - The VIRGO interferometer is shown (in white) at 43°37'53"N and 10°30'18"E
* - The celestial globe is displayed indicating latitude, longitude and the projected Greenwich Meridian
* - The different screen elements can be toggled separately
*
* \subsubsection sec_app_usage Usage
*
* When the graphics application is started in standalone mode (as opposed to screensaver mode)
* you can control the graphics interactively using mouse and keyboard.
*
* Use the following keys to control the application:
* - \c ENTER: Toggle fullscreen mode
* - \c ESC: Exit the application
*
* Use your mouse to modify the 3D rendering (click & drag):
* - Left button: Rotate the sphere
* - Right button: Zoom in or out
*
* Use the following keys to toggle single screen elements:
* - \c S: Stars
* - \c C: Constellations
* - \c P: Pulsars
* - \c R: Supernova Remnants
* - \c X: X-Ray Binary Systems
* - \c O: Observatories
* - \c M: Search Marker
* - \c I: Search Information
* - \c G: Globe
* - \c L: Logo
*
* Available command line options:
* - Screensaver mode (mouse and keyboard control deactivated!): \code --fullscreen \endcode
*
* \subsubsection sec_app_install Installation
*
* You don't have to install the graphics application yourself as it's distributed alongside
* Einstein\@Home.
*
* \section sec_doc_dev Developer Documentation
*
* \subsection cha_frame Graphics Application Framework
* \subsubsection sec_frame_overview Overview
*
* The Framework takes care of the following things:
*
* - Window management
* - OpenGL 3D context management
* - Event handling (mouse, keyboard)
* - Interface to BOINC application
* - Interface to Einstein\@Home science application
*
* For a detailed description of the available classes and interfaces please refer to the
* \htmlonly<a href="annotated.html">\endhtmlonly
* class list
* \htmlonly</a>\endhtmlonly.
*
* \subsection cha_orc Open Resource Compiler
*
* \subsubsection sec_orc_overview Overview
*
* The resource compiler is a very simple tool that converts binary resource files like images or fonts into plain C++ source
* code which can subsequently be compiled and linked to the executable. This way you can integrate any resource into your
* binary which no longer depends on external files, hence facilitates later distribution. For a detailed description please
* have a look at the ResourceCompiler class.
* * \subsubsection sec_orc_usage Usage
*
* -# Create a resource specification file
* -# Run the resource compiler (\c orc) to convert the resources into source code
* -# Include the generated source file in your project (compile and link it to the main executable)
* -# Use ResourceFactory to instantiate a Resource object (loads the binary resource data into memory)
* -# Use the Resource instance to retrieve a pointer to the resource's raw data
*
* %Resource specification file format:
* - Simple text file (*.orc)
* - Each line describes one resource
* - The descriptor has to look like this: \c LogicalResourceName|PhysicalResourceName
* - \c PhysicalResourceName is the actual file name of the resource
* - Lines starting with # are treated as comments
* - Empty lines are ignored
*
* Command line calling convention:
* \code orc <InputSpecFileName> <OutputCodeFileName> \endcode
* - \c InputSpecFileName: The name of the resource specification file (input)
* - \c OutputCodeFileName: The name of the resource code file (output)
*
* \subsection cha_source Source Code Access
*
* Please use this \htmlonly<a href="http://einstein.phys.uwm.edu/graphics/src/graphics_framework_src_0.1.tar.gz">\endhtmlonly
* link
* \htmlonly</a>\endhtmlonly
* to download the source code distribution (tarball).
*
* You may also check out the source code from our CVS repository:
* \code
* cvs -d:pserver:anonymous@gravity.phys.uwm.edu:2402/usr/local/cvs/lscsoft login
* cvs -z3 -d:pserver:anonymous@gravity.phys.uwm.edu:2402/usr/local/cvs/lscsoft co -P einsteinathome/graphics
* \endcode
*
* \subsection cha_build Build Script
*
* \subsubsection sec_build_overview Overview
*
* The (very simple) build script tries to compile binaries for all supported platforms without depending
* on any additional library being installed on the build machine. The only requirements are a properly
* installed and configured build system based on the GNU Compiler Collection Version 4, a few common
* library development packages and a working (direct) connection to the internet.
* Everything else is subsequently downloaded, configured and compiled automatically by the script.
*
* \subsubsection sec_build_provided Libraries used (provided automatically)
*
* - SDL - Simple DirectMedia Layer
* - FreeType 2 - High-quality glyph images
* - OGLFT - OpenGL-FreeType Library
* - BOINC (Graphics/API)
*
* \subsubsection sec_build_requirements Requirements
*
* Please make sure the following development packages (headers/libs) and tools are available to the build script
* (note: the following package names refer to Debian only, your distribution's package names might vary):
*
* - Common libraries (mostly required by SDL):
* - libc6-dev
* - zlib1g-dev
* - Libraries for Linux and Windows/MinGW (required by SDL):
* - libgl1-mesa-dev | nvidia-glx-dev
* - libglu1-mesa-dev
* - libxt-dev
* - libxext-dev
* - libaudio-dev
* - Libraries for Mac OS X (required by SDL, provided by XCode):
* - OpenGL Framework
* - Cocoa Framework
* - Carbon Framework
* - QuickTime Framework * - ApplicationServices Framework
* - AudioToolbox Framework
* - AudioUnit Framework
* - IOKit Framework
* - Tools:
* - bash
* - gcc / g++
* - automake
* - autoconf
* - m4
* - cmake
* - wget
* - cvs
* - svn
* - ld
* - libtool
* - ar
* - lex (i.e. flex)
* - yacc (i.e. bison)
* - doxygen (optional)
*
* \subsubsection sec_build_usage Usage
*
* In order to use the script you just have to navigate to the \c graphics directory
* in the Einstein\@Home source tree and run the script passing as an argument the desired target platform
* (you'll find the compiled executable \c starsphere in the \c install/bin directory):
*
* - Linux build: \code build.sh --linux \endcode
* - Mac OS X build: \code build.sh --mac \endcode
* - Windows build (uses MinGW cross-compile with Linux as build system!): \code build.sh --win32 \endcode
*
* Additional tools are provided as follows:
*
* - Build this documentation (requires doxygen): \code build.sh --doc \endcode
* - Purge build tree: \code build.sh --distclean \endcode
*
* \section cha_license License
* \verbatim
Copyright © 2004 Bruce Allen, David Hammer, Eric Myers
Copyright © 2008 Oliver Bock, Bernd Machenschalk
This application/framework is part of Einstein@Home.
Einstein@Home is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
by the Free Software Foundation, version 2 of the License.
Einstein@Home is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with Einstein@Home. If not, see <http://www.gnu.org/licenses/>.
\endverbatim
*/