Developer Documentation
LOAD 1.64 Plugin Collection
|
Welcome to the Developers Reference Information, here you will find
documentation on all aspects of developing programs that work alongside
or interact with Blender.
Blender supports a number of types of plugins to allow additional
control over rendering. Currently these are Texture plugins, which
can extend the current texture editor to provide control over intensity, color, and
bump-mapping, and Sequence plugins, which can provide post-processing and
transition facilities in the sequence editor.
- Installation
All the files necessary to develop plugins are found in each release
of Blender available on www.blender.nl/download/.
- bmake
bmake is a simple utility (shell script) to aid in the compilation
and development of plugins, and can be found in the plugins/ sub-directory
of the Blender installation directory. It is invoked by
bmake <plugin_name.c>
and will attempt to link the proper libraries and compile the specified
C file properly for your system.
- The Plugin System
Plugins are supported (loaded/called) in Blender using the
dlopen() family of calls. For those unfamiliar
with the dlopen system it allows a program (Blender) to use
a compiled object as if it were part of the program itself, similar
to dynamically linked libraries, except the objects to load are
determined at runtime.
The advantage of using the dlopen system for plugins is that
it is very fast to access a function, and there is no overhead
in interfacing to the plugin, which is critical when (in the
case of texture plugins) the plugin can be called several million
times in a single render.
The disadvantgae of the system is that the plugin code works
just like it is part of Blender itself, if the plugin crashes,
Blender crashes.
-
Provided functionality
The include files found in the plugin/include/ subdirectory
of the Blender installation document the Blender functionality
provided to the plugins. This includes the Imbuf library
functions for loading and working with images and image buffers,
and noise and turbulence functions for consistent texturing.
You might find it usefull to look over the
plugin.h or
an example plugin
while reading.
- The C File
- #include <plugin.h>
Every Blender plugin should include this header
file, which contains all of the structures and
defines needed to properly work with Blender.
- char name[]="Tiles";
A character string containing the plugin name,
this value will be displayed for the texture's title
in the Texture Buttons window.
- #define NR_TYPES 2
char stnames[NR_TYPES][16]= {"Square", "Deformed"};
Plugins are allowed to have seperate subtypes for
minor variations on algorithms - for example the
default clouds texture in Blender has the "Default"
and "Color" subtypes.
NR_STYPES should be defined to the number of
subtypes required by your plugin, and a name
for each subtype should be given. Every plugin
should have at least 1 subtype and a subtype name.
- VarStruct varstr[]= {...};
The varstr contains all of the information
Blender needs to display buttons for a plugin.
Buttons for plugins can be numerical for
input data, or text for comments and other
information. Plugins are limited to a maximum
of 32 variables.
Each VarStruct entry consists of a type, name,
range information, and a tooltip.
The type defines the data type for each button
entry, and the way to display the button. For number buttons
this value should be a combination (ORed) of INT
or FLO for the number format, and NUM, NUMSLI, or
TOG, for the button type. Text buttons should have
a type of LABEL.
The name is what will be displayed on (or beside)
the button. This is limited to 15 characters.
The range information consists of three floats
that define the default, minimum, and maximum values
for the button. For TOG buttons the minimum is
set in the pressed state, and the maximum is set
in the depressed state.
The tip is a string that will be displayed when
the mouse is over this button (if the user has tooltips
on). This has a limit of 80 characters, and should be
set to the NULL string ("") if unused.
- typedef struct Cast {...};
The cast structure is used in calling the
doit function, and serves as a way to simply
access each plugin's data values.
The cast should contain, in order, an integer
or float for every button defined in the varstr,
including text buttons. Typically these should
have the same name as the button for simple
reference.
- float result[8];
The result array is used to pass information
to and recieve information from the plugin.
The result values are mapped as follows:
| Result Index | Significance | Range |
| result[0] | Intensity value | 0.0 to 1.0 |
| result[1] | Red color value | 0.0 to 1.0 |
| result[2] | Green color value | 0.0 to 1.0 |
| result[3] | Blue color value | 0.0 to 1.0 |
| result[4] | Alpha color value | 0.0 to 1.0 |
| result[5] | X normal displacement value | -1.0 to 1.0 |
| result[6] | Y normal displacement value | -1.0 to 1.0 |
| result[7] | Z normal displacement value | -1.0 to 1.0 |
The plugin should always return an intensity value.
Returning RGB or a normal are optional, and should be indicated by the doit()
return flag
"1" (RGB) or "2" (Normal).
Before the plugin is called, Blender includes the current rendering-normal
in result[5], result[6] and result[7].
- float cfra
The cfra value is set by Blender to the current
from before every render pass. This value is
an the frame number +/- .5 depending on the field
settings.
- plugin_tex_doit prototype
The plugin_tex_doit function should be prototyped
for use by the getinfo function. You do not need
to change this line.
- plugin_tex_getversion
This function must be in each plugin for it
to be loaded correctly. You should not change
this function.
- plugin_but_changed
This function is used to pass information
about what buttons the user changes in
the interface. Most plugins should not need
to use this function, only when the interface
allows the user to alter some variable
that forces the plugin to do recalculation
(a random hash table for example).
- plugin_init
If needed plugins may use this function
to initialize internal data. NOTE: This init
function can be called multiple times if the same
plugin texture is copied. Do not init global data
specific to a single instance of a plugin in this
function.
- plugin_getinfo
This function is used to communicate information to
Blender. You should never need to change it.
- plugin_tex_doit
The doit function is responsible for returning
information about the requested pixel to
Blender.
The Arguments
- int stype
This is the number of the selected subtype,
see the NR_TYPES and char stypes
entires above.
- Cast *cast
The Cast structure which contains the plugin
data, see the Cast entry above.
- float *texvec
This is a pointer to 3 floats, which are the
texture coordinates for which a texture value
is to be returned.
- float *dxt
float *dyt
If these pointers are non-NULL they point to
two vectors (two arrays of three floats) that
define the size of the requested texture
value in pixel space. They are only non-NULL
when OSA is on, and are used to calculate
proper antialiasing.
The doit function should fill in the result array
and return 0,1,2, or 3, depending on what values have
been filled in. The doit function should always
fill in an intensity value. If the function fills in
a color value it should return 1, if it fills in a
normal value it should return 2, if it fills in
everything it should return 3.
- Texture/Material Interaction
Blender is somewhat different from most 3D packages
in the logical seperation between textures and materials.
In Blender textures are objects that return certain
values, signal generaters in fact. Materials control the
mapping of textures onto objects, what is affected,
how much, in what way, etc.
Properly designed plugins should only include
variables to affect the signal returned not the
mapping of it. Buttons to control scale, range,
axis, etc. are best only included when they make
the texture easier to use (in the case of the size
button in the Tiles plugin)
or they speed up the calculation (the Intensity/Color/Bump subtypes in
the Clouds2 plugin).
Otherwise the MaterialButtons make these buttons redundant,
and the interface becomes needlessly complex.
You might find it usefull to look over the
plugin.h or
an example plugin
while reading.
- The C File
- #include <plugin.h>
Every Blender plugin should include this header
file, which contains all of the structures and
defines needed to properly work with Blender.
- char name[]="Blur";
A character string containing the plugin name,
this value will be displayed for the texture's title
in the Texture Buttons window.
- VarStruct varstr[]= {...};
The varstr contains all of the information
Blender needs to display buttons for a plugin.
Buttons for plugins can be numerical for
input data, or text for comments and other
information. Plugins are limited to a maximum
of 32 variables.
Each VarStruct entry consists of a type, name,
range information, and a tooltip.
The type defines the data type for each button
entry, and the way to display the button. For number buttons
this value should be a combination (ORed) of INT
or FLO for the number format, and NUM, NUMSLI, or
TOG, for the button type. Text buttons should have
a type of LABEL.
The name is what will be displayed on (or beside)
the button. This is limited to 15 characters.
The range information consists of three floats
that define the default, minimum, and maximum values
for the button. For TOG buttons the minimum is
set in the pressed state, and the maximum is set
in the depressed state.
The tip is a string that will be displayed when
the mouse is over this button (if the user has tooltips
on). This has a limit of 80 characters, and should be
set to the NULL string ("") if unused.
- typedef struct Cast {...};
The cast structure is used in calling the
doit function, and serves as a way to simply
access each plugin's data values.
The cast should contain, in order, an integer
or float for every button defined in the varstr,
including text buttons. Typically these should
have the same name as the button for simple
reference.
- float cfra
The cfra value is set by Blender to the current
from before every render pass. This value is
an the frame number +/- .5 depending on the field
settings.
- plugin_seq_doit prototype
The plugin_seq_doit function should be prototyped
for use by the getinfo function. You do not need
to change this line.
- plugin_seq_getversion
This function must be in each plugin for it
to be loaded correctly. You should not change
this function.
- plugin_but_changed
This function is used to pass information
about what buttons the user changes in
the interface. Most plugins should not need
to use this function, only when the interface
allows the user to alter some variable
that forces the plugin to do recalculation
(a random hash table for example).
- plugin_init
If needed plugins may use this function
to initialize internal data. NOTE: This init
function can be called multiple times if the same
plugin texture is copied. Do not init global data
specific to a single instance of a plugin in this
function.
- plugin_getinfo
This function is used to communicate information to
Blender. You should never need to change it.
- plugin_seq_doit
The sequence doit function is responisble for
applying the plugin's effect and copying the
final data into the out buffer.
The Arguments
- Cast *cast
The Cast structure which contains the plugin
data, see the Cast entry above.
- float facf0
The value of the plugin's IPO curve for
the first field offset. If the user hasn't
made an IPO curve this ranges between 0 and
1 for the duration of the plugin.
- float facf1
The value of the plugin's IPO curve for
the second field offset. If the user hasn't
made an IPO curve this ranges between 0 and
1 for the duration of the plugin.
- int x
int y
The width and height of the image buffers,
respecively.
- Imbuf *ibuf1
A pointer to the first image buffer the
plugin is linked to. This will always be
a valid image buffer.
- Imbuf *ibuf2
A pointer to the second image buffer the
plugin is linked to. Plugins using this
buffer should check for a NULL buffer,
as the user may not have attached the
plugin to two buffers.
- Imbuf *out
The image buffer for the plugin's output.
- Imbuf *use
A pointer to the third image buffer the
plugin is linked to. Plugins using this
buffer should check for a NULL buffer,
as the user may not have attached the
plugin to three buffers.
- ImBuf image structure
The ImBuf structure always contains 32 bits ABGR pixel data.
ImBuf structs are always equal in size, indicated by the passed x and y value.
- User Interaction
There is no way for Blender to know how
many inputs a plugin expects, so it is
possible for a user to attach only one input
to a plugin that expects two. For this
reason it is important to always check the buffers
your plugin uses to make sure they are
all valid. Sequence
plugins should also include a text label
describing the number of inputs required
in the buttons interface.
|
