[Bf-blender-npr] Freestyle/Blender Basic Overview

Tamito KAJIYAMA rd6t-kjym at asahi-net.or.jp
Mon Jul 28 09:47:23 CEST 2014

Hi Margret,

Freestyle programming flows depend on what you want to achieve. Below I
will assume that you are interested in Freestyle line shaders in Python
and the underlying C++ component layer.

In Freestyle, line shading is done through a Python script called style
module. The Python Scripting mode of Freestyle allows you to specify a
set of style modules that actually perform one or more line shaders.
Freestyle comes with predefined style modules (e.g., in the
2.71/scripts/freestyle/styles/ directory). Testing an existing style
module will be the first step to get started.

Take a close look at existing style modules, and you will notice that
they consists of operator calls (e.g., Operators.select() and so on).
Operators are used in various combination of style module constructs.
There are four classes of style module constructs: chaining iterators,
functions, predicates, and stroke shaders. They are either predefined as
part of the Freestyle Python API, or user-defined. Implementing a new
style module construct (say, a new stroke shader of your own) will be
the next step to get familiar with Freestyle programming.

The Freestyle Python API is a thin wrapper of the underlying API
implementation in C++. There is almost a one-to-one relationship between
individual Python style module constructs and C++ counterparts. A
specific mechanism for inter-language method calls (from Python to C++,
and vice versa) called "directors" is used in-between the Python and C++
layers. Some code reading will be necessary to understand what is going
on there.

Style module constructs can be defined either purely in Python, or by
implementing them in C++ first and wrapping them in Python. The
source/blender/freestyle/intern/python/ directory of the source tree
stores the Python wrappers of the C++ API implementation. Existing pairs
of Python and C++ style module constructs will serve as examples for
Freestyle C++ programming.

It is noted that the Parameter Editor mode (i.e., the Freestyle GUI) is
implemented as a big, monolithic style module. Extending it requires the
same knowledge on style module writing in general.

If you want to introduce new parameters that show up in the UI and will
be saved into .blend files, then you need to study how to add new UI
controls and how to store the parameters into files. Simple UI
components (such as toggle buttons and drop-down menus) can be defined
in Python (see release/scripts/startup/bl_ui/), while advanced UI
controls (e.g., a custom version of UIList) may require C programming
(see source/blender/editors/space_buttons/). Parameters are defined in
the Blender DNA subsystem and described by the Blender RNA subsystem
(see source/blender/makesrna/). Once the parameters are annotated with
RNA, then showing the UI widgets for manipulating the parameters is a
matter of adding a few lines of code in Python. Addition of structured
parameters may require updates of the .blend file loader and writer (see

Here are some links to useful information:

Freestyle section of Blender 2.67 release notes

Freestyle Python API reference

Example of code updates for adding a new modifier

Overview of Freestyle source files


KAJIYAMA, Tamito <rd6t-kjym at asahi-net.or.jp>

On 28/07/2014 02:51, Margret Storm wrote:
> (My first time responding to any kind of official mailing list, forgive
> me in advance for any violations of protocol/basic manners)
> Hey, I'm learning C++ with the intention of getting under the hood with
> Freestyle (mainly, I'd like to change how many arguments the shaders can
> take, for more interactivity with Python add-ons), but it's kind of hard
> to know where to start!! The old Freestyle blog has documentation on
> what does what in what order, but I can't be sure what's current and
> what isn't . . .
> Is there, or could someone make, a basic overview of how the programming
> flow in Blender/Freestyle especially works?

More information about the Bf-blender-npr mailing list