vkoskiv / c-ray

c-ray is a small, simple path tracer written in C

c-ray

A portable, hackable, embeddable software path tracer.

Example renders

(1000 samples, 1920x1080, 512 max bounces, 26min, scene by Scott Graham)

(256 samples, 2560x1440, 12 max bounces, 9min 37s, scene by MaTTeSr)

(512 samples, 2560x1600, 30 max bounces, 8min)

About

c-ray is a portable, hackable, offline CPU rendering engine built for learning. The core is in plain C99, with an emphasis on clarity and avoiding superfluous abstraction. Contributions are welcome. See the contributing section in the wiki for more details.

An incomplete list of features:

• Cluster rendering support over TCP/IP
• A C API
• Python bindings
• A Blender add-on
• A node-graph material/shader system with 32+ node types, including a Principled BSDF approximation.
• A performant BVH accelerator (by @madmann92)
• A simple unidirectional Monte Carlo integrator with global illumination
• Real-time render preview and state reporting using a callback mechanism
• Simple thin-lens camera approximation with depth of field
• Multithreading
• Object instancing
• HDR environment maps for realistic lighting
• Triangles and spheres
• Russian Roulette path optimization

Things I'm looking to implement:

• More advanced light sampling
• Better performance & lower memory consumption.
• Proper physically based materials in place of the current ad-hoc implementations
• More cool advanced techniques from research literature

Portability

c-ray has been verified to work on the following architectures

• x86 & x86_64 (Primarily developed on x86_64)
• ARMv6, ARMv7 and ARMv8, AARCH64 (Various Raspberry Pi systems)
• PowerPC 7xx and 74xx (PowerPC G3 and G4 systems)
• MIPS R5000 (1996 SGI O2)
• SuperSPARC II (1992 SUN SparcStation 10)
• WebAssembly with emscripten

Usage

A basic driver program can be used to run c-ray standalone (see 'Stand-alone usage' below), but the easiest way to try out c-ray is to build and install the Blender add-on, and trying it out there:

1. Check BLENDER_ROOT in lib.mk, make sure it points to the version of Blender you have installed
2. make fullblsync will then compile the python bindings (cray_wrap.so), and install under BLENDER_ROOT as an add-on.
3. Enable the c-ray add-on in Blender Preferences, and choose c-ray for Blender as your render engine.
4. Report bugs or missing features (there are a lot!) by filing an issue here on GitHub

Dependencies

Compile time:

• Standard C99 compiler with some fairly common libraries (libc, libm, pthreads)

Runtime:

• CMake for the build system (Optional, a basic makefile is provided for *nix systems)
• SDL2 (Optional, enabled if SDL2 was found at runtime)
• Python3 (Optional, it's used for some utility scripts)

Tests

You can run the integrated test suite by invoking the test script like this: ./run-tests.sh This will compile c-ray with the correct flags, and then run each test individually in separate processes. If you want to run them in a shared process, do bin/c-ray --test You can also run a single suite ./run-tests.sh mathnode

Stand-alone usage

You can mostly ignore these instructions below if you're only interested in running c-ray as a Blender add-on.

Linux:

1. (Optional) Install SDL2 (See installing SDL below)
2. Run make to build the project
3. If the plain Makefile doesn't work on your system, run cmake . and then try make again.
4. Run binary. For example: bin/c-ray input/hdr.json. You can also pipe files into c-ray and it will read from there. This is useful for scripts that invoke c-ray. Example: cat input/scene.json | bin/c-ray Note: When reading the json from stdin, c-ray assumes that the asset path is ./. This can be specified with --asset-path

macOS:

1. Follow Linux instructions, or you can try mkdir build && cd build && cmake -G Xcode ..

Windows:

1. Install Build Tools for Visual Studio
2. Optional: Download SDL2 Development libaries from here and extract: https://www.libsdl.org/download-2.0.php (https://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip)
3. Open a Developer Command Prompt for VS 2019, navigate to where you cloned c-ray and set path to SDL2DIR (where you extracted the files to, should have a few folders like 'include' and 'lib'): set SDL2DIR=E:\sdl2\SDL2-devel-2.0.8-VC\SDL2-2.0.8
4. Run cmake: cmake -G "Visual Studio 16 2019" .
5. (Optional) Copy your SDL2.dll into bin\Release\ and bin\Debug\
6. Build the generated solution: msbuild c-ray.sln /p:Configuration=Release
7. Run: bin\Release\c-ray.exe input\scene.json or type input\scene.json | bin\Release\c-ray.exe

Usage

All the .json files in input/ are test scenes provided with c-ray, assets for those scenes are (mostly) bundled with the repository as well.

If you make a cool scene and have Python3 installed, you can bundle up the scene into a portable .zip file using the scripts/bundle.py script.

Credits

3rd party libraries included in this project include:

• lodePNG PNG compression library: http://lodev.org/lodepng/
• stb_image.h by Sean Barrett: https://github.com/nothings/stb/blob/master/stb\_image.h
• SDL2: https://www.libsdl.org/index.php (Optional)
• JSON parsing library: https://github.com/DaveGamble/cJSON
• PCG random number generator: http://www.pcg-random.org

Contributors

• Huge thanks to @madmann91 for the BVH accelerator and overall ~60% performance improvement

Please file an issue detailing any improvements you're planning on making. I openly welcome contributions!

You can also ping me on Discord: vkoskiv#3100

c-ray's Issues

Don't use: #pragma mark Helper funcs

Not supported by all compilers (windows).

Implement a better camera model

Current one is a very simple pinhole camera, not very realistic.

Optimize colors

Currently doubles are used, only really need uint8_t

boundingVolume shadow bug

Some form of edge case. This would be in rayTrace() in renderer.c

Ray hits a spot on the floor that is inside the boundingVolume of another OBJ, doesn't detect the boundingVolume in this case for some reason.

Move all enums into includes.h directly

enums don't have any code, just put them somewhere they can be used globally. Directly in includes.h or a separate .H file (one for each file, or one with all).

Implement volumetric rendering

k-d tree subdivide end condition calculation is O(n^2)

Find a more efficient, fast way to stop the subdivide. The check is located in kdtree.c:135

Consider: Refactor where writeImage doesn't depend on the scene

The caller could pass in only the stuff it needs to write.

Fix normal maps implementation.

Right now the normals appear skewed on one or more axis.

several missing obj and "unknown command" in "scene.json"

Loading OBJ input/teht1.obj
Error reading file: input/teht1.obj
OBJ teht1.obj file not found!
Failed to find OBJ named teht1.obj

Loading OBJ input/teapot_white.obj
Error reading file: input/teapot_white.obj
OBJ teapot_white.obj file not found!
Failed to find OBJ named teapot_white.obj

Lots of these

Unknown command 'Ke' in material file input/newScene.mtl at line 49:
	Ke

Handle OBJ groups (g) to divide an OBJ to multiple meshes automatically.

Right now if you export a scene from Blender as an OBJ, it's all stuffed into a single mesh in C-ray, which completely breaks the k-d tree acceleration.
Whenever a g tag is encountered in an OBJ file, we should start loading a new mesh instead of adding to the current one.

the xcode project won't build by default bc of missing file "logo.c"

But easy fix by deleting the reference from the project

Implement gamma correction

Fix nesting in polyFromObj

Why is this nested like that?

Glass material does not work with meshes

Right now only spheres like it.

The shading sucks!

I have ideas of better shading for this. Also the test scene could be organized a bit better. Answer my friend invite on discord ASAP my id is saidwho12#3446. I want to talk about it.

errorhandler.h has old style enums, convert to new style

Also, move these enums to global location, and just leave the function behind.

Implement stratified sampling

BMP file saving is broken

Move the material struct to it's own header

It is currently in color.h, move it and the newMaterial function.

Implement specular maps

Shouldn't be too hard, right?

Output directory is hard-coded

SIGKILL (CTRL-C) not handled

Disable assertions for release builds

Just a simple #ifdef should do, make them no-ops when running in release mode.

Stop rendering samples if didn't hit anything on first try

Aperture should be in f-stops instead of units of radius.

Would be more intuitive if it took f-stops and converted those to c-ray aperture radii.

Incorrect lighting

Tips:

My project may be a bit hard to follow for those unfamiliar, so here's some tips:

Uncomment this if you have SDL2 installed, allows for real-time render previews:
https://github.com/VKoskiv/c-ray/blob/master/src/includes.h#L12

The render parameters are set starting on this line here, tweak them to adjust the render result:
https://github.com/VKoskiv/c-ray/blob/master/src/scene.c#L218

Key points in code:

https://github.com/VKoskiv/c-ray/blob/master/src/renderer.c#L312
The render thread, run on each CPU in parallel. This sets up the ray, and calls this next one:

https://github.com/VKoskiv/c-ray/blob/master/src/raytrace.c#L483
The actual raytrace function that takes the scene and light ray, and returns a colour value.

Problem:

Lighting is calculated incorrectly. Shadows are shown where there is no object between the point observed, and a given light.

More recent detail of the bug (The red lamp highlights the issue):

Another angle of the problem, to show it's not dependent on the camera position:

All the lamps are supposed to cast light uniformly in all directions, but these images show otherwise.

The source of the problem is here:
https://github.com/VKoskiv/c-ray/blob/master/src/raytrace.c#L611

The inShadow parameter is incorrectly set to true
If we change that line to inShadow = false;, thus disabling all the shadows for the OBJ 3D models, the problem does go away. This isn't a solution though.

This is what it looks like with that change:

Note, how the spheres still have shadows, as that is calculated separately.

Progress feedback goes at fastest thread pace

If one thread finishes faster than others, render progress will be inaccurate

Scene is hardcoded (input.txt unused)

Rework scene building and reintroduce a logical scene.txt configuration format

Move renderTile to it's own header.

Remove void test_list() from list.h (unused)

Rendertime display is inaccurate

Break up transforms.h into two different files with only relevant structs.

calculateUVW doesn't exist anywhere

Either remove it from camera.h or add the code in camera.c

Implement better boundingVolume geometry

Currently the boundingVolume is a sphere, which is rather inefficient.

Render image in stages

Render each sample into a buffer, then average with previous sample. This way user gets more immediate feedback.

Currently each pixel is rendered fully before being stored to buffer

transformMesh() crashes on PowerPC 7xx series.

Happens here.

No clue why. Presumably it doesn't allocate tformed properly, so when it tries to deference it with an offset to pass a ref to transformVector, it crashes.
The exact segfault as reported by gdb is KERN_INVALID_ADDRESS.

Worth noting that this is a 32-bit big-endian platform.
Works fine on all x86_64 systems I've tested it on.

Put lightRay into it's own header

rayIntersectsWithSphereFast seems like a feature of lightRay, not sphere

I'd put this (and the other functions like this) in lightRay.h

Move threadInfo to it's own header.

filehandler.h has old style enums, convert to new and move to shared location

Implement spectral rendering

Camera lookAt not implemented

Implement a JSON scene parser

C-Ray should parse the scene definition from a JSON file:
./c-ray ./input/scene.json

And when arguments are not provided, read the JSON from stdin
cat input/scene.json | c-ray

This way implementing a separate launcher should be easier.

For the JSON parsing, I was considering the following lib:
https://github.com/kgabis/parson

Windows processor groups aren't handled properly

Windows divides systems with more than 40 cores to multiple processor groups. C-ray spawns the right amount of threads according to the physical core count, but only uses half available physical cores.

Implement instancing

Terrible performance on Linux

Abnormally low performance under more recent Linux kernels. Seems to spend vast amounts of time in kernel space for some reason.
Unable to debug further at this point.

Implement DOF for camera

old rayTrace() not working anymore

For some reason, it just returns all black.

File output dir is hard-coded