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 @jucelink{JUCE framework}, which can be obtained from GitHub @jucegithub{here}.

@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.

Generate a Projucer project from the PIP file located in the @s_file{JUCE/examples/BLOCKS/} folder, then navigate to the @s_file{BlocksDrawingDemo/Builds/} 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 @s_item{[1]} (for more details on how the %LEDGrid object operates, see @ref controlling_led_grids).

@code{.cpp}
    void topologyChanged() override
    {
        //...
        auto blocks = topologySource.getCurrentTopology().blocks;

        for (auto b : blocks)
        {
            if (b->getType() == Block::Type::lightPadBlock)
            {
                activeBlock = b;

                //...
                if (auto grid = activeBlock->getLEDGrid()) // [1]
                {
                    //...
                    setLEDProgram (*activeBlock);          // [2]
                }
                //...
            }
        }
    }
@endcode

In the @s_projcode{topologyChanged()} method of @s_projcode{BlocksDrawingDemo} this %LEDGrid pointer is passed to the @s_projcode{setLEDProgram()} method @s_item{[2]}, which sets the Block::Program to either a DrumPadGridProgram @s_item{[3]} or a BitmapLEDProgram @s_item{[4]}, depending on the selected mode.

@code{.cpp}
    void setLEDProgram (Block& block)
    {
        if (currentMode == canvas)
        {
            block.setProgram (new BitmapLEDProgram (block));   // [4]
            //...
        }
        else if (currentMode == colourPalette)
        {
            block.setProgram (new DrumPadGridProgram (block)); // [3]
            //...
        }
    }
@endcode

@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 is retrieved by calling the @s_projcode{getPaletteProgram()} helper function of @s_projcode{BlocksDrawingDemo} and in the @s_projcode{BlocksDrawingDemo::setLEDProgram()} method the %Block::Program is set to point to a new %DrumPadGridProgram object and is passed the %Block object of the Lightpad in its constructor.

@code{.cpp}
    DrumPadGridProgram* getPaletteProgram()
    {
        if (activeBlock != nullptr)
            return dynamic_cast<DrumPadGridProgram*> (activeBlock->getProgram());

        return nullptr;
    }
@endcode

After the program has been initialised, it is passed to the LEDGrid to display using the Block::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 @s_projcode{GridFill} for each pad that controls its colour and fill type.

@code{.cpp}
    void setLEDProgram (Block& block)
    {
        //...
        else if (currentMode == colourPalette)
        {
            //...
            if (auto* program = getPaletteProgram())
                program->setGridFills (layout.numColumns, layout.numRows, layout.gridFillArray);
        }
    }
@endcode

The @s_projcode{ColourGrid} struct contains all of this information and handles the construction of the @s_projcode{GridFill} array in the @s_projcode{ColourGrid::constructGridFillArray()} method.

@code{.cpp}
    void constructGridFillArray()
    {
        gridFillArray.clear();

        auto counter = 0;

        for (auto i = 0; i < numColumns; ++i)
        {
            for (auto j = 0; j < numRows; ++j)
            {
                DrumPadGridProgram::GridFill fill;
                Colour colourToUse = colourArray.getUnchecked (counter);

                fill.colour = colourToUse.withBrightness (colourToUse == currentColour ? 1.0f : 0.1f);

                if (colourToUse == Colours::black)
                    fill.fillType = DrumPadGridProgram::GridFill::FillType::hollow;
                else
                    fill.fillType = DrumPadGridProgram::GridFill::FillType::filled;

                gridFillArray.add (fill);

                if (++counter == colourArray.size())
                    counter = 0;
            }
        }
    }
@endcode

An instance of this object called @s_projcode{layout} is declared as a member variable of @s_projcode{BlocksDrawingDemo} to easily change how the grid looks.

@code{.cpp}
ColourGrid layout { 3, 3 };
@endcode

The @s_projcode{ColourGrid::setActiveColourForTouch()} method is called in the @s_projcode{BlocksDrawingDemo::touchChanged()} callback and is used to determine which brush colour has been selected based on a Touch coordinate from the Lightpad.

@code{.cpp}
    bool setActiveColourForTouch (int x, int y)
    {
        auto colourHasChanged = false;

        auto xindex = x / 5;
        auto yindex = y / 5;

        auto newColour = colourArray.getUnchecked ((yindex * 3) + xindex);
        if (currentColour != newColour)
        {
            currentColour = newColour;
            constructGridFillArray();
            colourHasChanged = true;
        }

        return colourHasChanged;
    }
@endcode

When the application is run, the colour palette mode would look like this:

@image html BlocksDrawing_palette.JPG "Colour palette mode"

@section blocks_drawing_canvas Canvas

In canvas mode, the %Block 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 @s_projcode{ActiveLED} struct declared in the private section of @s_projcode{BlocksDrawingDemo} is used to keep track of which LEDs are on and their colour and brightness. @s_projcode{BlocksDrawingDemo} contains an %Array of these objects called @s_projcode{activeLeds}.

@code{.cpp}
    struct ActiveLED
    {
        uint32 x, y;
        Colour colour;
        float brightness;
        //...
    };

    Array<ActiveLED> activeLeds;
@endcode

In the @s_projcode{BlocksDrawingDemo::setLEDProgram()} method the program is set up and passed to the %LEDGrid object the same way as in the colour palette mode but the @s_projcode{BlocksDrawingDemo::redrawLEDs()} method is also called which iterates over the @s_projcode{activeLeds} array and sets the appropriate LEDs on the Lightpad so the LED states persist between mode switches.

@code{.cpp}
    void redrawLEDs()
    {
        if (auto* canvasProgram = getCanvasProgram())
        {
            for (auto led : activeLeds)
            {
                canvasProgram->setLED (led.x, led.y, led.colour.withBrightness (led.brightness));
                lightpadComponent.setLEDColour (led.x, led.y, led.colour.withBrightness (led.brightness));
            }
        }
    }
@endcode

When a Touch is received in the @s_projcode{BlocksDrawingDemo::touchChanged()} callback the @s_projcode{BlocksDrawingDemo::drawLEDs()} method is called with 4 arguments: x and y coordinates, touch pressure and brush colour. This method iterates over the @s_projcode{activeLed} array and checks to see if there is an active LED at the given coordinate. If it is blank, an @s_projcode{ActiveLED} 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.

@code{.cpp}
    void drawLED (uint32 x0, uint32 y0, float z, Colour drawColour)
    {
        if (auto* canvasProgram = getCanvasProgram())
        {
            auto index = getLEDAt (x0, y0);

            if (drawColour == Colours::black)
            {
                if (index >= 0)
                {
                    canvasProgram->setLED (x0, y0, Colours::black);
                    lightpadComponent.setLEDColour (x0, y0, Colours::black);
                    activeLeds.remove (index);
                }

                return;
            }

            if (index < 0)
            {
                ActiveLED led;
                led.x = x0;
                led.y = y0;
                led.colour = drawColour;
                led.brightness = z;

                activeLeds.add (led);
                canvasProgram->setLED (led.x, led.y, led.colour.withBrightness (led.brightness));

                lightpadComponent.setLEDColour (led.x, led.y, led.colour.withBrightness (led.brightness));

                return;
            }

            auto currentLed = activeLeds.getReference (index);

            if (currentLed.colour == drawColour)
                currentLed.brightness = jmin (currentLed.brightness + z, 1.0f);
            else
                currentLed.colour = currentLed.colour.interpolatedWith (drawColour, z);

            if (canvasProgram != nullptr)
                canvasProgram->setLED (currentLed.x, currentLed.y, currentLed.colour.withBrightness (currentLed.brightness));

            lightpadComponent.setLEDColour (currentLed.x, currentLed.y, currentLed.colour.withBrightness (currentLed.brightness));

            activeLeds.set (index, currentLed);
        }
    }
@endcode

When the application is run, the canvas mode would look like this:

@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 %Block::Program object to display basic grids and set individual LEDs on the Lightpad.

@section blocks_drawing_see_also See also

- @ref example_blocks_monitor
- @ref example_blocks_synth

*/