# Brush Tool Documentation

## Overview

The Brush Tool is a core component of the image editor that allows users to draw and erase on the canvas. It provides a flexible drawing experience with customizable brush size, color, and opacity. This document explains how the brush tool works and the relationships between its components.

## Key Files

- `js/imageeditor/shared/brush/brush.ts`: Main implementation of the brush tool
- `js/imageeditor/shared/brush/BrushOptions.svelte`: UI controls for brush settings
- `js/imageeditor/shared/brush/ColorPicker.svelte`: Color selection component
- `js/imageeditor/shared/brush/ColorSwatch.svelte`: Color swatch component
- `js/imageeditor/shared/brush/ColorField.svelte`: Color input field component
- `js/imageeditor/shared/brush/BrushSize.svelte`: Brush size slider component
- `js/imageeditor/shared/Toolbar.svelte`: Defines tool types and handles tool selection
- `js/imageeditor/shared/core/editor.ts`: Provides the editor context and tool interface

## Architecture

The brush tool follows the Tool interface defined in `editor.ts`. It integrates with the image editor through the `ImageEditorContext` which provides access to the PIXI.js application, containers, and other utilities.

### Class Structure

The `BrushTool` class implements the `Tool` interface and provides the following functionality:

1. **Drawing and Erasing**: Handles pointer events to draw or erase on the canvas
2. **Brush Customization**: Allows changing brush size, color, and opacity
3. **Preview**: Shows a preview of the brush before drawing
4. **Cursor**: Displays a custom cursor that reflects the current brush settings

### State Management

The brush tool maintains several state variables:

- `state`: Contains the current brush settings (opacity, size, color, mode)
- `brushSize` and `eraserSize`: Separate size settings for drawing and erasing
- `isDrawing`: Tracks whether the user is currently drawing
- `isCursorOverImage`: Tracks whether the cursor is over the image container

### Rendering Pipeline

The brush tool uses multiple PIXI.js textures and containers to manage the drawing process:

1. `left_texture`: Stores the final result that is displayed to the user
2. `right_texture`: Stores the current state before applying new strokes
3. `stroke_texture`: Temporarily stores the current stroke being drawn
4. `displayContainer`: Contains all visual elements of the brush tool
5. `stroke_container`: Contains the graphics for the current stroke
6. `erase_graphics`: Used for masking when in erase mode

### Drawing Process

1. **Pointer Down**: Initializes a new stroke, captures the starting position
2. **Pointer Move**: Draws line segments between points with interpolation for smooth strokes
3. **Pointer Up**: Commits the current stroke to the canvas
4. **Commit Stroke**: Merges the temporary stroke with the existing content

### Erasing Process

1. **Pointer Down**: Creates an erase mask at the starting position
2. **Pointer Move**: Extends the erase mask along the pointer path
3. **Pointer Up**: Applies the erase mask to the canvas
4. **Commit Stroke**: Merges the erased content with the existing content

## UI Components

### BrushOptions.svelte

Provides UI controls for:
- Color selection (via color picker or swatches)
- Brush size adjustment
- Recent colors management
- Brush preview

### Brush Preview

The brush tool can show a preview of the current brush in the center of the screen, which helps users understand the brush size and color before drawing.

## Event Handling

The brush tool sets up the following event listeners:

- `pointerdown`: Starts a new stroke
- `pointermove`: Continues the current stroke and updates the cursor position
- `pointerup`/`pointerupoutside`: Ends the current stroke
- Custom events for checking if the cursor is over the image container

## Integration with Editor

The brush tool integrates with the editor through:

1. **Tool Interface**: Implements the required methods (setup, cleanup, set_tool)
2. **Context Access**: Uses the ImageEditorContext to access the PIXI.js application and containers
3. **Tool Switching**: Handles transitions between drawing and erasing modes

## Performance Considerations

The brush tool uses several techniques to maintain performance:

1. **Point Interpolation**: Ensures smooth lines even with fast mouse movements
2. **Texture Management**: Efficiently manages textures to minimize memory usage
3. **Cursor Position Checking**: Uses debouncing to avoid excessive updates

## Customization API

The brush tool exposes several methods for customization:

- `setBrushSize(size)`: Sets the brush size
- `setBrushColor(color)`: Sets the brush color
- `setBrushOpacity(opacity)`: Sets the brush opacity
- `set_brush_size(size)`: Sets the brush size (only affects drawing mode)
- `set_eraser_size(size)`: Sets the eraser size (only affects eraser mode)
- `set_brush_color(color)`: Sets the brush color (only affects drawing mode)
- `preview_brush(show)`: Shows or hides the brush preview

## Maintenance Notes

When modifying the brush tool, consider the following:

1. **Texture Cleanup**: Always clean up textures to prevent memory leaks
2. **Event Listener Management**: Properly add and remove event listeners
3. **Mode Transitions**: Handle transitions between drawing and erasing modes carefully
4. **Scale Handling**: Account for the editor scale when drawing and displaying the cursor
5. **Cursor Visibility**: Manage cursor visibility based on the current tool and cursor position

## Future Improvements

Potential areas for enhancement:

1. **Brush Types**: Add support for different brush types (e.g., airbrush, pencil)
2. **Pressure Sensitivity**: Integrate with pressure-sensitive devices
3. **Performance Optimization**: Further optimize for large canvases
4. **Layer Support**: Improve integration with the layer system
5. **Undo/Redo**: Enhance undo/redo support for brush strokes