Candle

2D lighting for SFML

Candle is a SFML based C++ library that provides light, shadow casting and field of view functionalities with easy integration.

Demo
- Controls
- Build
Requisites
Example program
Contributors
Contributing
License

Demo

Before anything, here you have a little example of how it looks.

The code comes with a demo program showing the basic functionalities provided by the library. In it you can place lights and blocks that will cast shadows, and modify the opacity of the fog.

Controls

Right click. Alternate between block and light.
Left click. Put a block or light.
Spacebar. Erase all lights and blocks.
Mouse wheel. Increase / Decrease light radius.
G. Toggle glow.
C. Alternate glow color between white, magenta, yellow and cyan.
A / S. Increase / Decrease light intensity.
Z / X. Increase / Decrease fog opacity.
P. Capture the window content and save it to a png file in the current working directory.

Build

You can build the static library and the demo program with CMake.

mkdir build && cd build
cmake .. -DBUILD_DEMO=ON
cmake --build .

This will generate libCandle-s.a or (Candle-s.lib on Windows) in build/lib folder, and demo program (or demo.exe) in build/bin.

Requisites

SFML v2.5.1
- Graphics module and System module.

This library is meant to be used in SFML applications, so it's assumed that you are familiar with the process of compiling them. If you are not, you can learn in the official website .

Example program

I will assume that you have SFML installed in your system. If we have a project with the following structure:

|- project
   |- libCandle-s.a
   |- main.cpp
   |- include
      |- Candle   # Candle headers
         |- Lighting.hpp
         |- LightSource.hpp
         |- Util.hpp

the main.cpp file could look like this:

#include <SFML/Graphics.hpp>
#include "Candle/Lighting.hpp"

int main(){
    // create window
    sf::RenderWindow w(sf::VideoMode(400,400), "app");
    
    // create the lighting area
    candle::Lighting lighting;
    lighting.setFogOpacity(0.6);
    lighting.adjustFog(w.getView());
    lighting.updateFog();
    
    // create the light and a shadow to cast
    candle::LightSource light;
    light.setRadius(150);
    lighting.addLightSource(&light);
    lighting.m_segmentPool.push_back({{200,100},{200,300}});
    
    // main loop
    while(w.isOpen()){
        sf::Event e;
        while(w.pollEvent(e)){
            if(e.type == sf::Event::Closed){
                w.close();
            }else if(e.type == sf::Event::MouseMoved){
                // make the light follow the mouse
                sf::Vector2i mpi = sf::Mouse::getPosition(w);
                light.setPosition(sf::Vector2f(mpi.x,mpi.y));
                light.castLight();
            }
        }
        
        w.clear();
        w.draw(lighting);
        w.display();
    }
	return 0;
}

We can compile it with the following command:

g++ -o app main.cpp -Iinclude -L. -lCandle-s -lsfml-graphics -lsfml-window -lsfml-system

And we run it

./app

The result will be a simple light casting a shadow over an invisible wall in the center of the window.

Contributors

Modar Nasser - Bug report · Code

Contributing

Here's a To Do list for Candle:

Currently this library needs more testing and documentation.
- Performance tests - this library is not yet optimized.
- Functionality tests - there may be bugs I haven't found yet.
- Tutorials and examples.
- Documentation review - the documentation still needs some more writing and maybe spell checking.
The functionalities of the library are enough for a basic lighting system, but there is still room for more complex behaviours.
- Some of the features I plan to implement are:
  - More type of light sources (directional, flashlight, etc).
  - More customization for the light intensity - Currently is simply linear; maximum intensity in the origin, zero in the radius; I'd like to add more options to customize that.
- If you want to request some feel free to open a new issue or even implement it and make a pull request.
Use of several technologies I'm still not very familiar with.
- Use shaders to blur the light or create a penumbra effect.
- Implement the algorithms with Box2D ray casting and add a compiler option to use them instead of the ones I coded (this feature is inspired by the optional use of fmtlib in the loguru project).
Finally, you can still ⭐ star this repository and give it some visibility .

License

Candle uses the MIT license, a copy of which you can find here, in the repo.

It uses the external library SFML, that is licensed under the zlib/png license.

sk-landry / Candle