Hacking:Source Tree

From GIMP Developer Wiki
Jump to: navigation, search

This page describes how the GIMP source is organized - it will describe what's inside each directory of GIMP, and should help you navigate your way through the source.

Contents

The app directory

The app directory contains the source code of GIMP itself, without any external tools or plugins. The only exception for that is the testing framework of GIMP which is also included here.

app/actions

The files inside this folder include mapping of functions from GIMP's core to visible parts in the user interface.

app/base

This files inside this folder include basic commands to preform on the image - such as Curves, Colorize. It also includes the source for pixel data structures including the PixelRegion and the tiles. Also some utility functions (for example getting the number of processors in a system) and some other algorithms (like SIOX).

app/composite

This folder includes source which is architecture specific, to do the calculations of the paint modes in an optimized-way (by making sure that only things that need to be done will be done).

app/config

This folder includes the files responsible for saving and loading the configurations of GIMP from the rc files.

app/core

This folder is truly the guts of GIMP. It contains most of the objects that GIMP deals with - guides, brushes, drawables, images,... If you want to do something to the way objects in GIMP behave or if you want to implement a new type of objects (for example, angular guides, vector layers, ...) this is the first place you'd want to look at. Note that almost every change in this directory requires changes in other places - for example, if I want to implement a new type of layers (let's say vector layers) then you would also need to update the layers tree widget (and not to mention many other things). "Massive" hacks that are not just for implementing one tool or another, but to change/add new objects to GIMP will start here, and will affect many other parts of GIMP so be prepared for lots of work when changing things in here.

app/dialogs

The code of all GIMP's dialogs, is inside this directory. Any dialog including simple ones (like renaming a layer) and the most complex ones (Like the preferences dialog) can be found in this directory.

Dialogs should not be confused with dockable areas:

  • Dialogs are things which open in response to a specific action. These are not dockable, meaning that they will always be in a floating window of their own
  • Dockables (or Docks in short) are parts of the user interface which can be open all of the time and don't have to be available only as a result of a specific action. Dockables can either "float around" like dialogs, or you can drag and drop them to other docks, in order to organize them together in a single window (You "dock" one dockable inside the other).

Examples:

  • Editing a layer's name is done inside a dialog since it's a response to a request to edit the name of a specific layer
  • The brushes dialog is a dockable since it makes sense to have it open all the time

The definition of what should be a dock and what should be a dialog is sometimes unclear. But by taking a brief look inside this directory, it's usually very easy to find from the file names if what you are looking for is a dialog or not.

The source of the GIMP docks can be found in #app/widgets

app/display

This directory contains the code of the image display. This includes the image projection (i.e. the process of combining the data from all the layers, channels, etc. to an image which can be displayed on screen), the and various functions to draw on the canvas itself (these functions are used to draw guides, grids, and the controls of some tools).

Note that although the functions for drawing on the canvas are all located here, the actual code who calls these functions (for example, the code of the rectangle tool which calls these function to draw lines on the canvas) is often located somewhere else

app/file

This folder contains the functions which call the appropriate file handlers when opening/saving different kinds of files. I.E. these folders don't contain nay code to handle any specific file type, but instead they contain the code to identify and call the appropriate file handler.

app/gegl

This folder contains code for interaction between GEGL and GIMP. This includes some of GIMP's operations that were ported to GEGL (such as colorize, brightness and contrast, curves) and other code to transfer data between GIMP and GEGL.

app/gui

This folder contains the code of the skeleton of GIMP's graphical user interface. I.E. it does not contain the code of specific dialogs or widgets - instead it contains base-classes for GIMP's windows and some more code to manage them. An example for a major work here was the implementation of single window mode in GIMP.

app/menus

This folder contains the code of some of the menus. Note that this is NOT where you'll find the menu path of different actions.

app/paint

This folder contains the source of GIMP's paint tools - which are define to be

  • Tools for painting - Paintbrush, Ink, Clone, ...
  • Transformation tools - Move, Rotate, Scale, ...
  • The Paths tool

These should be distinguished from the base tools - see #app/base

Note that the code in this directory only contains the algorithms of the tools. The code for interacting with the user interface is located inside #app/tools

app/paint-funcs

This folder contains various functions which are commonly used by the paint tools - Layer modes, Image Samplers and conversions between pixel modes (indexed, rgb, etc.)

app/pdb

This folder contains auto-generated (don't edit files in this folder!) code for exposing internal GIMP functions to the PDB. The code inside this directory is generated by the pdbgen tool which is located under #tools/pdbgen.

For more information about pdbgen, see Hacking:pdbgen.

app/tests

This folder includes many tests for GIMP, which are usually preformed before new releases to try and make sure that all the major features work correctly.

app/text

This folder contains the source of GIMP's text core. This includes the function to render text, and the structures for keeping it's properties.

app/tools

Here is the source code of the tools which are exposed to the user. The code here is mainly the code for the user interface, and not the actual algorithm which performs the tools operation. The actual source of the tools operation can usually be found in #app/paint and for some tools (such as the selection tools) in #app/core. Note that for some tools which are currently in a development phase (such as the text tool), some of the code may hide in different places (for example, some of the text tool's code is currently inside #app/widgets inside the code of the on-canvas text editor)

app/vectors

Here is the code for handling paths (vectors) inside GIMP.

app/widgets

Most of the custom user interface elements which are used by GIMP, are located inside this folder. This includes everything from simple color buttons to the custom view of the layer stacks.

As the name states, most of the things in this directory are widgets and not stand-alone dialogs! do not get confused with #app/dialogs

app/xcf

The cursors directory

This directory contains all the cursor images which GIMP uses. Directly under this directory, you can find all the bitmap images of the cursors.

cursors/xbm

This directory contains the images of the cursors, converted to XBM files - these are C header files which have the data of the cursors encoded in binary directly into them.

The data directory

This directory contains various data files which ship with GIMP - brushes, gradients, palettes, etc. Details of the subdirectories are omitted as these are obvious =)

The desktop directory

This folder contains various data files files which are required for installing GIMP. These are mainly GIMP's icon in different sizes, and some linux .desktop files (similar to shortcut files in windows).

The devel-docs directory

This folder contains documentation for developing GIMP. Most of it is autogenerated by a tool called gtk-doc, directly from comments in the source file.

Some interesting docs there are

  • Documentations of the native file formats GIMP uses for it's brushes, images, patterns, etc.
  • Notes for developers on the steps required to make a release
  • Schedules
  • GIMP's dependancies
  • more...

The docs folder

This folder includes documentation of GIMP's command line options (man pages), and some source files for creating different versions of Wilber (GIMP's mascot!)

The etc folder

This folder contains default rc files (configuration files), that should be installed with GIMP.

The libgimp* directories

These directories include functions and other stuff which GIMP exposes for usage by plugins and extensions. Some of the files inside these directories are auto-generated by the pdbgen tool (see #tools/pdbgen) and therefore should not be edited.

The menus folder

This folder includes XML files which specify the location to register many of GIMP's actions inside the menus.

This modules folder

This folder contains source code of modules for GIMP - such as special color pickers (CMYK and water paint) and some other modules. See Hacking::Modules for more info

The plug-ins directory

This folder includes the source off all of GIMP's plug-ins. Plug-ins which are big and/or require several files are usually located in their own subdirectory, while the smaller/simpler plugins are located under the plug-ins/common.

The po directories

The po, po-libgimp, po-plug-ins, po-python, po-script-fu, po-tags and po-tips directories, contain files for internationalization (i18n) of GIMP. Basically, these are text files with strings from GIMP's source, together with their translation to different languages. Please see i18n:How-to for more details on the files inside these directories.

The themes directory

This directory contains the GIMP's themes. The topic of GIMP themes can be found in Hacking:Themes

The tools directory

This directory contains miscellaneous tools which are used for developing GIMP. Currently, the only tool in that directory is the pdbgen tool.

tools/pdbgen

More on that the pdbgen tool can be found in Hacking:pdbgen.

Personal tools