How-to recipes

Short recipes for common tasks. Each one starts from the scene template, gives the code to add with the file and the place where it goes, and shows the expected result (most with a live demo). New to CGP? Start with Install and compile, then Draw a mesh with a camera.

Shapes and meshes

• Draw a mesh with a camera: The minimal code to create a shape, send it to the GPU and draw it with the scene camera.
• Create basic shapes (mesh primitives): Catalog of the 14 mesh_primitive_* functions (sphere, cube, cylinder, cone, torus, grid, arrow...) with their parameters, default values and a picture of the mesh they build.
• Move, rotate and scale a shape: Place a drawable in the world with model.translation, model.rotation and model.scaling, without touching its vertices.
• Build a mesh by hand: Fill the position, uv and connectivity arrays of a mesh yourself, complete the other fields with fill_empty_field, and display it.
• Update a mesh at every frame: Deform the vertices of a mesh on the CPU, recompute its normals, and re-send only the modified buffers to the GPU.
• Draw curves, segments and trajectories: Display a polyline, a set of independent segments or the trail of a moving object with curve_drawable.
• Mesh an implicit surface with marching cubes: Sample a scalar function on a 3D grid and extract the triangle mesh of one of its isosurfaces with marching_cube.

Appearance and textures

• Change the color of a shape: Change the color of a shape with material.color, give each vertex its own color, tint a texture, make a shape transparent, and change the color while the program runs or from the GUI.
• Display the wireframe of a mesh: Show the triangles of a mesh with draw_wireframe (desktop builds), and with a curve_drawable made of the mesh edges, which also works in the web (WebGL) build.
• Apply a texture image: Load a PNG or JPG image on the GPU and map it on a mesh using its uv coordinates, with a choice of wrap mode.
• Draw transparent objects: Display semi-transparent shapes and textures with alpha channel using OpenGL blending, drawn after the opaque ones and sorted back to front.
• Add a skybox: Surround the scene with a sky image (cube map) that follows the camera, using skybox_drawable and a cross-shaped image split into six faces.
• Reflect the environment on a shape: Give a shape a mirror-like look by sampling the skybox cube map in the reflected view direction, with a supplementary texture and a custom fragment shader.

Loading files

• Load a 3D model from an OBJ file: Read a Wavefront .obj file into a mesh, send it to the GPU, then scale and place it in the scene.
• Load an OBJ model made of several textured parts: Load an OBJ file with its .mtl materials and textures as a list of drawables, one per material.

Animation and interaction

• Animate a shape with time: Use a timer_basic to make a shape rotate or move smoothly, at the same speed on every computer.
• Add GUI controls: Add checkboxes, sliders and color pickers with ImGui in display_gui, and recompute a shape only when a parameter changes.
• Spawn objects periodically: Use timer_event_periodic to create particles at a regular rate, move them with time, remove the old ones, and draw them all with a single drawable.
• Explore a scene with a first-person camera: Replace the default orbit camera by a walking or flying first-person camera controlled with the keyboard and the mouse.
• Sketch curves with the mouse: Convert the 2D mouse position into a 3D point and record the strokes drawn with the mouse as growing curves.
• Select and drag objects with the mouse: Pick a sphere with a mouse click (picking_spheres), drag it in the plane facing the camera (picking_plane_orthogonal_to_camera), and freeze the camera during the drag.

Shaders and rendering

• Send a custom uniform to a shader: Load your own GLSL shader, assign it to a drawable, and send it extra parameters (time, coefficients, colors) through environment.uniform_generic.
• Draw thousands of copies with instancing: Draw the same mesh many times in a single draw call, with a per-instance position sent as a supplementary vertex buffer.
• Cast shadows with a shadow map: Render the depth of the scene seen from the light into a depth texture, then darken the pixels hidden from the light in the shader of the shapes.
• Render the scene to a texture and filter it: Draw the scene into an off-screen texture with opengl_fbo_structure, then display it on a full-screen quad with a post-processing shader (edge detection, blur, color effects).
• Use a newer version of OpenGL (4.x): Switch CGP from OpenGL 3.3 to 4.1, 4.3 or 4.6 with one compile definition, check the version obtained, then use OpenGL 4.3 - a compute shader that moves the vertices of a mesh_drawable on the GPU, and the debug messages of the driver.