3D World Creation: How-To Guide

The editor: Starting with the user interface

Introduction

The CP3D Editor starts with a default scene and two default plugins.

In the two default plugins, you will find the default monitor (a plugin that draws the scene and the GUI) and the plugin for the API tests. Do not mind those two plugins, just pay attention to the main window.

The default scene

What is the main window?

The main window is very important: it counts all the most common objects in your scene like Terrains, Objects, Lights, Water Surfaces (warning: not oceans), the Vegetation, and more. All these objects have different computations and are optimized automatically by CP3D, depending on their type.

For the entire scene, the complete scene graph is available to you on the right side of the CP3D’s window. Then, you have total control over your scene.

The “Others” section is free, you can place every 3D objects you want to draw (billboards, terrains, animated objects, static objects, etc.) and create their dependencies.

Note: The default scene contains a cube, a plane (which are both Objects) and a spotlight.

Add and configure your first object: a Terrain

To add a Terrain, you should follow these steps in the main window:

• Click “add a Terrain”
• Select the mesh file
• Load as OctTree (or not)
• Accept

Adding a Terrain

Once you added the Terrain, it appears in the Terrains List (main window & scene graph view).

You have now the possibility to edit your terrain and customize its materials, position, etc.

Add a light in your scene

To add a light you can follow the same steps as terrains, but in the Lights tab in the main window. Just give a name to the light and add it.

Added two lights: sun & hall

Edit a light and edit an object

To edit an object (everything is object), just select it in the main window and press CTRL+E. Lights have their own edition tool that follows the same method and have the same keyboard shortcut.

The edition tool for objects contains different tabs: General, Flags & Materials, Global Flags, Physics, Animations, etc. Each tab is disabled if the current object’s type is not valid.

• General tab: Contains all general information and information you will apply to all materials. If you change the first texture layer, all the other materials of the object will change their first texture layer. Same for Material Type. Note: you need to click “Accept” to apply the general tab.
• Flags & Materials: Edit each material. You can switch between materials using the above scrollbar. Each material has its own material, 4 texture layers, light parameters (diffuse, specular, ambiant and emissive).
• Global Flags tab: Same concept as the General tab. It will modify the drawing properties of all materials (back/front face culling, ZWrite enabled, stored into the ZBuffer, etc.). These flags are also customizable in the Flags & Materials tab.
• Physics tab: Set the physics body of the object. Rigid body, liquid body or soft body. Today, only the mass (for rigid and soft bodies) is customizable. Instead, you can customize more using the C++ API of CP3D.
• Animations tab: Configure the saved animations, created with the animation tool of CP3D, and use them.

Note: For more details on parameters and materials, you can press CTRL+SHIFT+E to run the “Materials Editor”. The Materials Editor gives you access to the more advanced parameters of the object.

Do not hesitate to play around with the parameters!

To edit a light, you have three important tabs. Where others are still concepts and are Work In Progress.

• General tab: The general tab contains the most common parameters: position, rotation (target) and the radius of the light (for point lighting)
• Advanced tab: It contains the light’s colors parameters and the shadow map resolution (for shadows computation). The bigger the resolution, the more detailed the shadows. Double-check the resolutions if the light is automatically recalculated (cf. Shadow Light tab).
• Shadow Light tab: Contains the shadow light parameters. You can modify the value of the depth map (no need to draw objects that are too far from the light ☺), the field of view value, whether the shadow is automatically recalculated, the shadow light type. The two pictures “Primary Shadow Map” and “Secondary Shadow Map” are enabled to have a look on the depth maps about the shadows computation.

Note: Point lighting computation is asynchronous, however, if you have more than 24FPS then you will not be able to see that it’s asynchronous.

The toolbars

The tools

The first toolbar contains tools for managing the scenes and objects.

You can save, open and edit the objects and features (custom materials, filters (shaders), animations, scenarios, etc.) you’ll add to your scene.

Helpers, primitives and utilities

Custom Materials Development

CP3D provides a way to develop your own materials (shaders). Compatible Direct3D9 (D3D11 device is still WIP) and OpenGL (GLSL & HLSL languages). A project is composed of multiple materials where you can edit each material.

Add and edit a material

To change the name of a material, select it and modify its name in the text box below the list.

To open the editor, just select a material and click “Open”.

The Editor

The Editor is pretty simple. You can edit the code of the pixel shader and the vertex shader using the Code Editor. Just click the “Edit” buttons and modify the code.

To build the material, click on “Build Material”. It runs the compilation of the shader and the output will appear in the console. If successful, the preview node will compute the new material’s code.

Customizing the constants

To send custom values to the shaders (shaders constants), use the simple and friendly language provided by Community Play 3D.

The code syntax is as follows:

[v-p]constant_type name_of_the_constant [values] [options]

Example: You want to send a float constant to your vertex shader. The constant is named “strength” and the value is “12.543":

vfloat strength 12.543

Before the constant type, just type “v” for vertex shader or “p” for the pixel shader.

The syntax to send a matrix4

[v-p]matrix4 [world, view, proj][0-1] [makeInverse]

If you want to send the concatenation of matrices World View Proj and make the inverse:

vmatrix4 worldViewProjInv proj[0] view[0] world[0] makeInverse

If you don’t want to make inverse, just type a 0 instead of “makeInverse”. To inverse only one matrix, just replace 0 to 1 in the arguments.

vmatrix4 worldInverse world[1] 0 0 0

Equivalent to:

vmatrix4 worldInverse world[0] 0 0 makeInverse

The types

Color (default as floats)

float color [0.f, 1.f]: [v-p]SColor [name] [a] [r] [g] [b]
integer color [0-255]: [v-p]SColori [name] [a] [r] [g] [b]

Integer

[v-p]int [name] [value]

Floats

[v-p]float [name] [value]

Vector3d (only floating points)

[v-p]vector3df [name] [X] [Y] [Z]
Vector3d tricks:
- [v-p]vector3df [name] camPos — Get the current camera position
- [v-p]vector3df [name] camPos4 — Current camera position as 4 values (w)

Send the current time to a constant

If you want to send the current time to a constant (float type), there is a trick!

[v-p][float-int] [name] + ctime [divider]

For example, if you want to send the current time divided per 10 to the constant named “time” in your vertex shader:

vfloat time + ctime 10

In the folder “shaders/Materials/”, you can find a couple examples with these different constants.

Custom Filters Development

CP3D provides a way to develop, compile and see in real-time your custom filters. To add a filter (shader GLSL & HLSL) from a file, use the context menu File -> Open from file. The filters editor is also pretty simple:

• Add a filter (from a file or by clicking on the “+” button)
• Edit the shader’s code
• Edit the callback if needed

Note: The predefined filter are located at “shaders/[HLSL/GLSL]”. You can find in the favorites of the open file dialog.

To compile a new filter with the newer version, just modify your code and type “CTRL+RETURN” and the result in real-time.

To see the compilation errors, just open the log by clicking on the “Open Logs” button.

The callback is in LUA language.

Functions to send a pixel constant:

filter:setPixelShaderConstantFloat(name, value)
filter:setPixelShaderConstantVector2D(name, {x, y})
filter:setPixelShaderConstantVector3D(name, {x, y, z})

Samplers (textures)

A filter can handle maximum of 4 textures. The default textures are:

• 1: LastColorSampler that contains the last effect
• 2: SceneColorSampler that contains the original scene color
• 3: DepthMapSampler that contains the current depth map (if enabled)
• 4: UserMapSampler that contains a custom texture (default 0)

If you want to change these textures you can use these lines

filter:setTextureAtIndex(index, “texture”) — add a texture from a path
filter:setRttTextureAtIndex(index, “texture”) — add a RTT texture

Example

filter:setTextureAtIndex(3, “shaders/Textures/Water/waves2.jpg”) — set the user texture from a path
filter:setRttTextureAtIndex(2, “ReflectionRTT”) — Add the reflection sampler instead of the DepthMapSampler

Valid RTT textures are:

• NormalPassRTT : normal pass
• ReflectionPassRTT : reflection pass
• LightScatteringRTT : light scattering pass (for godrays)
• DepthRTT : the depth pass
• ColorMapSampler : the last filter
• ScreenRTT : Original color of the scene

Steps to add some filters

Final Result

By following all of these steps, you can have:

Notes and informations

Undo / Redo

Due to the collaborative feature and its stakes (real-time collaborative edition), the undo/redo system is still Work In Progress.

The supported static mesh formats:

• 3D Studio meshes (.3ds, r)
• Alias Wavefront Maya (.obj, r/w)
• Lightwave Objects (.lwo, r)
• COLLADA 1.4 (.xml, .dae, r/w)
• OGRE meshes (.mesh, r)
• My3DTools 3 (.my3D, r)
• Pulsar LMTools (.lmts, r)
• DeleD (.dmf, r)
• FSRad oct (.oct, r)
• Cartography shop 4 (.csm, r)
• STL 3D files (.stl, r/w)
• PLY 3D files (.ply, r/w)
• FBX files (.fbx, r)

The supported animated mesh formats:

• B3D files (.b3d, r, skeleton)
• Microsoft DirectX (.x, r) (binary & text, skeleton)
• FBX (.fbx, r)

The supported texture file formats:

• JPEG File Interchange Format (.jpg, r/w)
• Portable Network Graphics (.png, r/w)
• Truevision Targa (.tga, r/w)
• Windows Bitmap (.bmp, r/w)
• Zsoft Paintbrush (.pcx, r/w)
• Portable Pixmaps (.ppm, r/w)
• Adobe Photoshop (.psd, r)
• Quake 2 textures (.wal, r)
• SGI truecolor textures (.rgb, r)
• DirectDraw Surface (.dds, r)