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 <krzy...@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
_______________________________________________
Pkg-games-commits mailing list
Pkg-games-commits@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-games-commits
