Programmer's Guide - Scape
Giliam de Carpentier
http://www.decarpentier.nl/scape
June 9th, 2012
Build instructions for Microsoft Visual C++ 2008 (Express)
Currently, Scape only comes with project and solution files for Microsoft Visual Studio C++ 2008 (Express). Follow the instructions below to build Scape's dependencies, to build Scape itself, and finally to run it.
- Download and install a graphics driver and Microsoft DirectX 9.0, if not already done so
- Download and install the Microsoft C++ redistributables, if not already done so
- Extract Scape
- Download the Scape source package, if not already done so. See http://www.decarpentier.nl/scape for details on how to do this.
- Extract the ZIP to your preferred destination base folder, called <PROJECT> for the remainder of this document
- Install and build wxWidgets 2.8.3
- Download http://sourceforge.net/projects/wxwindows/files/wxAll/2.8.3/wxWidgets-2.8.3.zip/download
- Extract the download to <PROJECT>/Dependencies/
- Copy <PROJECT>/Dependencies/wxWidgets-2.8.3-overwrite/lib over the <PROJECT>/Dependencies/wxWidgets-2.8.3/lib folder
- Open <PROJECT>/Dependencies/wxWidgets-2.8.3/build/msw/wx_dll.dsw with Visual Studio and convert all projects
- Set the current configuration to DLL Debug and only build project aui
- Set the current configuration to DLL Release and only build project aui
- Install and build wxPropertyGrid 1.2.12
- Download http://sourceforge.net/projects/wxpropgrid/files/wxPropertyGrid/1.2.12/wxpropgrid-1.2.12-win.exe/download
- Start the installer and set the destination folder to <PROJECT>/Dependencies/wxWidgets-2.8.3.
(don't worry about a potential windows compatibility warning when the installer is finished)
- Open <PROJECT>/Dependencies/wxWidgets-2.8.3/contrib/build/propgrid/propgrid.dsw with Visual Studio and convert project
- Set the current configuration to DLL Debug and build project propgrid
- Set the current configuration to DLL Release and build project propgrid
- Copy the following 8 built DLLs from <PROJECT>/Dependencies/wxWidgets-2.8.3/lib/vc_dll/ to <PROJECT>/Bin/ :
wxbase28_vc_custom.dll, wxmsw28_aui_vc_custom.dll, wxmsw28_core_vc_custom.dll, wxmsw28_propgrid_vc_custom.dll
wxbase28d_vc_custom.dll, wxmsw28d_aui_vc_custom.dll, wxmsw28d_core_vc_custom.dll and wxmsw28d_propgrid_vc_custom.dll
(so, basically everything built in step 2 and 3 except wxmsw28(d)_adv_vc_custom.dll)
- Install Ogre3D SDK 1.8.0
- Download https://sourceforge.net/projects/ogre/files/ogre/1.8/1.8.0/OgreSDK_vc9_v1-8-0.exe/download
- Start the install and chooise any destination folder (for example, <PROJECT>/Dependencies/OgreSDK). The remainder of this document will call the chosen Ogre destination folder <OGRE_HOME>, after the environment variable OGRE_HOME that will be set automatically by the installer.
- Copy OIS_d.dll, OgreMain_d.dll, Plugin_CgProgramManager_d.dll, Plugin_OctreeSceneManager_d.dll and RenderSystem_Direct3D9_d.dll from <OGRE_HOME>/bin/debug/ to <PROJECT>/Bin/
- Copy cg.dll, OIS.dll, OgreMain.dll, Plugin_CgProgramManager.dll, Plugin_OctreeSceneManager.dll and RenderSystem_Direct3D9.dll from <OGRE_HOME>/bin/release/ to <PROJECT>/Bin/
- Build and Run Scape
- Open <PROJECT>/Scape.sln
- Set the current configuration to Debug and only build project Editor
- Set the current configuration to Release and only build project Editor
- For Debug: Run <PROJECT>/Scape_d.exe. For Release: Run <PROJECT>/Scape.exe. Alternatively, to run from within Visual Studio, set the 'working directory' under 'Debugging' in the 'Editor' project properties to $(TargetDir) and Run.
- OPTIONAL: Install Windows Sysinternals DebugView, displaying all (Ogre) log/debug output in real time when Scape is running
C++ architecture
The codebase is split into two major components: The Engine library and the Editor application. All UI-related code can be found in the Editor project. Everything else is in Engine. Each project is further grouped by functionality into subfolders. A description of the function of each source code file in these subfolders written in their header file.
- /Editor - GUI/wxWidgets-related code
- /Application - 'main' function and application class
- /Controls - Custom drag / spinner wxWidget implemention
- /PCH - Precompiled headers
- /Resources - Icons
- /Utils - Miscellaneous helper functions and classes
- /Windows - GUI windows, dialogs and panels
- /Engine - 2D/3D-related code
- /EngineCore - Management and control of world, sky and cameras, as well as (UI) properties and settings
- /GPU2DOperation - 2D GPGPU bitmap / texture / rendertarget container and operation classes
- /HeightfieldBrush - User-controlled brush widget
- /HeightfieldBuffer - Heightfield / -set / -page data container
- /HeightfieldFileCodecs - Heightfield import / export class interfaces and implementations
- /HeightfieldGeom - Heightfield rendering
- /HeightfieldOperation - Brush operation implementations
- /HeightfieldSerializer - Heightfield serialization/compression
- /Input - Mouse/Keyboard/Wacom mapping and handling
- /PCH - Precompiled headers
- /Tinyxml - XML parsing (third party)
- /Utils - Math and miscellaneous functions and classes
- /Wintab - Wacom driver headers
Materials and shaders
The heightfield material is defined in /Bin/Materials/Scripts/HeightfieldMaterial.material. The Ogre materials for the GPU-based brushes are defined in /Bin/Materials/Scripts/GPU2DOperation.material. These materials refer to the following vertex and fragment shader code files in /Bin/Materials/Programs.
- GPU2DOperation.cg - The generic 1:1 vertex shader, and aimple 1:1 'copy' pixel shader
- GPU2DOperationAddMask.cg - Experimental smoothing pixel shader
- GPU2DOperationNoiseDrag.cg - Directional noise pixel shader
- GPU2DOperationNoiseMask.cg - Procedural noise brush pixel shaders
- GPU2DOperationPencil.cg - Smooth additive/subtractive brush pixel shader
- HeightfieldShaderCg.cg - Heightfield terrain and brush widget rendering
Settings
Many settings are store in the following config files in /Bin/Settings.
- ButtonDefinitions.xml - Mouse button and keyboard key to virtual 'buttons' (read)
- Perspective.cfg - Current UI layout set by user (read/write)
- Presets.conf - Tool presets set by user (read/write)
- Startup.conf - Size of the heightfield to be loaded/saved/edited (read-only)
- UI.conf - Names, descriptions and types of UI widgets and properties (read-only)
License
See /Docs/ScapeLicense.txt
Copyright (c) 2007-2012, Giliam de Carpentier. All rights reserved.