[colobot] 18/74: Import documentation from old dev wiki
Didier Raboud
odyx at moszumanska.debian.org
Mon Nov 7 07:50:00 UTC 2016
This is an automated email from the git hooks/post-receive script.
odyx pushed a commit to branch debian/master
in repository colobot.
commit c03d8beb8bc501f5c660ed843b1205d23484e6d4
Author: krzys-h <krzys_h at interia.pl>
Date: Fri Aug 5 16:55:10 2016 +0200
Import documentation from old dev wiki
I also updated all outdated information I could find, please tell me if I missed something
Model format documentation needs an update
---
CONTRIBUTING.md | 67 +++++++++++++++--
Doxyfile.in | 2 +-
INSTALL-MSYS2.md | 161 +++++++++++++++++++++++++++++++++++++++++
INSTALL.md | 4 +-
README-dev.md | 99 +++++++++++++++++++++++++
docimg/2d_coord.png | Bin 0 -> 4983 bytes
docimg/3d_canonical_coords.png | Bin 0 -> 10961 bytes
docimg/README.txt | 1 +
src/app/main.cpp | 31 +++++---
src/graphics/README.txt | 45 ++++++++++++
src/graphics/model/README.txt | 82 +++++++++++++++++++++
11 files changed, 475 insertions(+), 17 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c0b7871..030b439 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,9 +3,11 @@
So you want to contribute to Colobot: Gold Edition? That's awesome! Before you start, read this page, it contains a lot of useful information on how to do so.
## General information
-Before you start, read more about technical details of the project. They can be found in our [Game Design Document](http://compiled.colobot.info/jenkins/job/colobot-gold-gdd/lastSuccessfulBuild/artifact/Colobot_Gold_Edition-Game_Design_Document.pdf) ([live editor](http://krzysh.pl:3000/project/545e90d99e8bceed2284797e)).
+Before you start, read more about technical details of the project. They can be found in:
-You may also find some useful information on the our (outdated) [dev wiki](http://colobot.info/wiki/dev).
+* [Developer README](README-dev.md)
+* [Doxygen documentation](http://compiled.colobot.info/job/colobot/job/colobot/job/dev/Doxygen/)
+* [Game Design Document](http://compiled.colobot.info/job/colobot/job/colobot-misc/job/master/lastSuccessfulBuild/artifact/Colobot_Gold_Edition-Game_Design_Document.pdf)
## Before you start coding
* If you want to fix a bug, please first check the related [issue on GitHub's bug tracker](https://github.com/colobot/colobot/issues). If there isn't one, make it.
@@ -13,14 +15,69 @@ You may also find some useful information on the our (outdated) [dev wiki](http:
* Before you start, check *"Assignee"* field in the issue and read the comments to see if nobody else is working on the same issue. If somebody is assigned to it, but there was no activity for a long time, you can take it over. Also, please post a comment on the issue that you want to help us, so other people don't waste time working at that issue in the same time.
## Coding style
-See the [related page on dev wiki](http://colobot.info/wiki/dev/Coding_rules) for general guidelines, or [this file](https://github.com/colobot/colobot-lint/blob/master/RULES.md) for detailed description.
+When writing code, please adhere to the following rules:
-See [colobot-lint repository](https://github.com/colobot/colobot-lint) for automated tool that checks the coding style.
+* Indent with spaces, 1 indentation level = 4 spaces. Unix line endings. And don't leave whitespace at the end of lines. Thank you.
+* Put braces in new lines.
+
+Like that:
+```c++
+ if (a == b)
+ {
+ // ...
+ }
+ else
+ {
+ // ...
+ }
+```
+NOT like that:
+```c++
+ if (a == b) {
+ // ...
+ } else {
+ // ...
+ }
+```
+You may omit braces if there is only one line in block:
+```c++
+ if (a == b)
+ doStuff();
+```
+* Name functions beginning with upper case, e.g. `FooBar()`
+* Name classes beginning with C, e.g. `class CSomeClass`
+* Name accessors like so: `SetValue()` and `GetValue()`
+* Name structs and enums beginning with uppercase letter, e.g. `struct SomeStruct`
+* Enum values should begin with a prefix and underscore and should be all uppercase, e.g. `SOME_ENUM_VALUE`
+* Use constant values instead of #define's, e.g. `const int MAX_SPACE = 1000;` instead of `#define MAX_SPACE 1000` (names should be all uppercase as in example)
+* Don't use C-style casts, e.g. `(type)(foo)`. Use new C++-style casts, e.g. `static_cast<type>(foo)`.
+* Don't use global variables - use static class members whenever possible.
+* Provide full namespace qualifier wherever possible, e.g. Math::MultiplyMatrices to avoid confusion.
+* Document the new code in Doxygen. Even a short description is better than nothing at all. Also, if you are changing/rewriting old code, please do the same.
+* Put comments in your code but not explaining its structure or what it does (Doxygen is for that), but **why** it does so.
+* Whenever possible, please write unit tests for your code. Tests should go into `test/` subdirectory in each of the code directories.
+* You can use STL classes where needed.
+* Throwing exceptions is allowed, with the exception of CBot code (which has no automated memory management yet, so memory leaks could possibly occur)
+
+Also, when writing `#include`s:
+
+* first - in `.cpp` modules - associated `.h` header, e.g. `#include "app/app.h"` in `app.cpp`
+* then - local includes, e.g. `#include "common/logger.h"` (listed in alphabetical order for clarity)
+* and last - global includes, e.g. `#include <SDL/SDL.h>`, `#include <vector>`
+
+We also have an automated tool for checking the code style. See [colobot-lint repository](https://github.com/colobot/colobot-lint) for details.
If your pull request breaks the coding style, you will have to fix it before it gets merged.
+## Commiting rules
+Please adhere to the following rules:
+* Commits should have meaningful descriptions.
+* Commits should not break the build nor tests.
+* Changes in one commit should not be too extensive, unless necessary.
+* Merges to *master* branch must be discussed beforehand and should include fully finished features if possible.
+
## Submitting pull requests
-After you finish working on your issue and want your code to be merged into the main repository, you should submit a **pull request**. Go to [this page](https://github.com/colobot/colobot/pulls) and select "New pull request". All pull request should ALWAYS be submitted to the *dev* branch. After your PR gets reviewed by our development team, it will be merged to *dev* branch, and on the next release - to the *master* branch.
+After you finish working on your issue and want your code to be merged into the main repository, you should submit a **pull request**. Go to [this page](https://github.com/colobot/colobot/pulls) and select "New pull request". All pull requests should ALWAYS be submitted to the *dev* branch. After your PR gets reviewed by our development team, it will be merged to *dev* branch, and on the next release - to the *master* branch.
If you need more help, see [GitHub's help page on Pull Requests](https://help.github.com/articles/using-pull-requests/).
diff --git a/Doxyfile.in b/Doxyfile.in
index c55e328..c621ae3 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -859,7 +859,7 @@ EXAMPLE_RECURSIVE = NO
# that contain images that are to be included in the documentation (see the
# \image command).
-IMAGE_PATH =
+IMAGE_PATH = "@CMAKE_CURRENT_SOURCE_DIR@/docimg"
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/INSTALL-MSYS2.md b/INSTALL-MSYS2.md
new file mode 100644
index 0000000..f35634f
--- /dev/null
+++ b/INSTALL-MSYS2.md
@@ -0,0 +1,161 @@
+This guide is written to help you with a process of compilation (the newest version of) Colobot: Gold Edition in a Windows environment. [MSYS2](http://sourceforge.net/projects/msys2/) will be used.
+
+Why MSYS2?
+----------
+
+You might ask, why you would use this method instead of the other one? Firstly, let's answer a question "why not just use MSYS?".
+
+The biggest problem with the compilation is **3rd party dependencies**. Installing compiler and tools like Git or Cmake is really nothing compared to trying to install endless number of libraries. Why is it that hard, you ask? Well, we, as the developers, would willingly help with this process for example by providing a package with all the needed stuff. Actually, there was a package once, but IT develops fast and new versions of software are released, including not only compiler, but al [...]
+
+Here comes MSYS2. It provides everything that MSYS has and much more. It is basically a whole Linux-style development environment for Windows. Most importantly, it gives you a package manager, which makes not only installation of all the needed stuff easy, but also can take care of updating it with little human effort.
+
+Also, with the broken package, if you don't want to manually compile and install all the libraries, MSYS2 might be the only way to go.
+
+Guide
+-----
+
+Compiling in Windows is harder than in most Linux distributions, but with MSYS2 it isn't impossible.
+
+### Setting Up an Environment
+
+Steps in this section needs to be done only once. After this, you can basically develop Colobot the same way you would do it normally (well, there might be a problem with integrating Windows-only IDEs).
+
+#### Installation of MSYS2
+
+Read this page really carefully: <http://sourceforge.net/p/msys2/wiki/MSYS2%20installation/> . By following it, you should install and configure MSYS2 without major problems.
+
+#### TIP
+When you face any problems during this guide or anywhere in the future, the first thing you should do is to close all MSYS2 processes and run `autorebase.bat` script (it's in the main MSYS2 folder), especially after installation and updating. If you don't do it, odd problems might appear, like CMake not detecting GCC.
+
+#### Running
+
+Now you need to install `MinGW-w64 toolchain`. Open `MSYS2 Shell` and enter the following command:
+
+```sh
+pacman -S mingw-w64-i686-toolchain
+```
+
+**Warning:** Commands shown in this guide are for 32-bit operating system. If you have 64-bit OS, you must replace all `i686` occurrences with `x86_64`.
+
+MSYS2 creates a new environment (with all the "system" variables set properly) during this installation. You have done that from default `MSYS2 Shell`. To work with GOLD, you need to switch. There are two ways of "opening" an environment you can work in:
+
+1. Open MSYS2 Shell and enter
+
+```sh
+export PATH=/mingw32/bin:$PATH
+```
+
+or
+
+```sh
+export PATH=/mingw64/bin:$PATH
+```
+
+2. Open `MinGW-w64 Win32 Shell` (or `MinGW-w64 Win64 Shell`)
+
+You must do one of these two steps every time you want to compile GOLD.
+
+#### TIP
+You can add "Open MSYS2 Shell here" to the context menu using registry. Save the following code as `.reg` file and run it.
+
+```
+Windows Registry Editor Version 5.00
+[HKEY_CLASSES_ROOT\Directory\Background\shell\open_msys2]
+@="Open MSYS2 here"
+[HKEY_CLASSES_ROOT\Directory\Background\shell\open_msys2\command]
+@="c:\\msys32\\usr\\bin\\mintty.exe /bin/sh -lc 'cd \"$(cygpath \"%V\")\"; export PATH=\"/mingw32/bin:$PATH\"; exec bash'"
+[HKEY_CLASSES_ROOT\Folder\shell\open_msys2]
+@="Open MSYS2 here"
+[HKEY_CLASSES_ROOT\Folder\shell\open_msys2\command]
+@="c:\\msys32\\usr\\bin\\mintty.exe /bin/sh -lc 'cd \"$(cygpath \"%V\")\"; export PATH=\"/mingw32/bin:$PATH\"; exec bash'"
+```
+
+Remember to modify the paths before you use it so they fit in your installation.
+
+#### Installation of Tools and Dependencies
+
+To compile Colobot you need:
+
+- cmake
+- git
+- make
+- gcc
+
+Install them:
+
+```sh
+pacman -S msys2-devel git make mingw-w64-i686-cmake mingw-w64-i686-gcc
+```
+
+It's a good time to configure git or even ssh if you plan to push to the remote repository.
+
+When you are done, you can finally get the greatest benefit of using MSYS2. You are going to install required 3rd party libraries. This is how you do it:
+
+1. Find names of all required dependencies. They are listed in the [main INSTALL.md file](INSTALL.md#compiling-on-linux)
+
+2. Find each library using
+
+```sh
+pacman -Ss dependency-name
+```
+
+3. Install each library using
+
+```sh
+pacman -S package-name
+```
+
+Easy, isn't it?
+
+If you are lazy, you can just use this one-line command, although there is no guarantee it will work or install everything (might be out of date):
+
+```sh
+pacman -S mingw-w64-i686-boost mingw-w64-i686-glew mingw-w64-i686-libpng gettext mingw-w64-i686-gettext mingw-w64-i686-libpng mingw-w64-i686-libsndfile mingw-w64-i686-libvorbis mingw-w64-i686-libogg mingw-w64-i686-openal mingw-w64-i686-SDL2 mingw-w64-i686-SDL2_image mingw-w64-i686-SDL2_ttf
+```
+
+You should now have everything set up and working. You can close all instances of MSYS2 and autorebase to ensure everything installed properly.
+
+### Compilation of GOLD
+
+You could say that you have a small Linux inside of your Windows right now. To compile GOLD just follow the instructions for Linux that are available in the repository (https://github.com/colobot/colobot/blob/dev/INSTALL.md\#compiling-on-linux).
+
+**Warning:** You must add `-G"MSYS Makefiles"` argument to `cmake`. For example, when you want to build a developer version:
+
+```sh
+cmake -DCMAKE_BUILD_TYPE=Debug -DDEV_BUILD=1 -G"MSYS Makefiles" ..
+```
+
+### Dlls
+
+Your executable should run fine if you run it from the shell (like `./colobot` in a folder with a compiled binary). However, it will rather not run if you run it "from Windows", like by double clicking the shortcut. You will get error telling you that some dlls are missing. It's normal on Windows, so don't panic. Linker do dynamic linking by default, so binary must be distributed with the libraries stored in binary dll files. You can provide them in a few ways.
+
+#### PATH
+
+Add `C:\msys32\mingw32\bin` to your environment variable `PATH`.
+
+RMB on Computer -> Click Properties -> Advanced system settings -> Environment Variables -> Edit Path
+
+Be careful though. If you have any other installation of MinGW or other tools like FPC, git and so on, this might result in conflicts (for example two `gcc.exe` files) and the effects are unpredictable.
+
+You can use `PATH` also in other way: just copy all the dlls from `C:\msys32\mingw32\bin` to a place that's already in the `PATH`. This might result in a mess though, because you will mix files for GOLD with something else.
+
+#### Copy
+
+It's the way how it's done in most applications distributed for Windows. Just copy all the needed dlls to a folder with the game. All of them are in `C:\msys32\mingw32\bin`.
+
+You can simply try to run a game and each time it gives you an error copy a missing dll to folder with an executable (like `C:\Program Files\colobot`). Or, you can use this smart command (thanks @krzys-h!):
+
+```sh
+ldd colobot.exe | grep -v /c/WINDOWS/ | cut -d ' ' -f 3 | while read -r line; do cp $line /c/path/to/the/game; done
+```
+
+#### Static Linking
+
+You can try to compile GOLD with static linking. Nobody have done that (at least in Windows) yet, but it's possible in theory. If you did it, please, let us know!
+
+The End
+-------
+
+Hope, this guide helped you with using Windows as a development environment especially for Colobot.
+
+This method was first used and described by @MrSimbax. Script for gaining all the needed dlls was written by @krzys-h.
\ No newline at end of file
diff --git a/INSTALL.md b/INSTALL.md
index 8b4265d..423166d 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -40,7 +40,7 @@ statically linked Win32 binaries. More information is available in
#### Compiling with MSYS2/MinGW-w64
-See [this wiki page](http://colobot.info/wiki/dev/Compiling_GOLD_on_Windows_with_MSYS2) for details.
+See the [INSTALL-MSYS2.md](INSTALL-MSYS2.md) file for details.
#### Compiling with MSVC
@@ -125,7 +125,7 @@ So if you provided prefix "/some/prefix", you can run:
### Compiling on MacOS X
-As of 0.1.2-alpha, we have added MacOS X support. See [INSTALL-MacOSX.md](https://github.com/colobot/colobot/blob/master/INSTALL-MacOSX.md)
+As of 0.1.2-alpha, we have added MacOS X support. See [INSTALL-MacOSX.md](INSTALL-MacOSX.md)
file for details.
diff --git a/README-dev.md b/README-dev.md
new file mode 100644
index 0000000..cb5f1fa
--- /dev/null
+++ b/README-dev.md
@@ -0,0 +1,99 @@
+# README for developers
+This file contains a ton of information useful for development of the game
+
+## Repository setup
+All the repositories related to Colobot can be found on our GitHub organization page: https://github.com/colobot
+
+### Main code repository
+This is the repository you are currently in.
+
+This repository contains all the source files of Colobot, along with some 3rd party libraries, testing framework and build files for CMake.
+
+### Data repository
+The data repository is available at: https://github.com/colobot/colobot-data
+
+This repository contains the data files necessary to run the game. These are level files, textures, models, sounds, music, help files, translations, etc. It contains many binary files, and so, it may grow up to considerable size. If that becomes a problem, we may remove some old revisions of binary files to free up space.
+
+### Branch setup
+Current setup is as follows:
+
+* branch **master** - will always contain the best-playable version of the project so that new users could download and compile the project without problems. This branch is not intended for actual development but an integration branch for more "public" releases. The changes should be pulled from general development branch - *dev*. This branch will also have tags at certain commits to denote releases.
+* branch **dev** - development branch. This branch is used for general development. Changes committed here should be either pull requests implementing whole features, or incremental commits that do not change many files.
+
+Other **dev-*** branches may be created as needed, for work on major rewriting, or focusing on a set of features.
+
+## 3rd party libraries
+3rd party libraries are bundled in `lib/`. They are provided for ease of use since the standard packages are rare in OS distributions.
+
+In case of GTest and GMock, CMake tries to detect if they are available in the system. If so, the system-provided versions will be used.
+
+## CMake build system
+The build system is as follows:
+
+* `CMakeLists.txt` - definition of project, list of required packages, build type setup, general compiler options and reference to src subdirectory,
+* `src/CMakeLists.txt` - defines the main colobot target,
+* `src/CBot/CMakeLists.txt` - defines the CBot library target,
+* `src/tools/CMakeLists.txt` - defines tool program targets,
+* `data/CMakeLists.txt` - separate file in data submodule, includes routines for creating translations, manpage, icons, etc. and installing them with program.
+
+Test build system is discussed below.
+
+CMake sets some `#defines` which are passed to code in generated headers `common/config.h` and `common/version.h`.
+
+There are only a few include directories specified:
+
+* the main source directory `src/`,
+* CMake binary directory (because of generated `common/config.h`),
+* `lib/` directory with 3rd party libraries.
+
+Because of the above, include paths in source should always feature the full path from src, e.g. `#include "object/auto/auto.h"`, even if the file lies in the same directory. This will make it easier to move files around and change the `#include` lines with automated replace scripts (some of which are available in *tools/*).
+
+Note that the recommended way of building the project is to use separate build directory, where CMake will generate all targets. In this way, you can keep a clean source directory. The following shell commands illustrate this usage:
+
+```sh
+ cd <colobot_repository>
+ mkdir build
+ cmake ../
+ make
+ bin/colobot -datadir ../data
+```
+
+## Tests organization
+Tests are kept in `test/` directory which includes:
+
+* `test/cbot` - CBOT interpreter for test purposes,
+* `test/unit` - automated unit tests.
+
+Each test directory contains own `CMakeLists.txt` specifying targets. Note however that the only targets added as automated tests in CMake are in `test/unit` directory. The other targets are used as development support tools, not automated tests.
+
+Tests can be enabled or disabled using CMake option TESTS (OFF by default). To run the automated tests (you must be in the build directory):
+```
+ ./colobot_ut
+ # or:
+ make test
+ # or:
+ ctest -V .
+```
+
+For unit testing, we use Google Test framework (http://code.google.com/p/googletest/) and for mocking objects and function calls, GMock library (http://code.google.com/p/gmock/).
+
+Note that currently, there are very few well-tested parts of code. It is quite impossible to write unit tests for all the code we have but we should test as much code as possible, if not at unit level, then at module level. Hence the test environments and code snippets that enable us to test parts of code without actually running the full-fledged game.
+
+## CI and automated builds
+Our team is not large, but since compiling the whole project is lengthy and requires some knowledge, we use some automated services to facilitate the development.
+
+Currently we use Jenkins server hosted at http://compiled.colobot.info/ to run tests and provide compiled game binaries.
+
+Testers are encouraged to use these packages to test the game and report any problems.
+
+## Code documentation
+[Doxygen](http://www.stack.nl/~dimitri/doxygen/) is used as the documentation tool.
+
+The documentation is extracted from comment blocks in code by running `make doc`. The resulting HTML files are available in ''doc/'' inside the build directory. Generated documentation files '''will not''' be included in the repository. The idea is that anyone can generate the documentation at any time, in his local copy. Our Jenkins also builds documentation after every commit, see http://compiled.colobot.info/job/colobot/job/colobot/job/dev/Doxygen/
+
+Diagram generation (class inheritance, include dependencies, etc.) is disabled for now to speed up the generation process but you can of course enable it in your local copy.
+
+Currently, only a few classes and structs are documented properly. If you can, please expand the documentation wherever possible.
+
+## Coding rules
+Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md#coding-style) file.
diff --git a/docimg/2d_coord.png b/docimg/2d_coord.png
new file mode 100644
index 0000000..bd4676b
Binary files /dev/null and b/docimg/2d_coord.png differ
diff --git a/docimg/3d_canonical_coords.png b/docimg/3d_canonical_coords.png
new file mode 100644
index 0000000..d9b3ace
Binary files /dev/null and b/docimg/3d_canonical_coords.png differ
diff --git a/docimg/README.txt b/docimg/README.txt
new file mode 100644
index 0000000..ab7f16e
--- /dev/null
+++ b/docimg/README.txt
@@ -0,0 +1 @@
+Images used in Doxygen documentation
\ No newline at end of file
diff --git a/src/app/main.cpp b/src/app/main.cpp
index 389de93..97cee63 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -48,13 +48,22 @@
#include <vector>
#include <boost/filesystem.hpp>
-/* Doxygen main page */
-
/**
-
\mainpage
-Doxygen documentation of Colobot project
+Doxygen documentation of Colobot: Gold Edition project.
+
+<b>Colobot</b> <i>(COLOnize with BOTs)</i> is a game combining elements of real time strategy (RTS)
+and educational game, aiming to teach programming through entertainment. You are playing as an astronaut
+on a journey with robot helpers to find a planet for colonization. It features a C++ and Java-like,
+object-oriented language, CBOT, which can be used to program the robots available in the game.
+
+The original version of the game was developed by [Epsitec](http://www.epsitec.ch/) and released in 2001.
+Later, in 2005 another version named Ceebot was released. In March 2012, through attempts
+by Polish Colobot fans, Epsitec agreeed to release the source code of the game on GPLv3 license.
+The license was given specfifically to our community, <b>TerranovaTeam</b>,
+part of <b>International Colobot Community (ICC)</b> (previously known as <i>Polish Portal of Colobot (PPC)</i>;
+Polish: <i>Polski Portal Colobota</i>) with our website at http://colobot.info/.
\section Intro Introduction
@@ -71,17 +80,21 @@ The source code was split from the original all-in-one directory to subdirectori
each containing one major part of the project.
The current layout is the following:
- src/CBot - separate library with CBot language
- - src/app - class CApplication and everything concerned with SDL plus other system-dependent
- code such as displaying a message box, finding files, etc.
+ - src/app - class CApplication and everything concerned with SDL
- src/common - shared structs, enums, defines, etc.; should not have any external dependencies
+ - src/common/resources - filesystem management using PHYSFS library
+ - src/common/system - system-dependent code such as displaying a message box, finding files, etc.
+ - src/common/thread - wrapper classes for SDL threads
- src/graphics/core - abstract interface of graphics device (abstract CDevice class)
- (split from old src/graphics/common)
- src/graphics/engine - main graphics engine based on abstract graphics device; is composed
- of CEngine class and associated classes implementing the 3D engine (split from old src/graphics/common)
+ of CEngine class and associated classes implementing the 3D engine
+ - src/graphics/model - code related to loading/saving model files
- src/graphics/opengl - concrete implementation of CDevice class in OpenGL: CGLDevice
- src/graphics/d3d - in (far) future - perhaps a newer implementation in DirectX (9? 10?)
- src/math - mathematical structures and functions
- - src/object - non-graphical game engine, that is robots, buildings, etc.
+ - src/object - non-grphical game object logic, that is robots, buildings, etc.
+ - src/level - main part of non-graphical game engine, that is loading levels etc.
+ - src/level/parser - parser for loading/saving level files from format known as <i>scene files</i>
- src/ui - 2D user interface (menu, buttons, check boxes, etc.)
- src/sound - sound and music engine written using fmod library
- src/physics - physics engine
diff --git a/src/graphics/README.txt b/src/graphics/README.txt
index f9ec2ae..41772be 100644
--- a/src/graphics/README.txt
+++ b/src/graphics/README.txt
@@ -11,3 +11,48 @@
* defining a border between pure graphics engine and other parts of application.
*/
+/**
+ * \page graphics Graphics engine
+ *
+ * The graphics engine consists of 3 parts:
+ * * core - low-level device code (currently with only OpenGL implementation)
+ * * main engine - managing and displaying 3D environment (terrain, models, water, sky, effects, camera, etc.)
+ * * 2D interface - classes drawing the 2D interface (menus, buttons, editor, HUD elements)
+ *
+ * \section coords Drawing coordinates
+ *
+ * \subsection coords2d 2D interface
+ *
+ * 2D interface is drawn by setting orthogonal projection yielding the following 2D coordinate system:
+ *
+ * \image html 2d_coord.png
+ *
+ * Depth test is disabled for 2D interface, so Z coordinates are irrelevant.
+ *
+ * The coordinate system is constant and is independent of resolution or screen proportions.
+ *
+ * UI elements are laid out by computing these standard coordinates, using 640x480 resoultion as reference.
+ * That is, their coordinates are computed like so: x = 32.0f/640.0f, y = 400.0f/480.0f.
+ *
+ * \subsection coords3d 3D environment
+ *
+ * 3D environment is drawn using the following coordinate system:
+ *
+ * \image html 3d_canonical_coords.png
+ *
+ * The base coordinate system is like depicted above with viewport on Z=0 plane.
+ * The coordinates are then transformed by world, view and projection matrices to yield screen coordinates.
+ *
+ * The base coordinates are also model coordinates. All models must be modelled in this setup.
+ * Scale should be kept proportional to existing models.
+ *
+ * The world matrix defines the transformation from model coordinate system to the point and orientation
+ * in 3D scene. This matrix is defined one per every <i>graphics engine</i> object.
+ * (Note the emphasis - the objects as defined in game engine do not necessarily correspond to
+ * one graphics engine object.)
+ *
+ * The view and projection matrices define the viewing point and volume, and are mostly managed by Gfx::CCamera.
+ * View is defined by Math::LoadViewMatrix() function, that is using 3 vectors: eye position (eyePt),
+ * target point (lookatPt) and up vector (upVec). Projection is always perspective,
+ * with changing view angle (focus).
+ */
\ No newline at end of file
diff --git a/src/graphics/model/README.txt b/src/graphics/model/README.txt
new file mode 100644
index 0000000..a71ffa9
--- /dev/null
+++ b/src/graphics/model/README.txt
@@ -0,0 +1,82 @@
+/**
+ * \namespace Gfx::ModelInput
+ * \brief Functions related to model loading
+ */
+
+/**
+ * \namespace Gfx::ModelOutput
+ * \brief Functions related to model saving
+ */
+
+/**
+ * \page models Models
+ *
+ * Model formats and associated issues are described briefly for graphics designers and developers.
+ *
+ * \section format Model format
+ *
+ * \todo Update for the new model format
+ *
+ * Colobot models are basically a collection of triangles with some associated data.
+ * <span style="text-decoration: line-through;">In the code, the class Gfx::CModel (src/graphics/model/model.h)
+ * is responsible for reading/writing model files.</span> Each triangle of model contains the information
+ * as stored in Gfx::ModelTriangle struct defined in model_triangle.h header, that is:
+ * * 3 triangle points (coordinates, normals, UV texture coordinates for 2 textures)
+ * * material (ambient, diffuse, specular colors)
+ * * file names for 1st and 2nd texture (or, for 2nd texture - variable flag)
+ * * rendering state
+ * * <span style="text-decoration: line-through;">min and max values of LOD (= level of details)</span>
+ *
+ * \subsection textures Textures
+ *
+ * 1st texture is always static - the assigned image name.
+ *
+ * 2nd texture can be set explicitly in 2nd texture name, with variable flag set to false.
+ * It is then static as 1st texture.
+ *
+ * But if variable flag is set, the texture will be applied dynamically by the graphics engine.
+ * It will be one of dirtyXX.png textures, depending on current setup.
+ *
+ * \subsection renderstates Rendering states
+ *
+ * Rendering state is one of Gfx::CEngine's rendering states, that is a mask of enum Gfx::EngineRenderState values
+ * from src/graphics/engine/engine.h.
+ *
+ * For most purposes, the default render (Gfx::ENG_RSTATE_NORMAL = 0) state will be sufficient.
+ * This state enables regular one-texture rendering.
+ *
+ * To use 2nd texture, set one of Gfx::ENG_RSTATE_DUAL_BLACK or Gfx::ENG_RSTATE_DUAL_WHITE states.
+ * Other states, enabling specific behavior may be used in rare cases.
+ *
+ * \subsection lod Min and max LOD
+ *
+ * <span style="text-decoration: line-through;">LOD is used to display different model triangles based
+ * on distance to viewer. The given triangle will only be displayed if the distance is within bounds [min, max].</span>
+ *
+ * <span style="text-decoration: line-through;">For now, use standard definitions of min and max which
+ * fall into 3 categories:</span>
+ * * <span style="text-decoration: line-through;">min = 0, max = 100 - max detail</span>
+ * * <span style="text-decoration: line-through;">min = 100, max = 200 - medium detail</span>
+ * * <span style="text-decoration: line-through;">min = 200, max = 1 000 000 - low detail</span>
+ *
+ * \section fileformats File formats
+ *
+ * There are currently 3 file formats recognized by Gfx::ModelInput and Gfx::ModelOutput:
+ * * old binary format (in 3 versions, though mostly only the 3rd one is used) - this is the format
+ * of original model files; it is deprecated now and will be removed in the future
+ * * new text format - preferred for now, as it is easy to handle and convert to other formats as necessary
+ * * new binary format - contains the same information as new text format
+ *
+ * \section blenderimport Import/export in Blender
+ *
+ * The plugin to import and export models in Blender is contained in \p tools/blender-scipts.py.
+ * To use it, install it as per instructions [on Blender wiki](http://wiki.blender.org/index.php/Doc:2.6/Manual/Extensions/Python/Add-Ons).
+ * It will register new menu entries under File -> Import and File -> Export. Import is always active, but to export,
+ * you have to select a mesh object first.
+ *
+ * Textures are loaded from the same directory as the model file.
+ *
+ * Additional data like state, variable texture flag and min and max LOD can be given as user attributes.
+ *
+ * If you have any problems, please contact \b piotrdz on ICC forum or IRC channels.
+ */
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-games/colobot.git
More information about the Pkg-games-commits
mailing list