Skip to content

Commit

Permalink
meta: Clean up README slightly
Browse files Browse the repository at this point in the history 
It's long overdue a rewrite, but I'm not very good at marketing, so I'll
just keep the current one for a while longer :^)
  • Loading branch information
@vkoskiv
vkoskiv committed Jan 1, 2024
1 parent dd318b8 commit 322bba6
Showing 1 changed file with 60 additions and 72 deletions.
132 changes: 60 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@
<img src="https://i.imgur.com/fPBuCTG.png" width="256">
</p>

# c-ray

A portable, hackable, embeddable software path tracer.

## Status

[![Build Status](https://github.com/VKoskiv/c-ray/workflows/C-ray%20CI/badge.svg)](https://github.com/VKoskiv/c-ray/actions?query=workflow%3A%22C-ray+CI%22)
[![justforfunnoreally.dev badge](https://img.shields.io/badge/justforfunnoreally-dev-9ff)](https://justforfunnoreally.dev)

## Example renders

<p align="center">
Expand All @@ -17,74 +26,74 @@
<br>(512 samples, 2560x1600, 30 max bounces, 8min)
</p>

## Status

[![Build Status](https://github.com/VKoskiv/c-ray/workflows/C-ray%20CI/badge.svg)](https://github.com/VKoskiv/c-ray/actions?query=workflow%3A%22C-ray+CI%22)
[![justforfunnoreally.dev badge](https://img.shields.io/badge/justforfunnoreally-dev-9ff)](https://justforfunnoreally.dev)

## Synopsis

C-ray is a research oriented, hackable, offline CPU rendering engine built for learning. The source code is intended to be readable wherever possible, so feel free to explore and perhaps even expand upon the current functionality. See the [contributing section](https://github.com/vkoskiv/c-ray/wiki/Contributing) in the wiki for more details.

C-ray currently has:
- [Cluster rendering support](https://github.com/vkoskiv/c-ray/wiki/Using-cluster-rendering) (on \*nix systems)
- A node-based material system
- A simple unidirectional Monte Carlo integrator
- Real-time render preview using SDL2
- Easy scene compositing using a JSON interface
- Multithreading (using pthreads or WIN32 threads)
- Wavefront OBJ support
## 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](https://github.com/vkoskiv/c-ray/wiki/Contributing) in the wiki for more details.

An incomplete list of features:
- [Cluster rendering support over TCP/IP](https://github.com/vkoskiv/c-ray/wiki/Using-cluster-rendering)
- [A C API](https://github.com/vkoskiv/c-ray/blob/master/include/c-ray/c-ray.h)
- [Python bindings](https://github.com/vkoskiv/c-ray/blob/master/bindings/c_ray.py)
- [A Blender add-on](https://github.com/vkoskiv/c-ray/blob/master/bindings/blender_init.py)
- 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
- PNG and BMP file output
- Two levels of BVH acceleration structures (by @madmann92)
- Antialiasing (MSAA)
- HDR environment maps for realistic lighting
- Gouraud interpolated smooth shading
- Benchmarking metrics

The default integrator supports:
- Metal
- Glass
- Lambertian diffuse
- Plastic
- Triangles and spheres
- Depth of field
- Russian Roulette path optimization
- Diffuse textures
- Normal maps

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
- Built a more robust API with an interactive scene state.
- Some procedural textures
- Python API wrapper
- Volumetric rendering
- Subsurface scattering
- Spectral rendering
- More cool advanced techniques from research literature

## Compatibility
## Portability

C-ray has been verified to work on the following architectures
c-ray has been verified to work on the following architectures
- x86 & x86\_64 (Primarily developed on x86\_64)
- ARMv6, ARMv7 and ARMv8 (Various Raspberry Pi systems)
- ARMv6, ARMv7 and ARMv8, AARCH64 (Various Raspberry Pi systems)
- PowerPC 7xx and 74xx (PowerPC G3 and G4 systems)
- MIPS R5000 ([1996 SGI O2](https://twitter.com/vkoskiv/status/1236419126555488257?s=20))
- SuperSPARC II ([1992 SUN SparcStation 10](https://twitter.com/vkoskiv/status/1234515380200235008?s=20))
- [WebAssembly with emscripten](https://github.com/ani003/c-ray/tree/wasm)

## Usage

Please see the [Wiki](https://github.com/VKoskiv/c-ray/wiki) for details on how to use the JSON scene interface.
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)
- Standard C99/GNU99 with some standard libraries

All other dependencies are included as source
## Tests

## Installation
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)
Expand Down Expand Up @@ -112,40 +121,19 @@ All the .json files in `input/` are test scenes provided with c-ray, assets for

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.

## Installing SDL

On macOS, use `homebrew` to install SDL. `brew install sdl2`

On Windows, download from `https://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip`

On Linux using APT, run `sudo apt install libsdl2-dev`

## 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`

## Credits

3rd party libraries included in this project

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
3rd party libraries included in this project include:

PCG random number generator: http://www.pcg-random.org
- 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](https://github.com/madmann91) for the new BVH accelerator and overall ~60% performance improvement!
- Huge thanks to [@madmann91](https://github.com/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!

Expand Down

0 comments on commit 322bba6

Please sign in to comment.