Dev:Doc/Blender Source/Files Structure
Blender source code directories explained
This page lists the directories in Blender's code and their use.
Note: this documents paths can be validated against Blender's source using: Source Tree Validator.
Directory Layout
Support Files
| DIRECTORY / FILE | USE |
|---|---|
| /doc/ | Document generation (doxygen and sphinx), licenses, man page and file format info. Note that documentation may be comments in the code, or on our developer wiki. So this isn't the best place to look for introductory materials. |
| /release/ | Contains data-files included with Blender releases, such as icons, fonts and platform specific files.
This also includes all Python scripts: add-ons, user-interface layout, utility modules. Even though in a sense this _is_ source-code, its simply copied into a directory for releases. |
| /release/bin/ | Contains the ".blender" folder, with fonts and such files. These are copied in place the installation dir. |
| /release/darwin | Files for macOS installation. |
| /release/datafiles | Fonts, icons, mat-cap images and other files included in Blender builds. |
| /release/freedesktop | Desktop and icon files for Linux/X11 desktop. |
| /release/scripts | Python scripts that will be placed in Blender's installation directories |
| /release/text | Readme and license files and text included with Blender installations. |
| /release/windows | Files for MS-Windows installation. |
| /tests/ | Files for testing. |
| /tests/gtests/ | C & C++ tests using the gtest framework.
See: Blender's gtest docs. |
| /tests/python/ | Various tests for Blender's Python API, as well as other tests written in Python.
See: Blender's gtest docs. |
| /source/tools/ | Tools and utilities to assist with development (not required for building). |
Build System
| DIRECTORY / FILE | USE |
|---|---|
| /build_files/ | Files needed when building the source |
| /build_files/cmake/ | CMake build-system modules. |
| /build_files/build_environment/ | Scripts for setting up a build environment (currently only used for Linux). |
| /build_files/buildbot/ | Configuration for automated builds.
Used for automated builds on builder.blender.org See: home page. |
| /build_files/utils/ | Utility scripts to help with releases & building. |
| /build_files/package_spec/ | Specifications for Blender packages (currently supporting various popular Linux package formats).
Note: these aren't currently used for official releases which use a portable archive, building package files can be useful still. |
| /CMakeLists.txt | CMake build-system file.
See: home page. |
| /GNUmakefile | Make-file convenience wrapper for the CMake build-system, to quickly setup CMake builds without manual (configure, build, install) steps.
Used on Linux/BSD/MacOS X. |
| /make.bat | Batch-file convenience wrapper for the CMake build-system, to quickly setup CMake builds without manual (configure, build, install) steps.
Used on MS-Windows. |
Application Code (source/)
| DIRECTORY / FILE | USE |
|---|---|
| /source/ | Main source code directory for code maintained by Blender developers. |
| /source/blender/ | Source code directory for Blender's application code. |
| /source/blender/avi/ | AVI loading and writing code (Only supporting primitive AVI raw, AVI jpeg and windows codec, not ffmpeg) |
| /source/blender/blenfont/ | Blender's internal font system |
| /source/blender/blenkernel/ | Kernel functions (data structure manipulation, allocation, free. No tools or UI stuff, very low level); kernel functions are shared with the blenderplayer, for loading data |
| /source/blender/blenlib/ | Internal misc libraries: math functions, lists, random, noise, memory pools, file operations (platform agnostic) |
| /source/blender/blenloader/ | Blend file loading and writing as well as in memory undo file system |
| /source/blender/blentranslation/ | Internal support for non-English translations (uses gettext).
Used by the user interface for displaying text labels and tool-tips. |
| /source/blender/bmesh/ | Mesh editing API, with support for n-gons and comprehensive editing operations.
Used in Edit Mode and by modifiers that perform advanced editing operations (such as bevel). See: BMesh design docs. |
| /source/blender/collada/ | Collada interface between blender and the external collada library |
| /source/blender/compositor/ | TODO. |
| /source/blender/datatoc/ | Utility to convert data files (images, fonts & shaders) into C source code files containing that data.
Used by the build system to convert data into symbols that can be compiled into the executable. |
| /source/blender/depsgraph/ | TODO. |
| /source/blender/editors/ | Graphical editor code, tools, UI ... (most of the interesting code is in there) |
| /source/blender/editors/animation/ | TODO. |
| /source/blender/editors/armature/ | TODO. |
| /source/blender/editors/curve/ | TODO. |
| /source/blender/editors/datafiles/ | TODO. |
| /source/blender/editors/gpencil/ | TODO. |
| /source/blender/editors/include/ | TODO. |
| /source/blender/editors/interface/ | Widget drawing, widget handling, widget layout generation, 2D editor scrolling, interface operators, icon API, theme management. |
| /source/blender/editors/io/ | TODO. |
| /source/blender/editors/mask/ | TODO. |
| /source/blender/editors/mesh/ | TODO. |
| /source/blender/editors/metaball/ | TODO. |
| /source/blender/editors/object/ | TODO. |
| /source/blender/editors/physics/ | TODO. |
| /source/blender/editors/render/ | TODO. |
| /source/blender/editors/screen/ | TODO. |
| /source/blender/editors/sculpt_paint/ | TODO. |
| /source/blender/editors/sound/ | TODO. |
| /source/blender/editors/space_action/ | TODO. |
| /source/blender/editors/space_api/ | TODO. |
| /source/blender/editors/space_buttons/ | TODO. |
| /source/blender/editors/space_clip/ | TODO. |
| /source/blender/editors/space_console/ | TODO. |
| /source/blender/editors/space_file/ | TODO. |
| /source/blender/editors/space_graph/ | TODO. |
| /source/blender/editors/space_image/ | TODO. |
| /source/blender/editors/space_info/ | TODO. |
| /source/blender/editors/space_logic/ | TODO. |
| /source/blender/editors/space_nla/ | TODO. |
| /source/blender/editors/space_node/ | TODO. |
| /source/blender/editors/space_outliner/ | TODO. |
| /source/blender/editors/space_script/ | TODO. |
| /source/blender/editors/space_sequencer/ | TODO. |
| /source/blender/editors/space_text/ | TODO. |
| /source/blender/editors/space_time/ | TODO. |
| /source/blender/editors/space_userpref/ | TODO. |
| /source/blender/editors/space_view3d/ | TODO. |
| /source/blender/editors/transform/ | TODO. |
| /source/blender/editors/util/ | TODO. |
| /source/blender/editors/uvedit/ | TODO. |
| /source/blender/freestyle/ | TODO. |
| /source/blender/gpu/ | GLSL shaders, buffers and other GPU related functions |
| /source/blender/ikplugin/ | IK plugin api (used to interface with itasc). Note that while this system supports multiple inverse-kinematics solvers there is no plug-in system exposed from a user perspective. |
| /source/blender/imbuf/ | Image buffer API and functions (loading, writing and manipulating different image formats); seq just has it's own buffer structure, but the loading is still done by imbuf; imbuf also has code for loading textures into openGL for display and all that |
| /source/blender/makesdna/ | DNA structures definition: All data structures that are saved into files are here |
| /source/blender/makesrna/ | RNA definitions and functions. Sits on top of DNA to provide a low level data access and definition API |
| /source/blender/modifiers/ | Mesh modifiers |
| /source/blender/nodes/ | Nodes code: CMP = composite, SHD: material, TEX: texture |
| /source/blender/physics/ | Solvers for hair and cloth physics simulation. |
| /source/blender/python/ | Python API, source files that embed the Python scripting language into Blender, as well as the API's Blender exposes which are written in C.
See: Python API Reference. |
| /source/blender/python/bmesh/ | The Python API for editing mesh data. |
| /source/blender/python/generic/ | The Python API generic functions (font, opengl, noise, ...) |
| /source/blender/python/intern/ | The primary parts of the API (bpy module, wraps Operators and RNA). |
| /source/blender/python/mathutils/ | The Python API 3D math module (access to Euler, Vector, Matrix, Quaternion, Color types). |
| /source/blender/quicktime/ | Quicktime integration code (MacOS X only). |
| /source/blender/render/ | The Blender Internal render engine.
Used by default for rendering and baking. |
| /source/blender/windowmanager/ | Blender's internal window manager, event system, operators, thread jobs, ... |
| /source/blenderplayer/ | Stubs for blenderplayer linking. bad level calls for functions the Game Engine needs for linking. |
| /source/creator/ | Contains the main(...) entry point function for the Blender executable. Handles initialization and command line argument parsing. |
| /source/gameengine/ | Blender's internal game engine sources |
Internal Library Code (intern/)
| DIRECTORY / FILE | USE |
|---|---|
| /intern/ | Abbreviation for internal. This directory contains source-code maintained by Blender developers but kept as isolated modules/libraries.
Some of these modules are C-API's to libraries written in C++, since much of Blender's core is written in C and can't call into C++ code directly. |
| /intern/atomic/ | Low level header to handle atomic operations.
See jemalloc's home page for the original source. |
| /intern/audaspace/ | An audio library which abstracts playback across different back ends, as well as handling 3D audio.
Used for audio playback in the sequencer, speaker objects and by the Game Engine. See: home page. |
| /intern/container/ | Template container library written in C++, defines a map and pointer hashing.
Used by the Game Engine. |
| /intern/curve_fit_nd/ | Library for calculating bezier (cubic) curve paths from input points.
Used for freehand curve drawing. See: home page |
| /intern/cycles/ | Cycles rendering engine. |
| /intern/dualcon/ | This library is used to re-create geometry.
Used by the remesh modifier. |
| /intern/elbeem/ | Fluid simulation library. |
| /intern/ffmpeg/ | Library used for video encoding and decoding.
Used for reading and writing many different video formats (movie clip editor, sequencer, render output... etc). |
| /intern/ghost/ | Stands for General Handy Operating System Toolkit.
This library abstracts platform specific operations. So we can avoid using OSX/Win32/X11 API calls in the rest of Blender's code. It handles window management actions, the OpenGL context and reading events from the mouse and keyboard, it also supports less common input devices such as a tablet or NDOF device. |
| /intern/glew-mx/ | An extension wrangler library for OpenGL, this is used to manage multiple glew implementations. |
| /intern/guardedalloc/ | This Blender primary memory allocator which is used in place of the system allocator. It has facilities for (optionally) guarding against common memory errors. Enabled when running with the --debug command-line argument.
Used throuought nearly all of Blender's own code. |
| /intern/iksolver/ | Inverse kinematics solver, to constraint a chain of bone to a target.
Used by the IK armature constraint. |
| /intern/itasc/ | A library used for the IK constraint solver iTaSC, an alternate solver useful for robotics.
Used by the IK plug-in system. |
| /intern/libmv/ | A motion tracking library.
Used for motion-tracking in the movie-clip editor. TODO maybe Sergey has better description? |
| /intern/locale/ | Wrapper for gettext translation library, not intended for standalone use.
Used by blentranslation. |
| /intern/memutil/ | Utility library with C++ memory management classes.
Generic cache-limiter and reference-counted implimentations and their C-API's. |
| /intern/mikktspace/ | Utility module for calculating tangents from mesh geometry (triangles and quads) and their UV coordinates.
Used by the DerivedMesh system and Blender Internal Render Engine. |
| /intern/moto/ | Linear algebra library.
See: home page. (though Blender's version is out-dated). Used by the Game Engine. |
| /intern/opencolorio/ | A C-API to the OpenColorIO Library (often abbreviated to OCIO).
Used by image loading and saving code to support color-management, as well as rendering. See home page. |
| /intern/opensubdiv/ | Subdivision surface library.
Used by Blender's subdivision surface modifier. See: home page. |
| /intern/rigidbody/ | A C-API to the Bullet physics library.
Used by the rigid-body physics system. |
| /intern/smoke/ | Smoke simulation library. |
| /intern/string/ | Defines the STR_String C++ class.
A utility class for basic string manipulation. Used by GHOST and the Game Engine. |
| /intern/utfconv/ | Utility functions for converting between unicode utf-8 and utf-16 (wchar_t).
Used for file operations on MS-Windows, which require utf-16. |
| /intern/eigen/ | Library written in C used to wrap the C++ Eigen3 library. |
| /intern/openvdb/ | Library used for efficiently store volumetric data.
Used for storing smoke simulation cache. |
External Library Code (extern/)
| DIRECTORY / FILE | USE |
|---|---|
| /extern/ | Abbreviation for external,
This directory contains source-code imported from other projects and not apart of Blender (strictly speaking). Each library is stand-alone and typically included because they aren't common system libraries we can rely on the system providing (such as libjpeg, zlib and libc). |
| /extern/binreloc/ | Utility to find the absolute path of the currently running executable on Linux.
Used for launching animation playback and some scripts which launch a Blender sub-process. See: archived home page. |
| /extern/bullet2/ | A real-time physics library.
Used for animating rigid-body physics and in the Game Engine. See: home page. |
| /extern/carve/ | A boolean 3D-geometry intersection library.
Used by the boolean modifier. See: home page. |
| /extern/ceres/ | Ceres Solver is a C++ library for modeling and solving large, complicated optimization problems.
Used for motion tracking. See: home page. |
| /extern/clew/ | An extension wrangler library for OpenCL, a library used for executing code both on the CPU and GPU with the ability to take advantage of many GPU cores. |
| /extern/cuew/ | CUDA Extension Wrangler.
See: home page. |
| /extern/Eigen3/ | A linear algebra header-only library to perform vector, matrix math operations and a sparse matrix solver.
Used by motion-tracking, ITASC IK solver and BLI math library. See: home page. |
| /extern/gflags/ | A C++ command line flag parsing library.
Not used directly, only included as a dependancy for glog. |
| /extern/glew/ | An extension wrangler library for OpenGL, used to optionally take advantage of newer API calles which may not be available on all systems.
Used by all areas of Blender that do OpenGL drawing. See: home page. |
| /extern/glew-es/ | An extension wrangler library for OpenGL-ES. A limited version of OpenGL, supported on mobile devices. Note that OpenGL-ES is currently not supported.
|
| /extern/glog/ | A C++ logging framework.
See: home page. |
| /extern/gtest/ | A C++ testing framework.
Used for testing C and C++ code in See: home page. |
| /extern/libopenjpeg/ | Support for the JPEG2000 image format.
Used by imbuf for loading Jpeg2000 images. |
| /extern/lzma/ | A compression library focusing on best compression at the expense of processing time.
Used for compressing physics cache. See: home page. |
| /extern/lzo/ | A compression library focusing on fast compression at the expense of final file-size.
Used for compressing physics cache. See: home page. |
| /extern/rangetree/ | Basic library for storing non-overlapping scalar ranges.
Used by dynamic-topology sculpting, to store unique ID's for undo data. See: home page. |
| /extern/recastnavigation/ | Calculate navigation path.
Used by the Game Engine. See: home page. |
| /extern/sdlew/ | An extension wrangler library for the SDL library.
Used for audio and joystick support in the Game Engine. See: home page. |
| /extern/wcwidth/ | Support for fixed width unicode characters, where some characters use multiple cells.
Used for the text editor and Python console. See: online source. |
| /extern/xdnd/ | Utility to support drag and drop on Unix/X11.
Used to support dropping files onto Blender's window. |
Glossary
Atomic
- Atomic operations refer to the assurance that multiple threads
- will never interfere with each other.
- eg: multiple threads incrementing a global counter.
- Without the guarantee of atomicity, the outcome may be undefined.
Bad Level Calls
- It's common practice to use a mix of low level API's and high level API's when developing a complex application.
- * Low level API's (to handle file io, compression, lists... and other primitive data structures).
- * High level API's (showing an error popup, drawing the splash screen, showing a file, sending an undo push).
- Typically high level API's will call lower level API's but not the other way round.
- Bad level calls break this convention, by calling high level API's from lower level ones.
- In some cases this is hard to avoid, for example it was necessary to have low level image loading code call into font reading and translations to be able to generate thumbnails for font files.
- Bad level calls can be avoided by allowing callback functions to be registered at run-time, or by defining a new higher level library that depends on multiple lower level ones.
- Both solutions are used already in Blender, however there are some isolated cases where bad-level-calls are accepted in the code.
Extension Wrangler
- Code to bind library calls to a library at load time.
GPU
- Graphics processing unit typically included on a systems graphics card.
IK
- Stands for Inverse Kinermatics.
- The process of solving a rigging constraint,
- where a chain of bones are deformed to reach a target.
NDOF
- Stands for N degrees of freedom.
- In Blender this term is associated with input devices
- also known as a 3D Mouse - input devices that give many degrees of freedom.
- More than a regular mouse or joystick.
