ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Better README with catchy design goals and stuff.

pull/278/head
Vladimír Vondruš 13 years ago
parent
fe3a73aab2
commit
8b7c21cef9
2 changed files with 111 additions and 74 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 87
      README.md
  2. 98
      doc/mainpage.dox

87
README.md
Unescape View File

@ -1,30 +1,60 @@
Magnum is 3D graphics engine written in C++11 and OpenGL 3 Core Profile. Magnum is 2D/3D graphics engine written in C++11 and OpenGL 3 Core Profile.
Features:
DESIGN GOALS
* Easy-to-use templated mathematical library for matrix/vector calculations ============
and geometry.
* Classes wrapping OpenGL objects and simplifying their usage - shaders, * **2D is not an ugly stepchild**
buffers, meshes and textures. Access to framebuffer and occlusion queries. Many engines out there are either purely 2D or 3D and if you want to do
* Mesh tools for cleaning, optimizing and generating meshes, utility classes your next project in 2D only, you have to either relearn another engine
for color conversion, timeline and profiling. from scratch or emulate it in 3D, leaving many things overly complicated.
* Hierarchical scene graph which supports transformation caching for better Magnum treats 2D equivalently to 3D so you can reuse what you already
performance, physics library for collision detection and rigid body learned for 3D and even combine 2D and 3D in one project.
dynamics.
* Plugin-based data exchange framework for importing image, mesh, material * **Forward compatibility**
and scene data in various formats. If newer technology makes things faster, simpler or more intuitive, it is
* Collection of pre-made graphic primitives and shaders for testing purposes. the way to go. If you then really need to, you can selectively backport
* Classes for creating OpenGL-enabled applications with various toolkits, some features and it will be easier than maintaining full backward
methods for querying supported OpenGL version and available extensions. compatibility by default. Magnum by default relies on decent C++11 support
* Comprehensive use of C++11 features for safety, performance and ease of and modern OpenGL features, but compatibility functions for older hardware
development. All code which doesn't directly interact with OpenGL is and compatibility branch for older compilers are available if you need
covered with unit tests. them.
* Actively maintained Doxygen documentation. Occasionally updated snapshot is
also available online at http://mosra.cz/blog/magnum-doc/ . * **Intuitive, but not restrictive API**
Scripting languages are often preferred to C/C++ because they tend to do
more with less -- less complicated APIs, nicer syntax and less boilerplate
code. Magnum is designed with scripting language intuitivity in mind, but
also with speed and static checks that native code and strong typing
offers. Usually the most common way is the most simple, but if you need
full control, you can have it.
* **Extensible and replaceable components**
If you want to use different mathematical library for specific purposes,
that new windowing toolkit, your own file formats or another physics
library, you can. Conversion of data between different libraries can be
done on top of pre-made skeleton classes, support for file formats is done
using plugins and platform support is done by writing simple wrapper class.
FEATURES
========
* Actively maintained Doxygen documentation with tutorials and examples.
Snapshot is available at http://mosra.cz/blog/magnum-doc/.
* Vector and matrix library with implementation of complex numbers,
quaternions and their dual counterparts for representing transformations.
* Classes wrapping OpenGL and simplifying its usage with direct state access
and automatic fallback for unavailable features.
* Extensible scene graph which can be modified for each specific usage.
* Plugin-based data exchange framework, tools for manipulating meshes,
textures and images.
* Integration with various windowing toolkits and also ability to create
windowless contexts.
* Pre-made shaders, primitives and other tools for easy prototyping and
debugging.
INSTALLATION INSTALLATION
============ ============
You can either use packaging scripts, which are stored in package/ You can either use packaging scripts, which are stored in `package/`
subdirectory, or compile and install everything manually. Note that Doxygen subdirectory, or compile and install everything manually. Note that Doxygen
documentation (see above or build your own using instructions below) contains documentation (see above or build your own using instructions below) contains
more comprehensive guide for building, packaging and crosscompiling. more comprehensive guide for building, packaging and crosscompiling.
@ -38,7 +68,7 @@ Minimal dependencies
* **CMake** >= 2.8.8 (needed for `OBJECT` library target) * **CMake** >= 2.8.8 (needed for `OBJECT` library target)
* **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL) * **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL)
* **Corrade** - Plugin management and utility library. You can get it at * **Corrade** - Plugin management and utility library. You can get it at
http://github.com/mosra/corrade or at http://mosra.cz/blog/corrade.php. https://github.com/mosra/corrade.
Compilation, installation Compilation, installation
------------------------- -------------------------
@ -85,12 +115,11 @@ PLUGINS AND EXAMPLES
==================== ====================
Various importer plugins for image and 3D model formats are maintained in Various importer plugins for image and 3D model formats are maintained in
separate repository, which can be found at separate repository, which can be found at https://github.com/mosra/magnum-plugins.
http://github.com/mosra/magnum-plugins .
There are also examples of engine usage, varying from simple *Hello There are also examples of engine usage, varying from simple *Hello World*-like
World*-like example to more advanced applications, such as viewer for complex example to more advanced applications, such as viewer for complex 3D models.
3D models. Example repository is at http://github.com/mosra/magnum-examples . Example repository is at https://github.com/mosra/magnum-examples.
CONTACT CONTACT
======= =======

98
doc/mainpage.dox
Unescape View File

@ -25,59 +25,67 @@
namespace Magnum { namespace Magnum {
/** @mainpage /** @mainpage
%Magnum is 3D graphics engine written in C++11 and OpenGL 3 Core Profile. %Magnum is 2D/3D graphics engine written in C++11 and OpenGL 3 Core Profile.
Features:
@section mainpage-design-goals Design goals
- Easy-to-use templated @ref Math "mathematical library" for
@ref matrix-vector "matrix/vector calculations" and - **2D is not an ugly stepchild**
@ref Math::Geometry "geometry". Many engines out there are either purely 2D or 3D and if you want to do
- Classes wrapping OpenGL objects and simplifying their usage - your next project in 2D only, you have to either relearn another engine
@ref AbstractShaderProgram "shaders", @ref Buffer "buffers", from scratch or emulate it in 3D, leaving many things overly complicated.
@ref Mesh "meshes" and @ref AbstractTexture "textures". Access to %Magnum treats 2D equivalently to 3D so you can reuse what you already
@ref Framebuffer "framebuffer" and @ref AbstractQuery "occlusion queries". learned for 3D and even combine 2D and 3D in one project.
- @ref MeshTools "Mesh tools" for cleaning, optimizing and generating meshes,
utility classes for @ref Color.h "color conversion", @ref Timeline "timeline" - **Forward compatibility**
and @ref DebugTools::Profiler "profiling". If newer technology makes things faster, simpler or more intuitive, it is
- Hierarchical @ref SceneGraph "scene graph" which supports transformation the way to go. If you then really need to, you can selectively backport
caching for better performance, @ref Physics "physics library" for collision some features and it will be easier than maintaining full backward
detection and rigid body dynamics. compatibility by default. %Magnum by default relies on decent C++11 support
- Plugin-based @ref Trade "data exchange framework" for importing image, mesh, and modern OpenGL features, but compatibility functions for older hardware
material and scene data in various formats. and compatibility branch for older compilers are available if you need
- Collection of pre-made @ref Primitives "graphic primitives" and them.
@ref Shaders "shaders" for testing purposes.
- Classes for creating OpenGL-enabled applications with @ref Platform - **Intuitive, but not restrictive API**
"various toolkits", methods for querying Scripting languages are often preferred to C/C++ because they tend to do
@ref Context "supported OpenGL version and available extensions". more with less -- less complicated APIs, nicer syntax and less boilerplate
- Comprehensive use of C++11 features for safety, performance and ease of code. %Magnum is designed with scripting language intuitivity in mind, but
development. All code which doesn't directly interact with OpenGL is also with speed and static checks that native code and strong typing
covered with unit tests. offers. Usually the most common way is the most simple, but if you need
full control, you can have it.
The engine is meant to be run on OpenGL 3 capable hardware, but most of the
functionality is working on OpenGL 2.1 hardware too. The engine can be built - **Extensible and replaceable components**
also for OpenGL ES with limited functionality. See also @ref required-extensions. If you want to use different mathematical library for specific purposes,
that new windowing toolkit, your own file formats or another physics
@section download-build Downloading and building Magnum library, you can. Conversion of data between different libraries can be
done on top of pre-made skeleton classes, support for file formats is done
using plugins and platform support is done by writing simple wrapper class.
@section mainpage-features Features
- Vector and matrix library with implementation of complex numbers,
quaternions and their dual counterparts for representing transformations.
- Classes wrapping OpenGL and simplifying its usage with direct state access
and automatic fallback for unavailable features.
- Extensible scene graph which can be modified for each specific usage.
- Plugin-based data exchange framework, tools for manipulating meshes,
textures and images.
- Integration with various windowing toolkits and also ability to create
windowless contexts. Ported to OpenGL ES and various platforms.
- Pre-made shaders, primitives and other tools for easy prototyping and
debugging.
@section mainpage-download-build Downloading and building Magnum
Guide @ref building "how to download and build Magnum" on different platforms. Guide @ref building "how to download and build Magnum" on different platforms.
@section getting-started Getting started @section mainpage-getting-started Getting started
To get up and running, you must first subclass one of the provided window
context classes and implement required functions. %Magnum provides
implementations for the most common toolkits (such as GLUT, Xlib, or SDL2) in
Platform namespace.
Then you can either draw your meshes directly or use SceneGraph which will
help you with object hierarchy, transformations and resource management.
@subsection getting-started-examples Tutorials and examples
The best way to get started is to render your first triangle in The best way to get started is to render your first triangle in
@ref example-index "step-by-step tutorial". Then you can dig deeper and try @ref example-index "step-by-step tutorial". Then you can dig deeper and try
other examples, read about @ref features "fundamental principles" in the other examples, read about @ref features "fundamental principles" in the
documentation or start experimenting on your own! documentation or start experimenting on your own!
@subsection getting-started-hacking Hacking Magnum @section mainpage-hacking Hacking Magnum
If you want to hack on this engine, if you spotted a bug, need an feature or If you want to hack on this engine, if you spotted a bug, need an feature or
have an awesome idea, you can get a copy of the sources from GitHub and start have an awesome idea, you can get a copy of the sources from GitHub and start
@ -93,7 +101,7 @@ Feel free to get more information or contact the author at:
- E-mail - mosra@centrum.cz - E-mail - mosra@centrum.cz
- Jabber - mosra@jabbim.cz - Jabber - mosra@jabbim.cz
@section license License @section mainpage-license License
%Magnum is licensed under MIT/Expat license: %Magnum is licensed under MIT/Expat license:

Write Preview
Loading…
Cancel
Save