-
Notifications
You must be signed in to change notification settings - Fork 2
CompactStar engine documentation
Below is a quick documentation about how to start a project using the CompactStar Engine and SDK.
The CompactStar Engine provides a template which may be used as a starting point for a new project. It contains the basic features to render a scene, as well as the exposed functions to load, animate and release the scene.
The template is located in the \Templates\CodeBlocks\ folder.
You can also register the template in CodeBlocks, in order to reuse it later, by clicking on the File->Save project as template... menu item, while the project is opened in the editor. Be aware, however, that the new project created from the template need to be deployed in the same folder level as the source template, otherwise you'll have to modify the linked files and third-party libraries manually, in the project properties.
The template is located in the \Templates\Embarcadero\ folder.
The template is located in the \Templates\Visual Studio\ folder.
You can also register the template in Visual Studio, in order to reuse it later. The process to achieve that is described here. Be aware, however, that the new project created from the template need to be deployed in the same folder level as the source template, otherwise you'll have to modify the linked files and third-party libraries manually, in the project properties.
The template is located in the /Templates/xCode/ folder.
You can also register the template in xCode, in order to reuse it later. The process to achieve that is described here.
Several third-parties dependencies may be required to compile the CompactStar SDK.
- The GLEW library is required for all the OpenGL based rendering. This library allows the usage of advanced OpenGL functions implemented since the 2.0 version. To use it, you need to define the \Third-party\glew\include\ path in your project include options, and the \Third-party\glew\lib\Release\[Win32_x64]\ path in your project link options. NOTE due to a different standard used for the library files (OMF instead of COFF) the Embarcadero compilers should point to the \Third-party\glew\lib\Embarcadero\ link path, and there is no 64 bit library version available for this compiler.
- The OpenAL library is required for projects which need to play a sound. To use it, you need to define the \Third-party\OpenAL\include\ path in your project include options, and the \Third-party\OpenAL\libs\[Win32_Win64]\ path in your project link options.
- The SXMLC library is required to load the Collada models, which are based on the XML standards. To use it, you just need to define the \Third-party\sxml\src\ path in your project include options.
NOTE If you're using a template, all the dependencies were already added by default, as relative paths. In case you face link errors during building time, please verify if these paths are correct. Moving the project location or creating a new project from a template in a different folder level than the template may cause this kind of issues. Also, if you don't plan to use a specific module, don't forget to remove the matching dependencies.
The CompactStar SDK is contained in the SDK folder. You can include all the modules, or only those you need for your current project, e.g the CSR_Sound module isn't required if you don't plan to play a sound.
In the CSR_Common.h file you may find the following defines:
// enable or disable model formats
#define USE_MDL // Quake I model format
#define USE_IQM // Inter-Quake model format
#define USE_COLLADA // Collada model format, EXPERIMENTAL (not fully supported)
#define USE_X // DirectX model format, EXPERIMENTAL (not fully supported)
#define USE_WAVEFRONT // WaveFront model format, EXPERIMENTAL (not fully supported)Depending on which model you want to use in your projects, you may enable or disable these defines, thus the matching module no longer needs to be included in the project. It may be particularly important for the USE_COLLADA define, because to compile the Collada module you need to include the SXMLC library to your project. Be aware, however, that changing the define configuration will impact all the projects sharing the same SDK. For that reason, if you need a different configuration for each project, you may either disable entirely the defines here and manage them from the project properties, or copy the SDK in another folder and change its configuration locally.
The SDK also includes several C++ and Objective-C helper classes, which are located in the Common folder. Although these classes are not part of the SDK itself, they may be useful to achieve several common tasks specific to the target system or compiler, e.g initialize or shut down OpenGL, manage the OpenGL resources, create an OpenGL viewport, load a ready-to-use Shader, and so on.
You need to initialize the libraries in order to use them. This is commonly achieved in the project startup code.
The graphics libraries to initialize depend on which renderer you're using:
- For the OpenGL based renderer, the OpenGL library should be initialized, as well as the GLEW library. To do that, you can use the
CSR_OpenGLHelperhelper class, available in the \Common\C++\Helpers\ folder.
HDC g_hDC = 0;
HGLRC g_hRC = 0;
...
// enable OpenGL
CSR_OpenGLHelper::EnableOpenGL(hWnd, &g_hDC, &g_hRC);
// stop GLEW crashing on OSX :-/
glewExperimental = GL_TRUE;
// initialize GLEW
if (glewInit() != GLEW_OK)
{
// shutdown OpenGL
CSR_OpenGLHelper::DisableOpenGL(hWnd, g_hDC, g_hRC);
// close the app
return 0;
}- For the Metal based renderer, the Metal library is automatically initialized by the provided view, for that reason there is nothing special to do.
- It's the same situation if you're using OpenGLES in a MacOS/iOS project.
NOTE If you're using a template, the code to initialize the required graphics libraries is already implemented. You may also refer to the demos for further implementation details.
Here is the code to initialize the OpenAL sound library, it may be used in any project.
ALCdevice* g_pOpenALDevice = nullptr;
ALCcontext* g_pOpenALContext = nullptr;
...
// initialize OpenAL
csrSoundInitializeOpenAL(&g_pOpenALDevice, &g_pOpenALContext);Below are the basic steps to make the scene to work.
If you're using OpenGL, the first task to achieve is to configure it. In your InitScene() function, you may e.g add the following code:
// configure OpenGL depth testing
glEnable(GL_DEPTH_TEST);
glDepthMask(GL_TRUE);
glDepthFunc(GL_LEQUAL);
glDepthRangef(0.0f, 1.0f);To add a scene in your project, you need to create a scene object, which will manage the models to draw. You may achieve that by declaring the following variables:
CSR_Scene* g_pScene = nullptr;
CSR_SceneContext g_SceneContext;Once declared, the variables may be initialized, e.g in your InitScene() function. Below is a code example showing how to achieve that:
// create the default scene
g_pScene = csrSceneCreate();
// create the scene context
csrSceneContextInit(&g_SceneContext);
g_SceneContext.m_fOnSceneBegin = OnSceneBegin;
g_SceneContext.m_fOnSceneEnd = OnSceneEnd;
g_SceneContext.m_fOnGetShader = OnGetShader;
g_SceneContext.m_fOnGetID = OnGetID;
// configure the scene background color
g_pScene->m_Color.m_R = 0.45f;
g_pScene->m_Color.m_G = 0.8f;
g_pScene->m_Color.m_B = 1.0f;
g_pScene->m_Color.m_A = 1.0f;You may find the whole CSR_Scene and CSR_SceneContext description in the provided documentation.
To render a model in the scene you need a Shader. You may write your own Shader program, or you may use one of the Shaders provided in the CSR_ShaderHelper class. Below is a code example showing how to load a Shader in the CompactStar Engine:
const std::string vsTextured = CSR_ShaderHelper::GetVertexShader (CSR_ShaderHelper::IEShaderType::IE_ST_Texture);
const std::string fsTextured = CSR_ShaderHelper::GetFragmentShader(CSR_ShaderHelper::IEShaderType::IE_ST_Texture);
// load the shader
g_pShader = csrOpenGLShaderLoadFromStr(vsTextured.c_str(),
vsTextured.length(),
fsTextured.c_str(),
fsTextured.length(),
0,
0);
// succeeded?
if (!g_pShader)
return false;
// get shader attributes
g_pShader->m_VertexSlot = glGetAttribLocation (g_pShader->m_ProgramID, "csr_aVertices");
g_pShader->m_ColorSlot = glGetAttribLocation (g_pShader->m_ProgramID, "csr_aColor");
g_pShader->m_TexCoordSlot = glGetAttribLocation (g_pShader->m_ProgramID, "csr_aTexCoord");
g_pShader->m_TextureSlot = glGetUniformLocation(g_pShader->m_ProgramID, "csr_sTexture");If you pretend to write your own OpenGL Shader program, be aware that the CompactStar scene object may require several standardized slots, which are:
GLint m_VertexSlot; // it's the vertex buffer data - identified by the csr_aVertices attribute in the OpenGL Shader program
GLint m_NormalSlot; // it's the normal buffer data - identified by the csr_aNormal attribute in the OpenGL Shader program
GLint m_ColorSlot; // it's the vertex color buffer data - identified by the csr_aColor attribute in the OpenGL Shader program
GLint m_TexCoordSlot; // it's the uv texture coordinate buffer data - identified by the csr_aTexCoord attribute in the OpenGL Shader program
GLint m_TextureSlot; // it's the texture sampler - identified by the csr_sTexture sampler in the OpenGL Shader program
GLint m_BumpMapSlot; // it's the bump map texture sampler - identified by the csr_sBumpMap sampler in the OpenGL Shader program
GLint m_CubemapSlot; // it's the cube map texture sampler - identified by the csr_sCubemap sampler in the OpenGL Shader program
GLint m_ModelSlot; // it's the model matrix - identified by the csr_uModel uniform in the OpenGL Shader programYou will also need to define the csr_uProjection and csr_uView uniforms in the Shader program, for the projection and view matrices, respectively.
This is not a limitation, and you can add as additional slots as you need, but you'll have to provide the data for these slots, because the scene object cannot do that for you. You may take a look to the Bot demo in order to see e.g how an additional alpha blending effect is handled in a custom Shader program.
Once the Shader is loaded, it's important to declare the scene viewport. This may be achieved with the following code:
// update the viewport
CSR_OpenGLHelper::CreateViewport((float)w,
(float)h,
0.01f,
100.0f,
g_pShader,
g_pScene->m_ProjectionMatrix);Once the scene initialized, you may add one or several models to it. The below code shows how to load and add an Inter-Quake Model (.iqm) in the scene
// configure the vertex format
vertexFormat.m_HasNormal = 0;
vertexFormat.m_HasTexCoords = 1;
vertexFormat.m_HasPerVertexColor = 1;
vertexCulling.m_Face = CSR_CF_CW;
vertexCulling.m_Type = CSR_CT_Back;
// configure the material
material.m_Color = 0xFFFFFFFF;
material.m_Transparent = 0;
material.m_Wireframe = 0;
// load the IQM model
g_pModel = csrIQMOpen((g_SceneDir + IQM_FILE).c_str(),
&vertexFormat,
&vertexCulling,
&material,
0,
0,
0,
OnLoadTexture,
OnApplySkin,
0);
BuildModelMatrix(&g_Matrix);
// add the model to the scene
csrSceneAddIQM(g_pScene, g_pModel, 0, 0);
csrSceneAddModelMatrix(g_pScene, g_pModel, &g_Matrix);You may refer to the documentation to find the description of the different supported models, and to the provided demos to show how to use them.
To load a sound, you can use the csrSoundOpenWavFile() function, as shown in the example code below:
CSR_Sound* g_pFootStepLeftSound = nullptr;
CSR_Sound* g_pFootStepRightSound = nullptr;
...
// load the sound files
g_pFootStepLeftSound = csrSoundOpenWavFile(g_pOpenALDevice, g_pOpenALContext, (g_SceneDir + FOOT_STEP_LEFT_SOUND_FILE).c_str());
g_pFootStepRightSound = csrSoundOpenWavFile(g_pOpenALDevice, g_pOpenALContext, (g_SceneDir + FOOT_STEP_RIGHT_SOUND_FILE).c_str());
// change the volume
csrSoundChangeVolume(g_pFootStepLeftSound, 0.2f);
csrSoundChangeVolume(g_pFootStepRightSound, 0.2f);To play or stop a sound, you just need to call the following functions:
csrSoundPlay(g_pFootStepLeftSound);
...
csrSoundStop(g_pFootStepLeftSound);You may refer to the documentation to find the description of the whole CSR_Sound module.
While the application is closing, the scene needs to be cleaned up. This is commonly achieved in the DeleteScene() function, called from the application shut down code.
To release the Shader, just call the csrOpenGLShaderRelease() function, as in the below example:
// release the shader
csrOpenGLShaderRelease(g_pShader);To release the scene, just call the csrSceneRelease() function. This will automatically release all the used resources. The below code example shows how to achieve that:
// release the scene
csrSceneRelease(g_pScene, OnDeleteTexture);If you loaded several sounds in your scene, you can release them with the csrSoundRelease() function. Below is an example showing how to achieve that:
// stop running step sound, if needed
csrSoundStop(g_pFootStepLeftSound);
csrSoundStop(g_pFootStepRightSound);
// release OpenAL interface
csrSoundRelease(g_pFootStepLeftSound);
csrSoundRelease(g_pFootStepRightSound);If you previously initialized the graphic libraries, you'll need to shut down them by using the below code.
// shutdown OpenGL
CSR_OpenGLHelper::DisableOpenGL(hWnd, g_hDC, g_hRC);If you previously initialized the sound library, you'll need to shut down it by using the below code.
// release OpenAL interface
csrSoundReleaseOpenAL(g_pOpenALDevice, g_pOpenALContext);You can find the whole SDK documentation here. You just need to open the index.html file in your favorite browser.