Relevant to Blender v2.31
#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 separate 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 tool tip.
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 tool tips 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 receive 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 entries 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 anti aliasing.
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 separation between textures and materials. In Blender textures are objects that return certain values, signal generators 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 Material Buttons make these buttons redundant, and the interface becomes needlessly complex.