Blender 3D: Noob to Pro/Hacking Blender

Blender is an Open Source project. That doesn’t just mean you get to use it for free, you also get to see how it works, and you can even make your own changes and share them with others.

Blender is also a large software project (well over a million lines of code), with a great many active contributors over a lifespan of more than a decade, and it continues to be developed at a rapid rate. This can make things somewhat intimidating for less-experienced programmers.

This unit assumes you have some decent programming experience under your belt. Blender is mainly programmed in the C, C++ and Python programming languages. It can be built using either the CMake or SCons build systems.

Getting the Blender Source Code

The official Blender source is kept in Git repositories located at developer.blender.org. There are actually several separate repositories:

blender-main — the main part of the Blender source, excluding most Python addons.
blender-addons — the Python addons included in the standard Blender distribution.
blender-addons-contrib — additional useful Python addons.
blender-translations — localized language translations for text messages.
blender-tests — some interesting example .blend files used for testing and demonstrating Blender functionality.
blender-dev-tools — tools that are useful for performing maintenance tasks on the Blender source, but are not actually needed for building Blender.
blender-cloud — looks like a framework for offering a new cloud-based Blender service.

Layout of the Blender Source

Say you’ve checked out a copy of the main Blender source tree. The top level looks like this:

build_files/ — files used during the build process
CMakeLists.txt — top-level control file for CMake
COPYING — note about Blender licensing (GPLv2)
doc/ — documentation files, among them:
- doc/blender_file_format/ — the format of .blend files
- doc/build_systems/ — how to build Blender, and hack the build system
- doc/manpage/ — the man page
extern/ — non-Blender-specific libraries, primarily developed elsewhere, included in the source
GNUmakefile — simple build script for those who can’t be bothered to go through the CMake setup process
intern/ — libraries which are non-Blender-specific but primarily developed here, also glue code for interfacing to external libraries not included in the Blender source. Notable subdirectories:
- intern/bsp/ — Constructive Solid Geometry routines
- intern/cycles/ — the Cycles renderer
- intern/elbeem/ — the fluid simulator
- intern/ghost/ — Blender’s platform-independent GUI (including platform-dependent implementations). See intern/ghost/GHOST_ISystem.h for a more detailed description.
- intern/guardedalloc/ — thread-safe memory management with consistency checking
- intern/iksolver/ — the Inverse Kinematics library
- intern/smoke/ — the library for simulating smoke and flames
release/ — additional files to be included in the Blender distribution, including GUI icons and fonts
SConstruct — top-level control file for SCons
source/ — the main part of the Blender source, further divided (ignoring the CMakeLists.txt and SConscript files which you will find just about everywhere) into
- source/blender/ — the bulk of the source, of which some useful parts are
  - source/blender/blenlib/ — low-level stuff for file management, geometry algorithms, sorting and suchlike
  - source/blender/blenkernel/ — core Blender-specific code (no UI stuff)
  - source/blender/blenloader/ — code for reading and writing .blend files
- source/blenderplayer/ — some additional files for building the Blender Player executable
- source/creator/ — the Blender mainline
- source/gameengine/ — the Blender Game Engine
- source/icons/ — some files specific to the Windows build
- source/tests/ — some test scripts

Common Subdirectory Layout

Within many of the subdirectories in source/blender/ and intern/, you will see the following pattern:

A bunch of .h files in the directory, and
an intern subdirectory.

The .h files define the functionality exported to other modules, while the intern subdirectory contains the .c or .cpp files that actually implement the module. Sometimes the .h files are put into an extern subdirectory instead of the upper directory level.

(And yes, these meanings of intern and extern are not the same as the meanings of intern and extern at the top directory level.)

Blender’s “Genetic Code”: “DNA” and “RNA”

You will find references to “DNA” (or “SDNA”) and “RNA” throughout Blender’s source code. The analogy to the terms from genetics is weak at best, but what they refer to is:

“DNA” or “SDNA” (“structure” DNA?) is the system for mapping Blender’s in-memory data structures to the on-disk .blend file format. A .blend file is little more than a memory dump, which makes it quick to write. However, the file needs to be readable by Blender builds on machines with different endianness, 32 versus 64-bit pointers, etc, not to mention future versions with different capabilities. Thus, the saved .blend file includes a detailed description of the layout of all the data structures saved in the file, and this description is stored in the “DNA1” block at the end. This block is generated by the makesdna tool, which is built and run automatically as part of the overall build process, so its output can be included directly into the Blender executable. It parses all the .h files in the directory source/blender/makesdna/, so all data structures that could get saved into .blend files must be defined here, and they must be careful to use a limited subset of C that the parsing tool can handle.
“RNA” defines the Python interface to Blender’s internal data structures and routine calls.

Here is Ton “Mr Blender” Roosendaal explaining DNA and RNA.

Special Globals: “G” and “U”

There is a frequently-referenced global variable named “G”, of type struct Global, declared in source/blender/blenkernel/BKE_global.h. The variable is defined in source/blender/blenkernel/intern/blender.c. This same file also defines the global “U”, of type struct UserDef, declared in source/blender/makesdna/DNA_userdef_types.h.

Naming Conventions

Some (but not all) global symbols have prefixes on their names indicating (roughly) where they come from. Here is a partial list.

Prefix	Meaning	Where Found
AUD_	audaspace sound library	intern/audaspace/
BKE_	lowest-level (non-UI) Blender operations	source/blender/blenkernel/
BLF_	Font/text-handling	source/blender/blenfont/
BLI_	common library routines	source/blender/blenlib/
BLO_	loading/saving `.blend` files	source/blender/blenloader/
COM_	compositor	source/blender/compositor/
CTX_	handling of `bContext` objects	source/blender/blenkernel/BKE_context.h, source/blender/blenkernel/intern/context.c
DNA_	include files containing all type definitions that get saved into `.blend` files	source/blender/makesdna/
ED_	editor UI routines	source/blender/editors/
FRS_	Freestyle renderer	source/blender/freestyle/
GHOST_	platform-independent UI layer	intern/ghost/
IMB_	image-format handling	source/blender/imbuf/
MEM_	memory management	intern/memutil/
MOD_	modifiers	source/blender/modifiers/
NOD_	node editor	source/blender/nodes/
PIL_	platform-independent timing	source/blender/blenlib/PIL_time.h. PIL_time_utildefines.h
RE_	common renderer handling	source/blender/render/
RNA_	Python interface	source/blender/makesrna/
STR_	string routines	intern/string/
WM_	window management	source/blender/windowmanager/

User-Interface Implementation

The UI code is structured into several layers. This code also handles finding of user-preference files and shared application data. Starting from the lowest, the layers are:

intern/ghost/
source/blender/windowmanager/ (see source/blender/windowmanager/WM_types.h for an overview)
source/blender/editors/screen/
source/blender/editors/interface/