OGRE/Środowisko projektowe

Wspólne

Struktura katalogów

Budując i uruchomiając aplikację opartą na OGRE musimy zagwarantować, że kompilator i pliki wykonywalne będą mogły znaleźć wszystkie zależności, czyli pliki jakie potrzebują.

Podczas kompilacji będziemy potrzebować:

• pliki nagłówkowe (*.h)
• biblioteki (*.lib / *.a)

Natomiast skompilowany program będzie potrzebował w tym samym katalogu w którym został utworzony:

• Jądra OGRE w postaci dllów (OgreMain, OgrePlatform)
• Plik plugins.cfg - informuje OGRE, których bibliotek renderingu będzie używał (Direct3D9, OpenGL itp.)
• Plik resources.cfg, w którym gdy używasz takich mechanizmów znajdowania zasobów, jaki jest w ExampleApplication.h określa się ścieżki do tekstur, siatek i skryptów
• Każdy plugin wspomniany w plugins.cfg
• Dodatkowe pliki mediów (*.zip, *.png, *.particle, *.mesh itp.)

W plikach .cfg powinny być ustawione właściwe ścieżki. Jeśli tak nie jest, Ogre może nie znaleźć żadnej biblioteki renderingu i zostanie zgłoszony błąd na ekranie lub w Ogre.log podobny do tego:

Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file

Najłatwiej skonfigurować wszystko poprzez skopiowanie konfiguracji z przykładów z OGRE, jednak ponieważ używają one względnej ścieżki mogą pojawiają się problemy, jeśli program nie znajduje się w tej samej względnej lokacji np. w katalogu sample. Jeśli przenosisz swoją aplikację gdzie indziej będziesz musiał także przestawić ścieżki odpowiednio gdzie indziej.

Typowy rozkład katalogów wygląda następująco:

OGRE_HOME
       ├───bin                  (OgreMain, OgrePlatform, plugins.cfg, resources.cfg)
       │     ├───debug          (binaria tworzone w wersji do debuggowania)
       │     └───release        (binaria tworzone do właściwej wersji)
       ├───docs                 (dokumentacja)
       ├───include              (pliki nagłówkowe .h)
       ├───lib                  (pliki bibliotek .lib / .a)
       ├───media                (pliki mediów, czcionki, modele, siatki 3D, grafika itp)
       ├───plugins              (pluginy)
       └───samples              (katalog przykładów)
             ├───include        (pliki nagłówkowe przykładów .h, m.in. ExampleApplication.h)
             ├───refapp         (pliki zależne)
             ├───scripts        (skrypty do kompilacji przykładów)
             └───src            (pliki źródłowe przykładów .cpp)

Zmienne środowiskowe

Choć nie jest to wprost wymagane, wiele skryptów czy nawet programów wynikowych może korzystać ze zmiennej środowiskowej OGRE_HOME wskazujacej na korzeń struktury katalogów OGRE. Ułatwia ona także konfigurowanie kompilatorów i ogólnie jej stosowanie jest polecane.

• Jeśli pobierałeś i instalowałeś przekompilowany OGRE SDK, powinieneś już mieć mieć ustawioną zmienną środowiskową OGRE_HOME wskazującą na katalog, gdzie go zainstalowałeś. OGRE_HOME jest zmienną zależną od użytkownika (także w Windows). Jeśli po zainstalowaniu SDK nie masz jej ustawionej prawdopodobnie instalowałeś SDK pod innym użytkownikiem. Musisz wtedy samemu określić OGRE_HOME.
• Jeśli pobierałeś kody źródłowe, powinieneś ustawić zmienną środowiskową OGRE_HOME, aby wskazywała na katalog z kodami źródłowymi, czyli ogrenew.

Wiele pluginów i systemów współpracujących z OGRE korzysta z dodatkowych własnych zmiennych środowiskowych. Opis ich znajdziesz w dokumentacji pluginu lub systemu współpracującego.

Struktura katalogów projektu aplikacji

Przyjęto stosować standardową strukturę katalogów przy projektowaniu aplikacji:

 KATALOG_PROJEKTU
            ├───include        (pliki nagłówkowe .h)
            ├───refapp         (pliki zależne)
            ├───scripts        (skrypty)
            └───src            (pliki źródłowe .cpp)

Jak pewnie zauważyliście jest to ta sama struktura co struktura przykładów w głównym katalogu OGRE. Warto przygotować sobie taką strukturę dla każdego swojego projektu osobno. Jeżeli jest to potrzebne do odpowiednich podkatalogów kopiujemy wymagane pliki, które potem możemy zmieniać nie zmieniając ich właściwych wersji. Katalog projektu może znaleźć się w dowolnym miejscu na naszym dysku.

W przypadku stosowania środowiska Visual Studio tworzony jest specjalny katalog dla wszystkich projektów VS w którym z kolei tworzone są podkatalogi solucji a w nich podkatalogi projektów. VS z zainstalowanym Ogre Wizard SDK samo pilnuje ustawienia struktury katalogów projektu. Nie stoi jednak nic na przeszkodzie w stosowaniu ww. struktury standardowej.

Wstępny kod źródłowy

Warto zaczynać od pliku źródłowego zawierającego zalążek programu, nad którym będziemy potem pracować. Plik taki np. mój_projekt.cpp tworzymy w katalogu src. Zawartość pliku umożliwia utworzenie programu tworzącego pustą scenę. Na ekranie po przejściu przez okno konfiguracyjne zobaczymy na czarnym tle po prawej stronie logo OGRE a po lewej okienku informacyjne podające kilka podstawowych informacji na temat działania programu.

Kod źródłowy takiego programu opisany jest w rozdziale Zalążek programu OGRE. W przypadku stosowania VS oraz Ogre SDK Wizard praca z ww. zalążkiem wymaga wybrania opcji "Empty project". W przypadku wybrania innej opcji tworzony jest automatycznie inny kod zalążka co opisane jest w rozdziale "Utworzenie projektu w VS 2005". Także dalsze postępowanie przy rozbudowie programu różni się od podanego w przykładach.

Klasy dołączone

OGRE dostarcza nam zbiór użytecznych klas do tworzenia aplikacji. Nazwane są ExampleApplication i ExampleFrameListener. Klasy te w łatwy sposób uruchomiają system OGRE, konfigurują wszystkie podstawowe rzeczy jak wyświetlanie dialogu konfiguracyjnego, tworzenie okna, ustawianie kamery i to, żeby była czuła na mysz. Jedynie czego potrzebujesz to utworzyć klasy pochodne tych klas i ustawić, jak mają się zachowywać. Klasy te znajdują się w ExampleApplication.h i ExampleFrameListener.h znajdujące się w katalogu Samples. Skopiuj je do <katalog_projektu>/include. W małych projektach możesz wszystko umiejscowić w tym samym katalogu.

Teraz trzeba zapełnić funkcję createScene. Jeśli potrzebujesz bardziej wyrafinowanych możliwości jak np. zmienianie różnych menadżerów scen, będziesz musiał nadpisać kilka metod w ExampleApplication i być może wprowadzić pochodną klasy ExampleFrameListener.

Oczywiście nie musisz używać klas ExampleApplication i ExampleFrameListener. Jednak są one najszybszym sposobem, aby coś zrobić.

Linux

Pliki Samples/Common/include/ExampleApplication.h, Samples/Common/include/ExampleFrameListener.h i Samples/Common/include/ExampleLoadingBar.h powinny zostać przekopiowane do katalogu, w którym chcesz zapisać plik z kodem źródłowym.

Zapisz plik jako main.cpp i przekompiluj go poleceniem:

$ gcc `pkg-config --cflags OGRE` `pkg-config --libs OGRE` main.cpp

Następnie przekopiuj plik wykonywalny a.out do Samples/Common/bin, przejdź do tego katalogu i uruchom go poleceniem

$ ./a.out

Jeśli pkg-config nie może odnaleźć OGRE utwórz plik OGRE.pc w odpowiednim katalogu za pomocą polecenia:

$ ln -s /usr/local/lib/pkgconfig/OGRE.pc /usr/lib/pkgconfig/OGRE.pc

Oczywiście zakładamy, że plik OGRE.pl znajduje się w /usr/local/lib/pkgconfig/.

Zamiast kopiować przekompilowany program do Samples/Common/bin możesz przekopiować pliki plugins.cfg i resources.cfg do katalogu ze swoim projektem, a następnie skonfigurować ścieżki w resources.cfg. W przypadku tworzenia większych projektów jest to najlepsze rozwiązanie.

Gnu Compiler Collection (gcc) v3.x

Upewnij się najpierw, że używasz gcc 3.x. Wiele dystrybucji GNU/Linuksa dostarcza wciąż gcc 2.95.x, który nie za dobrze wspiera standard C++ i może powodować problemy. Najlepiej zainstalować stabilną wersję gcc 3.x.

Utwórz plik Makefile w katalogu twojej aplikacji z poniższą zawartością. Zamień yourApp na twoją nazwą programu.

DEFINES =
LIBS = OGRE
CXX = g++
CXXFLAGS = $(shell pkg-config --cflags $(LIBS)) $(DEFINES)
LD = g++
LDFLAGS = $(shell pkg-config --libs $(LIBS))

all:
	$(CXX) $(CXXFLAGS) $(LDFLAGS) -o yourApp yourApp.cpp

clean:
	rm -f yourApp

Jeśli jesteś przygotowany do pracy z wieloma plikami, możesz stworzyć plik podobny do do poniższego przykładu. Zakładamy, że posiadamy pliki yourApp.cpp, camera.cpp i listener.cpp.

## Ustawienie kompilatora i linkera
DEFINES = -g
LIBS = OGRE CEGUI-OGRE CEGUI
CXX = g++
CXXFLAGS = $(shell pkg-config --cflags $(LIBS)) $(DEFINES)
LD = g++
LDFLAGS = $(shell pkg-config --libs $(LIBS))

## Pliki dołączane do twojego projektu
YOURAPP = yourApp.o camera.o listener.o

## Kompilacja i linkowanie
all: yourApp
	$(LD) $(LDFLAGS) $(YOURAPP) -o yourApp

yourApp: $(YOURAPP)

## Czyszczenie
clean:
	rm -f $(YOURAPP) yourApp

Windows

W przypadku Windows i zastosowania prekompilowanego pakietu SDK nic więcej do prac projektowych nie jest wymagane. Natomiast w przypadku kompilowania systemu ze źródeł potrzebne nam będą także platform SDK dla systemu operacyjnego. Można je pobrać z http://www.microsoft.com/platformsdk. Trzeba także w tym przypadku mieć zainstalowany DirectX SDK, który można pobrać z http://msdn.microsoft.com/directx/sdk/.

Microsoft Visual C++ 6 (SP3+) =

Przed rozpoczęciem upewnij się, czy masz ostatni service pack dla VC6. Szczególnie przed SP3 VC6 było kilka bugów, które oddziałują na twój program. Nie jest to opcjonalny krok.

1. Uruchom VC++ i utwórz nowy projekt 'Win32 Application'.
2. Wpisz nazę swojego projektu i zmień lokację wskazującą, gdzie przekopiowałeś SampleApp.cpp.
3. Wybierz 'An empty project', kiedy wybierasz typ projektu jaki masz utworzyć.
4. Przejdź do zakładki 'File View' i rozszerz drzewo.
5. Przyciśnij prawym przyciskiem myszy na 'Source Files' i wybierz 'Add Files To Folder...'
6. Wybierz plik .cpp przekopiowany z SampleApp.cpp i przyciśnij 'Ok'.
7. Zapisz projekt.

Następnie będziesz potrzebował zmienić ustawienia kompilatora.

Visual Studio 2003-2005 (Visual C++ 7.1-8.0)

Zakładamy, że mamy już prawidłowo zainstalowane Visual Studio lub Visual C++ wraz z jakimś środowiskiem edytorskim.

Instalacja SDK

Instalujemy OGRE 1.2.3 SDK for Visual C++ .Net 2003 (7.1) lub OGRE 1.2.3 SDK for Visual C++ .Net 2005 (8.0) ściągnięty ze strony Ogre. Sugeruję by zainstalować go bezpośrednio do katalogu-korzenia jednego z dysków a w ostateczności do przygotowanego podkatalogu. Zbyt długa ścieżka może być powodem występowania błędów. Z tego samego powodu warto też w tej ścieżce nie używać spacji ani znaków diakrytycznych (ą,ć itp). Po zainstalowaniu SDK będzie się ono znajdować w katalogu OgreSDK. Ścieżka do tego katalogu powinna zostać zarejestrowana (automatycznie) w zmiennych systemowych jako:

 OGRE_HOME=C:\ścieżka\OgreSDK

Instalacja SDK Wizard

Instalujemy Ogre SDK 1.2.x Application Wizard v.1.2 for VC7.1 lub Ogre SDK 1.2.x Application Wizard v.1.2 for VC8.0 (w zależności od zainstalowanego środowiska VS) ściągniety ze stron SourceForge. Sugeruję zainstalować go w katalogu OgreSDK. W czasie instalowania zostanie utworzony podkatalog "Files", który musi tak pozostać. W głównym katalogu zostaną utworzone trzy pliki w tym dwa o rozszerzeniach .js. W zależności od tego czy posiadamy kompletne Visual Studio czy też jedynie Visual C++ Express wybieramy i wykonujemy plik VC8_Setup.js (pełne) lub VC8_Express_Setup.js (express).

Utworzenie projektu w VS 2005

Po uruchomieniu środowiska projektowego Visual Studio, wybieramy z menu File/New/Project. Jako typ projektu wybieramy Visual C++ a z szablonów (templates) wybieramy "Ogre SDK Application". Projekty w VS grupowane są w tak zwane solucje (solution). Solucja taka może grupować niezależne projekty programów ale bardziej sensowne jest grupowanie w niej projektów, które ze sobą współpracują. Jeżeli nasz projekt jest pierwszym w solucji, musimy podać zarówno bardziej ogólną nazwę solucji (solution name) jak i bardziej szczegółową nazwę projektu (name). Można też wybrać katalog do przechowywania plików naszej solucji/projektu ale nic nie stoi na przeszkodzie zastosować domyślny podpowiadany przez środowisko VS.

Pojawia nam się teraz okienko konfiguracji projektu Ogre. Mamy w nim do wyboru typ aplikacji (Application type) którymi są:

Standard application
Minimal application
Empty application

W przypadku aplikacji standardowej mamy możliwość wyboru jednego z dwóch środowisk:

Samples framework  (takiego jak programy przykładowe)
Own framework  (własnego)

Dodatkowo możemy ustawić opcje dodatkowe:

Initial LoadinBar (pokazuje się pasek postępu przy ładowaniu elementów Ogre)
CEGUI Support  (pozwala na wykorzystanie systemu CEGUI)
Skip Config Dialog  (nie wyświetla okienka wyboru konfiguracji)
Postbuild copy  (po przekompilowaniu binaria kopiowane są do OgreSDK\bin\Debug lub OgreSDK\bin\relase)

Standard application

W przypadku wyboru tej opcji wraz z opcją "Sample Framework" tworzone jest środowisko z pełni funkcjonalnym kodem programu Ogre, który po przekompilowaniu wyświetla trójwymiarową głowę ogra. W folderze "Source files" tworzone jest jądro aplikacji w postaci pliku nazwa_projektu.ccp.

Definicja klasy nazwa_projektuApp jest zapisany w pliku nazwa_projektu.h w folderze "Header Files". W definicji klasy znajduje się metoda tworząca kamerę, metoda tworząca scenę i metoda tworząca FrameListener-a. W tym samym pliku znajduje się także definicja klasy nazwa_projektuFrameListener posiadająca metodę frameStarted.

Kody podany są w opisie Zalążek programu OGRE.

Opcja "Sample Framework" automatycznie dodaje katalog "OgreSDK\samples\include" do ścieżek z plikami źródłowymi kompilatora. Musi tak być bo z założenia korzystamy z SampleApplication.h i innych związanych z nim plików.

Pozostały jeszcze trzy pliki w folderach projektu: Resource.h w folderze "Header Files" oraz nazwa_projektu.ico i nazwa_projektu.rc w folderze "Resource Files". Wystarczy na razie, że powiem iż definiują one ikonę programu. Nie są wymagane do właściwej pracy.

Trochę inaczej sprawa wygląda przy wyborze opcji "Own Framework". Tworzona jest wówczas dodatkowa para BaseApplication.ccp i BaseApplication.h gdzie znajdują sie definicje wymaganych klas które w poprzednio omawianym przykładzie znajdowały się w SampleApplication.h w "OgreSDK\samples\include". Umożliwia to bardziej eleastyczne tworzenie własnej aplikacji gdyż możemy je dowolnie zmieniać. Dlatego też można też wówczas dodać "InitBar" czy wyłączyć dialog konfiguracyjny.

Opcja "Standard Application" wykorzystywana jest do szybkiego utworzenia programu, który potem dopasowywujemy do naszych celów. Nie jest zalecana do pracy z dalszymi częściami naszych przykładów.

Minimal application

Tworzone jest środowisko z kilkoma podstawowymi plikami źródłowymi. Zdefiniowana w nich aplikacja jest w pełni poprawna ale nic nie wykonuje (po uruchomieniu kończy się i wychodzi z kodem 0). W folderze "Source files" został utworzony plik nazwa_projektu.ccp. Zawartość pliku podana jest Zalążek programu OGRE

Pozostałe pliki są o tyle mniej ważne, że nie zawierają właściwego kodu ich zadania opisane są w Standard Application.

Gdy zabieramy się za pracę w tak przygotowanym środowisku musimy zdefiniować klasę nazwa_projektuApp czyli klasę naszej aplikacji. Możemy to zrobić w powyższym pliku lub (bardziej poprawnie) w pliku nazwa_projektu.h lub najpoprawniej utworzyć plik z nową klasą za pomocą kreatora klasy.

Pozostałe trzy pliki jak w przypadku "Standard Application" definiują ikonę programu.

Gdybyśmy w powyższym środowisku pracowali z dalszymi przykładami trzeba by z nich usuwać powtarzający się wyżej fragment. Dlatego lepiej - w tym przypadku - zastosować ostatni typ aplikacji, czyli:

Empty application

Tworzone jest puste środowisko projektowe. Nie są tworzone żadne pliki.

W czasie pracy z naszym poradnikiem w celu rozpoczęcia tworzenia programu należy utworzyć w folderze "Nazwa_Solucji\Nazwa_Projektu\Source Files" plik własna_nazwa.ccp, do którego należy wkopiować podany zwykle na początku kod.

Dopiero po utworzeniu pierwszego pliku można wywołać konfigurację projektu i dodać na przykład dodatkowe podkatalogi z plikami źródłowymi. Opcja Configuration Properties\C/C++ nie jest dostępna, jeżeli w projekcie nie ma żadnego pliku cpp lub h.