Skip to content

Commit

Permalink
fix: Check documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
MiguelMJ committed Feb 16, 2021
1 parent f9150bf commit 05dd1d8
Show file tree
Hide file tree
Showing 8 changed files with 48 additions and 45 deletions.
6 changes: 3 additions & 3 deletions doc/md/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ cmake --build .

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

If it happens that CMake can't find the SFML files, you might need to set manually `SFML_ROOT` inside the `CMakeLists.txt` (uncomment and complete line 15).
If CMake can't manage to find the SFML files, you might need to set `SFML_ROOT` inside the `CMakeLists.txt` manually (uncomment and complete line 15).

# Make

Expand All @@ -28,10 +28,10 @@ For Linux users, the old Candle build system is still available. You just have t
make release
```

to build `libCandle-s.a` and the `demo` program inside the folder `release`. Alternatively, you can use
to build `libCandle-s.a` and the `demo` program inside the `release` folder. Alternatively, you can use

```shell
make debug
```

to build the debug version inside the folder `debug`.
to build the debug version inside the `debug` folder.
14 changes: 7 additions & 7 deletions doc/md/demo_manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The [**Candle source code**](https://github.com/MiguelMJ/Candle) comes with a demo program that you can [build](@ref build) along with the library. It is also the one used to illlustrate almost everything in the official documentation.

It consists of a canvas with a background of colored tiles and eight buttons on the side, to access the brushes and ease some common manipulations. However, there is much more to it that what is available through the minimalistic GUI. Also, in the window title, it appears the framerate both in fps and ms and two counters for the number of lights and edges in the scene
It consists of a canvas with a background of colored tiles and eight buttons on the side, to access the brushes and make some common manipulations easier. However, there is much more to it than what is available through the minimalistic GUI. Also, in the window title, the framerate both in fps and ms and two counters for the number of lights and edges in the scene are displayed.

<div align="center">
<img src="demo_1.png" width="400px" alt="Demo schema">
Expand All @@ -28,17 +28,17 @@ It consists of a canvas with a background of colored tiles and eight buttons on
- **Customize brush - Block**
- **[Mouse wheel]** Modify block size
- **Customize brush - All**
- **[Ctrl]** Maintain it pressed to fix the position of the brush to discrete values.
- **[Ctrl]** Hold to fix the position of the brush to discrete values.
- **Modify fog/ambience light**
- **[M]** Alternates between fog mode with black color an ambient light with yellow color.
- **[T]** In fog mode, disables clearing the lighting area to get a [fog of war](https://en.wikipedia.org/wiki/Fog_of_war#In_video_games) effect.
- **[M]** Alternate between fog mode with black color and ambient light with yellow color.
- **[T]** In fog mode, disable clearing the lighting area to get a [fog of war](https://en.wikipedia.org/wiki/Fog_of_war#In_video_games) effect.
- **[Z]** Decrease the opacity of the fog/ambience light . (5)
- **[A]** Increase the opacity of the fog/ambience light. (6)
- _Use a texture_. Before you launch the program, put a PNG image in the working directory called `texture.png`, and it will use it as the LightingArea texture.
- **Clear the scene**
- **[Shift + Space]** All lights are removed from the scene. (7)
- **[Alt + Space]** All edges are removed from the scene. (8)
- **[Space]** Both edges and lights are removed from the scene.
- **[Shift + Space]** Remove all lights from the scene. (7)
- **[Alt + Space]** Remove all edges from the scene. (8)
- **[Space]** Remove all elements from the scene.
- **Window**
- **[Q]** or **[Esc]** Quit the demo.
- **[P]** Capture an image of the canvas and save it in the working directory.
12 changes: 6 additions & 6 deletions doc/md/fog_ambiental.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

# Fog and darkness

Light sources alone can become somewhat noisy in the scene. They make much more sense when they exist within an area of darkness, that they illuminate. For such purpose, Candle provides the class candle::LightingArea, that operates in two modes: FOG and AMBIENCE. We will focus in the first one right now.
Light sources alone can become somewhat noisy in the scene. They make much more sense when they exist within an area of darkness, which they illuminate. For this, Candle provides the class candle::LightingArea, that operates in two modes: FOG and AMBIENT. We will focus on the first one right now.

A lighting area in FOG mode behaves as a mask, and when objects candle::LightSource are drawn to it, they makes transparent the illuminated polygon, taking into account its intensity and the fade flag. You can think of this class as a wrapper to a sf::RenderTexture, as you have to use clear, draw and display functions. Let's see a minimalistic example:
A lighting area in FOG mode behaves as a mask, and when objects candle::LightSource are drawn to it, they make transparent the illuminated polygon, taking into account its intensity and the fade flag. You can think of this class as a wrapper to a sf::RenderTexture, as you have to use clear, draw and display functions. Let's see a minimalistic example:

@include gettingstarted2.cpp

Expand All @@ -17,7 +17,7 @@ This time the fade flag is set to false to make the contrast stronger. The previ
<br><em>Preview</em>
</div>

Also, note that the light is not drawn to the window. If we did that, then the light itself could cover the image below. This doesn't mean that there aren't cases when you will want to draw the light both to the lighting area and the window, but you will have to experiment and adjust the range and intensity parameters, to obtain the desired effect.
Also, note that the light is not drawn to the window. If we did that, then the light itself could cover the image below. This doesn't mean that there aren't cases when you will want to draw the light both to the lighting area and the window, but you would have to experiment and adjust the range and intensity parameters, to obtain the desired effect.

## Texturing fog

Expand All @@ -32,15 +32,15 @@ and we would have this result:
<br><em>Preview</em>
</div>

This example also allows us to illustrate how to manage size. An object candle::LightingArea uses internally a sf::RenderTexture, and to avoid destroying and creating repeteadly a potentially heavy resource, it is created only upon construction or when using candle::LightingArea::setAreaTexture. So, if we want to change the size of the area (in this case we want to adjust it to the size of the window), the only way is to scale it.
This example also allows us to illustrate how to manage size. An object candle::LightingArea uses a sf::RenderTexture internally, and to avoid destroying and creating a potentially heavy resource repeteadly, it is created only upon construction or when using candle::LightingArea::setAreaTexture. So, if we want to change the size of the area (in this case we want to adjust it to the size of the window), the only way is to scale it.

## Revealing permanently (fog of war effect)

For now we have been calling candle::LightingArea::clear before any draw call. If we don't do this, then the darkness layer isn't restored. This way, we can have the effect of revealing permanently what is under it.
For now we have been calling candle::LightingArea::clear before any draw call. If we don't do this, then the darkness layer isn't restored. This way, we can have the effect of permanently revealing what is under it.

# Ambient light

The second operation mode of candle::LightingArea is AMBIENT. Its behaviour is rather simple, as it acts as a mere additive layer. Be it a plain color or a texture, they are overlayed to the layer below. Drawing lights in it has no effect, but as light sources are also drawn in an additive manner, then lights within the area will appear to have more intensity.
The second operation mode of candle::LightingArea is AMBIENT. Its behaviour is rather simple, as it acts as a mere additive layer. Be it a plain color or a texture, they are overlayed to the layer below. Drawing lights to it has no effect, but as light sources are also drawn in an additive manner, then lights within the area will appear to have more intensity.

<table width="100%">
<tr>
Expand Down
10 changes: 5 additions & 5 deletions doc/md/lights_shadows.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

The two main objects related to shadow casting in Candle are light sources and edges.

For the lights, there is an abstract class called candle::LightSource, implemented by candle::RadialLight and candle::DirectedLight. They inherit for sf::Drawable and sf::Transformable, so they can be used as the more common SFML entities.
For the lights, there is an abstract class called candle::LightSource, implemented by candle::RadialLight and candle::DirectedLight. They inherit from sf::Drawable and sf::Transformable, so they can be used as common SFML entities.

For the edges, there is a structure called [**candle::Edge**](LightSource_8hpp.html#a232f746b6098d9a876d23e84a67dc0a2), that can represent a segment by the coordinates of its ends. However, the raycasting function requires that the shadow casting edges are stored in a `std::vector`, so Candle provides a convenient alias for `std::vector<candle::Edge>` called [**candle::EdgeVector**](LightSource_8hpp.html#a384b0e96a22f34b27f84a55713279e89). This is what you should be using to manage your edges.

Expand All @@ -16,11 +16,11 @@ Let's see with a sample of code.

@include gettingstarted1.cpp

The previous code results in a light that follows the mouse and a vertical edge in the center of the screen.
The previous code results in a light that follows the pointer and a vertical edge in the center of the screen.

<div align="center"><img src="example.gif" width="250px"><br><em>Preview</em></div>

Note how the `castLight` function is called only when the mouse is moved. Although it shouldn't cost much when a light has a normal amount of edges in range, is preferable not to abuse it unnecesarily. Therefore, we will call it only when the light has been modified or the edges in range have moved.
Note how the `castLight` function is called only when the mouse is moved. Although it shouldn't be very expensive when a light has a normal amount of edges in range, it is preferable not to abuse it unnecesarily. Therefore, we will call it only when the light has been modified or the edges in range have moved.

# Radial light and Directed light

Expand All @@ -42,7 +42,7 @@ Candle doesn't behave well when segments intersect. The reason is that lights pr
<td align="center"> <img width="300px" src="intersection_2.png" alt="Intersection of edge and directed light example"> <br> <em>Second case: Intersection between an edge and the source of a directed light</em> </td>
</tr>
</table>
You should avoid this when disposing the edges and lights in the scene.
You should avoid this when placing the edges and lights in the scene.

# Customizing the lights

Expand Down Expand Up @@ -74,7 +74,7 @@ Plain color of the light.
</div>
### Range

Max range of the iluminated area.
Max range of the illuminated area.

- candle::LightSource::getRange
- candle::LightSource::setRange
Expand Down
10 changes: 5 additions & 5 deletions include/Candle/DirectedLight.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ namespace candle{
*
* A DirectedLight is defined, mainly, by the direction of the rays, the
* position of the source, the beam width and the range of the light. You
* can manipulate the two first transforming changing the rotation and
* position as you would do with any sf::Transformable. The range can
* can manipulate the first two changing the rotation and
* position as you would with any sf::Transformable. The range can
* be manipulated as with other LightSources, with
* @ref LightSource::setRange, and the beam width with @ref setBeamWidth.
*
* <table width="100%">
* <tr>
* <td align="center"> <img src="directed_1.png" width="300px"> <br> <em>Variables schema</em> </td>
* <td align="center"> <img src="directed_1.png" width="300px"> <br> <em>Variables diagram</em> </td>
* <td align="center"> <img src="directed_2.png" width="300px"> <br> <em>Demo example</em> </td>
* </tr>
* </table>
Expand All @@ -43,8 +43,8 @@ namespace candle{
/**
* @brief Set the width of the beam.
* @details The width specifies the maximum distance allowed from the
* center of segment to cast a ray, along a segment normal to the ligh
* direction.
* center of the segment to cast a ray, along a segment normal to the
* light direction.
* @param width Width of the beam.
* @see getBeamWidth
*/
Expand Down
8 changes: 4 additions & 4 deletions include/Candle/LightSource.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@ namespace candle{
* separately.
*
* By default, they use a sf::BlendAdd mode. This means that you can
* specify any other blend mode you want except sf::BlendAlpha, that
* will be converted to the additive mode.
* specify any other blend mode you want, except sf::BlendAlpha, that
* will be changed to the additive mode.
*/
class LightSource: public sf::Transformable, public sf::Drawable{
private:
Expand Down Expand Up @@ -158,9 +158,9 @@ namespace candle{
float getRange() const;

/**
* @brief Modifies the polygon of the illuminated area with a
* @brief Modify the polygon of the illuminated area with a
* raycasting algorithm.
* @details The algorithm needs to know what edges to use to cast
* @details The algorithm needs to know which edges to use to cast
* shadows. They are specified within a range of two iterators of a
* vector of edges of type @ref sfu::Line.
* @param begin Iterator to the first sfu::Line of the vector to take
Expand Down
21 changes: 11 additions & 10 deletions include/Candle/LightingArea.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -42,13 +42,14 @@ namespace candle{
* <img width="300px" src="lightingArea04.png"> <br> <em>LightingArea in FOG mode with texture</em>
* </div>
*
* As the sf::RenderTexture may be a heavy resource to be creating, there
* is only two moments in which you are able to do so. The first one and
* most common is upon construction, where you can specify the size of the
* area, that will be the size of the sf::RenderTexture. The second one is
* upon the assignation of a texture (with @ref setAreaTexture), on which
* the area is created again to match the size of the new texture.
*
* As the sf::RenderTexture may be a heavy resource to be creating
* repeteadly, there are only two moments in which you are able to do so.
* The first one and most common is upon construction, where you can
* specify the size of the area, which will also be the size of the
* sf::RenderTexture. The second one is upon the assignment of a texture
* (with @ref setAreaTexture), on which the area is created again to match
* the size of the new texture.
*
* There are two things to note about this:
* 1. To change the size of a LightingArea that has already been
* constructed, without changing the base texture, you have to scale it as
Expand All @@ -66,8 +67,8 @@ namespace candle{
*/
enum Mode {
/**
* In this mode, the area behaves like a mask through which is only
* possible to see by drawing light on it.
* In this mode, the area behaves like a mask through which it is
* only possible to see by drawing light on it.
*/
FOG,
/**
Expand All @@ -86,7 +87,7 @@ namespace candle{
sf::Vector2f m_size;
Mode m_mode;
/**
* @brief Function to draw all the fog and the light sources.
* @brief Draw the object to the target.
*/
void draw(sf::RenderTarget&, sf::RenderStates)const override;
sf::Color getActualColor() const;
Expand Down
12 changes: 7 additions & 5 deletions include/Candle/RadialLight.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,13 @@ namespace candle{
* @brief LightSource that emits light from a single point
* @details
*
* A RadialLight is defined, mainly, by the origin of the rays, the range of the light, the
* beam angle and its aperture. To manipulate the position and the orientation of the light,
* you can change the position and rotation of the object as you would do with any
* sf::Transformable. The range can be manipulated as with other LightSources, with
* @ref LightSource::setRange, and the angle of the beam with @ref setBeamAngle.
* A RadialLight is defined, mainly, by the position, the orientation, the
* range of the light and the beam angle. To manipulate the
* position and the orientation of the light, you can change the position
* and rotation of the object as you would do with any sf::Transformable.
* The range can be manipulated as with other LightSources, with
* @ref LightSource::setRange, and the angle of the beam with
* @ref setBeamAngle.
*
* <table width="100%">
* <tr>
Expand Down

0 comments on commit 05dd1d8

Please sign in to comment.