Goals
-----

This section describes how brushes are organized in the repository and how to make them available for you to use in GIMP (GNU Image Manipulation Program).

Description
-----------

A brush is a pixmap or set of pixmaps used for painting through an image manipulation program like GIMP.  Inside the repository, we've organized brushes in common brushes and theme-specific brushes.  In both cases, brushes are created under a Xcf directory as .xcf files first and later exported to .gbr or .gih format in the same level of Xcf directory.

1. Common brushes       2. Theme-specific brushes
----------------------  -----------------------------------------------------------
trunk/Identity/Brushes  trunk/Identity/Themes/Motifs/THEMENAME/THEMEVERSION/Brushes
|-- Xcf                 |-- Xcf
|   |-- 1.xcf           |   |-- 1.xcf
|   |-- 2.xcf           |   |-- 2.xcf
|   `-- 3.xcf           |   `-- 3.xcf
|-- 1.gbr               |-- 1.gbr
|-- 2.gih               |-- 2.gih
`-- 3.gbr               `-- 3.gbr
Figure: Brush file format and directory structure.

In order for both common brushes and theme-specific brushes to be loaded by GIMP, they need to be stored under ~/.gimp-2.2/brushes directory. Since files related to brushes already exist in the repository, there is no need to duplicate them in ~/.gimp-2.2/brushes directory, too.  Instead, we make use of symbolic links and file name convenctions to ``connect'' brushes created in the repository with the standard location they need to be stored in for GIMP to recognize them. In this configuration, when links to brushes are created, if someone commits a change for a brush you are using, that change will be immediatly available for you the next time you update your working copy and refresh the Brushes panel of GIMP.

When new brushes are added to or removed from the repository, it is required to update the connection between the brushes inside the repository working copy and the links created in the predifined location that GIMP uses to retrive them.  Otherwise you may end up with broken links or brushes in the repository which are not linked.

Inside the repository, common brushes and theme-specific brushes are created individually in different locations. However, they all are linked from one unique directory (i.e., ~/.gimp-2.2/brushes). This configuration may provoke overlapping of brushes if a name convenction is not implemented correctly.  In that sake, file names used for brushes inside the repository must be unique, no matter where they be.

As convenction inside the repository, brush files are named using a numerical value that start at 1 and increment one unit when a new brush is added to the same directory. Later, when links are built, we use one suffix for those brushes retrived from trunk/Identity/Brushes and another suffix for those brushes retrivided from theme-specific directories. Using both the numerical value and the suffix information,  it is possible to build unique names for links under ~/.gimp-2.2/brushes directory, scalably.

trunk/Identity/Brushes
|-- 1.gbr (file) <-- ~/.gimp-2.2/brushes/centos-1.gbr (link)
|-- 2.gbr (file) <-- ~/.gimp-2.2/brushes/centos-2.gbr (link)
`-- 3.gbr (file) <-- ~/.gimp-2.2/brushes/centos-3.gbr (link)
Figure: Common brushes path relation.

trunk/Identity/Themes/Motifs/THEMENAME/THEMEVERSION/Brushes
|-- 1.gbr (file) <-- ~/.gimp-2.2/brushes/centos-THEMENAME-THEMEVERSION.1.gbr (link)
|-- 2.gbr (file) <-- ~/.gimp-2.2/brushes/centos-THEMENAME-THEMEVERSION.2.gbr (link)
`-- 3.gbr (file) <-- ~/.gimp-2.2/brushes/centos-THEMENAME-THEMEVERSION.3.gbr (link)
Figure: Theme-specific brushes path relation.

Each brush produced with GIMP has a description field associated which is shown in the Brushes panel of GIMP.  This description is set when the brush is created as .xcf file and can be updated when it is exported either to .gbr or .gih format. It wouldn't be too useful to have two or more brushes using the same description. So, in order to have unique descriptions in brushes it is required to provide them that way. In that sake, we use the same name schema used to name brush files as description but without including the file extension.  This way, if we have the centos-flame-3.gbr brush, its description would be centos-flame-3.

Usage
-----

How to use brushes is up to your creativeness. You can use brushes as you consider them more appropriate for your graphical compositions. However, adding and removing them from the repository is something we need to standardize. It would be terribly sad being using one brush and suddenly find out that it no longer exists, the next time you update your working copy.

Common brushes
--------------

Common brushes exist to organize brushes that can be used anywhere inside the repository. Inside the repository, common brushes under trunk/Identity/Brushes are mainly used to hold brand information related to The CentOS Project (e.g., symbols, logos, trademarks, etc.).

Common brushes are always made available under ~/.gimp-2.2/brushes directory after preparing the repository (see Directories trunk Scripts Functions Prepare).

Theme-specific brushes
----------------------

Theme-specific brushes exist to organize brushes that can be used inside specific artistic motifs only. Inside the repository, theme-specific brushes are stored in a directory named Brushes which is stored in the first directory level under the artistic motif directory structure. Each artistic motif inside the repository has the Brushes directory and uses it to store brushes that can be considered auxiliars to that artistic motif construction.

Theme-specific brushes aren't made available under ~/.gimp-2.2/brushes directory after preparing the repository. In order to make theme-specific brushes available under ~/.gimp-2.2./brushes it is required to activate/deactivate them using the brush functionality of centos-art.sh script ().

See also
--------

  * Brushes (file:///usr/share/gimp/2.0/help/en/gimp-concepts-brushes.html) (from GIMP's manual)