/*
 *  Copyright (C) 2006 Boudewijn Rempt <boud@valdyas.org>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */

/**
  \mainpage LibBrush

  March 2008

<h1>About libbrush</h1>

libbrush is a library for handling brush resources. Brush resources
should not be confused with brush engines (or paintops). Brush engines
may or may not use a brush resource. Basically, brush resources provide
an image to make "footprints" with on the canvas, like with a potato
stamp.

A brush's task is to basically return an image or a mask (depending on
the type) when the brush engine asks for it. The KisBrush class can
also keep a set of prescaled brush images or masks, which is handy
when using the pressure-size curve option for tablets.

There are several kinds of brush types:

<ul>
 <li> gbr: Gimp one-image brushes, either a grayscale mask or a coloured image.
        There are also 16-bit .gbr brushes, created and used by CinePaint.
        Krita is compatible with those, too.
 <li> gih: Gimp image hose brushes. Image hoses contain a set of images and
        some instructions to determine which image comes next
 <li> custom: this brush is generator from the image or a selection of the image
           and can be saved as an ordinary gbr or gih brush.
 <li> text: a basic brush created from some text and a font
 <li> auto: a brush defined from a shape and some parameters.
</ul>

Other applications support other types of brushes:

<ul>
 <li> png: krita used to use png images in stead of gbr brushes, and there
        are (march 2009) some noises that GIMP might want to use png
        brushes again.
 <li> svg: defining brushes in svg format has the advantage that scaling is
        lot nicer.
 <li> abr: photoshop's brush format. Early versions are open, later versions
        are closed
 <li> painter: Corel Painter has its own closed brush format that would be
        interesting to support
 <li> myb: mypaint brushes. Open source and we really should try to support
        them, though it may only be useful for a special-built paintop.
</ul>

Right now there is no way to categorize brushes into sets: there is some
GIMP code that allows users to tag resources, but it is not easy to use
that to deliver brush sets that are pre-tagged.

<h2>Architecture</h2>

The original brush resource architecture used a resource server,
resource mediator and resource chooser. It was impossible to retrieve
a specific brush by name or to serialize and deserialize brushes.
We are transitioning to the ordinary Krita
registry/factory/instance/settings/settings widget  pattern, where
the registry loads plugins, the plugins add a factory to the registry
and provides instances to the application.  For now, it's still a
bit mixed.

Brush plugins cannot yet provide a gui for editing or choosing a brush;
all brush plugins must add the brushes they load to the brush resource
server. The interaction is as follows:

<ul>
 <li> KisBrushRegistry is instantiated
 <li> KBR loads all plugins
 <li> Plugins instantiate a factory and add it to the KBR
 <li> The KBR asks the factories to load existing resources
 <li> The factories add the existing resources to the KisBrushServer
</ul>

<h2>Serializing and deserializing, and creating brushes</h2>

Brushes have a toXML function that can be used to store a brush with
settings in an xml file, for instance for action recording or paintop
presets. The xml _must_ contain a brush_type_id.

The KisBrushRegistry has a getOrCreate method that takes this xml and
determines which bruhs factory to use: the brush factory then analyzes
the xml and determines whether to create a new brush or retrieve an
instance of a loaded brush.

The KisBrush::fromXML method hides all this complexity from the user.

<h2>Widgets</h2>

Currently, all brush settings widgets are in libpaintop. If we want completely
independent brush plugins or use libbrush from other places, like some filters,
we need to move the widgets in here.

*/
