Bigfoot71/r3d
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
R3D is a 3D rendering library designed to work with raylib. It offers features for lighting, shadows, materials, post effects, and more.
R3D is ideal for developers who want to add 3D rendering to their raylib projects without building a full rendering engine from scratch.
- Hybrid Renderer: Supports both deferred and forward rendering. You can force forward rendering globally with
R3D_FLAG_FORCE_FORWARD, or let the engine choose the optimal path based on rendering parameters. - Advanced Model Loading: Powered by Assimp for superior compatibility with 3D model formats. Automatic generation of missing normals and tangents for complete vertex data.
- Unified Material System: Complete
R3D_Materialsystem that handles blend modes, face culling, and all material properties in one place. - Optimized Mesh Architecture:
R3D_Meshsystem with unified vertex buffer containing all attributes (position, texcoord, normal, color, tangent) for better performance and consistency. - Automatic Frustum Culling: Built-in frustum culling with automatic AABB generation for meshes and models. Supports OBB (Oriented Bounding Box) for precise culling using local-space transforms.
- Memory-Based Loading: Load models directly from memory with
R3D_LoadModelFromMemory()for embedded resources scenarios. - Lighting: Supports directional, spot, and omni lights, fully integrated with both deferred and forward rendering paths.
- Shadow Mapping: Soft shadows with per-light resolution and dynamic update modes (manual, interval, or per-frame).
- Skyboxes: HDR and non-HDR skybox rendering with IBL (image-based lighting) support.
- Post-processing Effects: Includes SSAO, bloom, fog, tonemapping, color grading, FXAA, and more.
- Enhanced Instanced Rendering: Render instances with per-instance transform matrices, optional global matrix, color instances support, and global AABB for frustum culling.
- Flexible Mesh Generation: Complete set of mesh generation functions with optional deferred upload via
R3D_UploadMesh()for better control over GPU resource management. - Blit Management: Renders at internal resolution and blits to screen or texture with aspect ratio controls.
- CPU Particles: Particle system simulated on CPU with automatic AABB support for frustum culling, dynamic curves for size over lifetime, and other interpolated properties.
- 3D Sprites: Render 3D-facing sprites with support for sprite sheet animations.
- Billboard Rendering: Billboards supported across all render types—meshes, instanced geometry, particles, and sprites.
- Transparency Control: Transparent object sorting can be manually enabled when needed for a correct blending.
To use R3D, you must have raylib installed, or if you don’t have it, clone the repository with the command:
git clone --recurse-submodules https://github.com/Bigfoot71/r3d
If you have already cloned the repository without cloning raylib with it, you can do:
git submodule update --init --recursive
To build and use R3D, ensure you have the following dependencies installed:
-
raylib 5.5 or later By default, R3D uses
find_package(raylib)to detect a system-installed version. If you don't have the required version installed, or prefer not to install it manually, you can enable theR3D_RAYLIB_VENDOREDCMake option to use the vendored version included as a Git submodule.
To clone the submodule, refer to the Getting Started section. -
Assimp By default, R3D uses
find_package(assimp)to detect a system-installed version. If you don't have Assimp installed, or prefer to use a specific version, you can enable theR3D_ASSIMP_VENDOREDCMake option to use the vendored version included as a Git submodule.
To clone the submodule, refer to the Getting Started section. -
Python (>= 3.6) Required for shader minification, which integrates optimized shaders into the library's binary.
-
C Compiler A compiler supporting C99 or later is necessary for building the project.
-
CMake Used to configure and build the library.
R3D requires an OpenGL 3.3+ compatible driver. OpenGL ES support is not yet available but is planned for future updates.
-
Clone the repository:
git clone https://github.com/Bigfoot71/r3d cd r3d -
Optional: Clone raylib submodule:
git submodule update --init --recursive
-
Build the library:
Use CMake to configure and build the library.
mkdir build cd build cmake .. cmake --build .
-
Link the library to your project:
- R3D is a CMake project, and you can include it in your own CMake-based project via
add_subdirectory()or by linking directly to the built library. - If you're using it as the main project, you can build the examples using the option
R3D_BUILD_EXAMPLESin CMake. - If you want to build R3D as a shared library, use the CMake option
BUILD_SHARED_LIBS.
- R3D is a CMake project, and you can include it in your own CMake-based project via
-
Cross Compilation:
You can also perform cross-compilation on Linux for Windows using MinGW.
Ensure that MinGW is installed on your system. For example, on a Debian or Ubuntu-based system, run:
sudo apt-get install mingw-w64
Once inside the
builddirectory, use one of the following commands depending on the target architecture:- For Windows 32-bit:
cmake .. -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w32-x86_64.cmake
- For Windows 64-bit:
cmake .. -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake
To initialize R3D, you need to specify the internal resolution in which it will render, as well as the flags that determine how it should operate. You can simply set them to '0' to start.
Here is a basic example:
#include <r3d.h>
int main()
{
// Initialize raylib window
InitWindow(800, 600, "R3D Example");
// Initialize R3D Renderer with default settings
R3D_Init(800, 600, 0);
// Load a model to render
// 'true' indicates that we upload immediately to the GPU
R3D_Mesh mesh = R3D_GenMeshSphere(1.0f, 16, 32, true);
// Get a material with default values
R3D_Material = R3D_GetDefaultMaterial();
// Create a directional light
// NOTE: The direction will be normalized
R3D_Light light = R3D_CreateLight(R3D_LIGHT_DIR);
R3D_SetLightDirection(light, (Vector3) { -1, -1, -1 });
R3D_SetLightActive(light, true);
// Init a Camera3D
Camera3D camera = {
.position = (Vector3) { -3, 3, 3 },
.target = (Vector3) { 0, 0, 0 },
.up = (Vector3) { 0, 1, 0 },
.fovy = 60.0f,
.projection = CAMERA_PERSPECTIVE
};
// Main rendering loop
while (!WindowShouldClose()) {
BeginDrawing();
R3D_Begin(camera);
R3D_DrawMesh(&mesh, &material, MatrixIdentity());
R3D_End();
EndDrawing();
}
// Close R3D renderer and raylib
R3D_UnloadMesh(mesh);
R3D_Close();
CloseWindow();
return 0;
}This example demonstrates how to set up a basic 3D scene using R3D:
- Initializes a raylib window (800x600 pixels).
- Calls
R3D_Init()to set up the R3D renderer with the default internal resolution (same as the raylib window). - Loads and renders a simple mesh using
R3D_GenMeshSphere(). - Get a default material for rendering the mesh that you can then configure.
- Creates a directional light to illuminate the scene.
- Initializes a
Camera3Dto view the scene. - Runs the main loop, rendering the mesh and light until the window is closed.
- Closes the R3D renderer and raylib window properly.
R3D supports several types of lights, each with its own behavior and characteristics. You can create and manage lights as shown below:
R3D_Light light = R3D_CreateLight(R3D_SPOTLIGHT); // Create a spotlight and return its ID
R3D_LightLookAt(light, (Vector3){0, 10, 0}, (Vector3){0}); // Set light position and target
R3D_SetLightActive(light, true); // Indicates to turn on the lightThe R3D_CreateLight() function takes one parameter: the light type, which remains constant for the light's lifetime.
R3D supports the following light types:
-
R3D_DIRLIGHT (Directional Light):
- Simulates sunlight, casting parallel rays of light in a specific direction across the entire scene.
- Useful for outdoor environments where consistent lighting over large areas is required.
-
R3D_SPOTLIGHT (Spotlight):
- Emits a cone-shaped beam of light from a specific position, pointing toward a target.
- Requires defining both the light's position and its target to determine the direction of the beam.
- Spotlights include the following configurable parameters:
- Range: Defines how far the spotlight reaches before fading out completely.
- Inner Cutoff: The angle of the cone where the light is at full intensity.
- Outer Cutoff: The angle where the light fades out to darkness.
- Attenuation: Controls how the light intensity decreases with distance, enabling realistic falloff effects.
-
R3D_OMNILIGHT (Omni Light):
- A point light that radiates uniformly in all directions, similar to a light bulb.
- Requires a position but does not use a direction or target.
- Range: Determines the maximum distance the light affects objects before fading out.
- Attenuation: Controls how the light intensity decreases with distance, enabling realistic falloff effects.
To draw a model in the scene, use the R3D_DrawModel() functions. There are three possible variants:
void R3D_DrawModel(const R3D_Model* model)void R3D_DrawModelEx(const R3D_Model* model, Vector3 position, float scale)void R3D_DrawModelPro(const R3D_Model* model, Vector3 position, Vector3 rotationAxis, float rotationAngle, Vector3 scale)
These functions work like raylib’s but differ internally. The only visible difference is that they don’t take a tint.
The 'tint' must be set directly in the material via the material.albedo.color member.
Note that this material is copied internally, so you can modify it between each call and the results will be different.
R3D_Model model = R3D_LoadModel("model.fbx");
R3D_DrawModel(&model, (Vector3) { 0 }, 1.0f);- Shadow Mapping: Supports shadows for point, spot, and directional lights. When creating a light, you can specify a shadow map resolution. Shadows can still be disabled later using the
R3D_DisableLightShadowfunction:
R3D_EnableLightShadow(light, 2048); // Enable shadow mapping with a 2048x2048 shadow map resolution
R3D_DisableLightShadow(light, false); // Disables the light; `false` keeps the allocated shadow map, while `true` destroys it- Material System: R3D uses its own
R3D_Materialsystem that provides a unified approach to handling textures, rendering modes, and material parameters. The material system integrates blend modes, face culling, shadow casting, and billb 8000 oard settings directly into the material structure.
R3D_Material material = R3D_LoadMaterialDefault(); // Creates a default R3D material, default material config below
// Sets the material's albedo with a texture and color tint
material.albedo.texture = R3D_GetWhiteTexture();
material.albedo.color = WHITE;
// Configure ORM (Occlusion-Roughness-Metalness) properties
material.orm.texture = R3D_GetWhiteTexture(); // Optional: combined ORM texture
material.orm.roughness = 1.0f; // Surface roughness (0.0 = mirror, 1.0 = rough)
material.orm.metalness = 0.0f; // Metallic property (0.0 = dielectric, 1.0 = metallic)
material.orm.occlusion = 1.0f; // Ambient occlusion (1.0 = no occlusion)
// Set up emission properties
material.emission.texture = R3D_GetWhiteTexture(); // Optional: emission texture
material.emission.color = WHITE; // Emission color
material.emission.energy = 0.0f; // Emission energy multiplier
// Configure normal mapping
material.normal.texture = R3D_GetNormalTexture(); // Optional: normal texture
material.normal.scale = 1.0f; // Normal scale
// Set rendering modes directly in the material
material.blendMode = R3D_BLEND_OPAQUE; // Transparency blending
material.cullMode = R3D_CULL_BACK; // Face culling
material.shadowCastMode = R3D_SHADOW_CAST_FRONT_FACES; // Shadow casting
material.billboardMode = R3D_BILLBOARD_DISABLED; // Billboard behavior
// Alpha cutoff for transparency testing
material.alphaCutoff = 0.01f;- Post-processing: Post-processing effects like fog, bloom, tonemapping or color correction can be added at the end of the rendering pipeline using R3D's built-in shaders.
If you'd like to contribute, feel free to open an issue or submit a pull request.
This project is licensed under the Zlib License - see the LICENSE file for details.
Thanks to raylib for providing an easy-to-use framework for 3D development!