JUCE/extras/BLOCKS/doxygen/pages/juce_example_blocks_drawing.dox

/**
@page example_blocks_drawing BlocksDrawing

In order to compile and run this application you need to first download the <a href="https://www.juce.com/">JUCE framework</a>, which can be obtained from GitHub <a href="https://github.com/julianstorer/JUCE">here</a>.

@section blocks_drawing_introduction Introduction

BlocksDrawing is a JUCE application that allows you to use your Lightpad as a drawing surface. You can choose from a palette of 9 base colours and paint them on the 15x15 LED grid, blending between colours using touch pressure.

Navigate to the <tt>JUCE/examples/BLOCKS/BlocksDrawing/Builds/</tt> directory and open the code project in your IDE of choice. Run the application and connect your Lightpad (if you do not know how to do this, see @ref connecting_blocks) - it should now display a 3x3 grid of colours to choose from. Touch a colour to set it as the current brush colour and then press the mode button to switch to canvas mode where you will be presented with a blank touch surface. Touch anywhere on the LED grid to start painting and use the pressure of your touch to control how bright the colour is. Try painting over an already painted LED to increase its brightness and blend between different colours by doing this with a different brush colour. To clear the canvas and start over, double-click the mode button.

The concept of a BLOCKS topology and the methods for receiving callbacks from a Block object are covered in the @ref example_blocks_monitor example and this tutorial will cover the methods in the API for displaying grids and setting LEDs on the Lightpad.

@section blocks_drawing_led_grid The LEDGrid Object

Lightpads have a 15x15 LED grid which can be accessed and controlled through the LEDGrid object, a pointer to which is returned by the Block::getLEDGrid() method (for more details on how the %LEDGrid object operates, see @ref controlling_led_grids). In the <code>topologyChanged()</code> method of <code>MainComponent</code> this %LEDGrid pointer is passed to the <code>setLEDProgram()</code> method, which sets the LEDGrid::Program to either a DrumPadGridProgram or BitmapLEDProgram, depending on the selected mode.

@section blocks_drawing_colour_palette Colour Palette

In the colour palette mode the Lightpad displays a 3x3 grid of colours, constructed using the %DrumPadGridProgram class. A %DrumPadGridProgram pointer called <code>colourPaletteProgram</code> is declared as a private member variable of <code>MainComponent</code> and in the <code>MainComponent::setLEDProgram()</code> method this is set to point to a new %DrumPadGridProgram object and is passed the %LEDGrid object of the Lightpad in its constructor. After the program has been initialised, it is passed to the LEDGrid to display using the LEDGrid::setProgram() method and the layout of the grid is set up using the DrumPadGridProgram::setGridFills() method. This function takes 3 arguments: the number of rows, number of columns and an array of DrumPadGridProgram::GridFill objects containing a <code>GridFill</code> for each pad that controls its colour and fill type. The <code>ColourGrid</code> struct in MainComponent.h contains all of this information and handles the construction of the <code>GridFill</code> array in the <code>ColourGrid::constructGridFillArray()</code> method. An instance of this object called <code>layout</code> is declared as a member variable of <code>MainComponent</code> to easily change how the grid looks. The <code>ColourGrid::setActiveColourForTouch()</code> method is called in the <code>MainComponent::touchChanged()</code> callback and is used to determine which brush colour has been selected based on a Touch coordinate from the Lightpad.

\image html BlocksDrawing_palette.JPG "Colour palette mode"

@section blocks_drawing_canvas Canvas

In canvas mode, the %LEDGrid program is set to an instance of %BitmapLEDProgram and uses the BitmapLEDProgram::setLED() method to set individual LEDs on the Lightpad to a particular colour. The <code>ActiveLED</code> struct declared in the private section of <code>MainComponent</code> is used to keep track of which LEDs are on and their colour and brightness. <code>MainComponent</code> contains an %Array of these objects called <code>activeLeds</code>.
In the <code>MainComponent::setLEDProgram()</code> method the program is set up and passed to the %LEDGrid object the same way as in the colour palette mode but the <code>MainComponent::redrawLEDs()</code> method is also called which iterates over the <code>activeLeds</code> array and sets the appropriate LEDs on the Lightpad so the LED states persist between mode switches. When a Touch is received in the <code>MainComponent::touchChanged()</code> callback the <code>MainComponent::drawLEDs()</code> method is called with 4 arguments: x and y coordinates, touch pressure and brush colour. This method iterates over the <code>activeLed</code> array and checks to see if there is an active LED at the given coordinate. If it is blank, an <code>ActiveLED</code> object is created and added to the array with the given coordinates and colour using touch pressure for brightness. If there is already an active LED at the coordinate, the colour of that LED will be blended with the current brush colour, the proportion of which is determined by the touch pressure.

\image html BlocksDrawing_canvas.JPG "Unleash your inner Picasso!"

@section blocks_drawing_summary Summary

This tutorial and the accompanying code project have introduced the %LEDGrid object and shown how to use the %LEDGrid::Program object to display basic grids and set individual LEDs on the Lightpad.

*/