with scene audio recursion in mattieu's gooseberry edit in sequencer.
Will probably cause something else to explode but let's just guard
against this in the audio lib for now.
The issue was caused by memory optimization marking particle system to recalc,
and because of the way how particle flags works it was possible that it'll
cause particle's re-distribution. Now this memory optimization will act the
same as loading the file.
Would need to review if this fix is to go to master/cycles_memory branches
but for now it'll be cool to figure out what to do with the farm.
Now file open operator also sets a temporary flag for collapse. This
allows the user to configure the option to always collapse files and the
editor will remember the setting and not reset it back after finishing a
collapsed file open.
This way we store quite reasonable amount of memory (density is stored as RGBA
textures, which ends up in gigabytes of RAM for hires smoke sims).
It's not really pretty implementation and we'll really need to support textures
with 1 and 3 channels instead of doing such packing, but we need to be able to
render some files here.
This happens if all object's smokes are backed to files and rendering is either
happening from command line of with locked interface.
The idea behind this change is to make as much memory available for path tracing
as possible, so after heavy swapping during synchronization period there's loads
of free memory to put important data back to RAM.
Notes:
* This is own coocking, since it seems hard to find papers on simplifying already existing bezier curves,
and we do not really need the 'generic' least-square fitting of bezier in a set of points, here.
* It takes advantage of specificities of FCurves (e.g. only difference that matters here is Y value at same X frame,
no vertical overlapping, etc.).
* It gives reasonably good results, but could most likely be enhanced quite a bit still.
* Only 'hooked' to bake action operator right now (needs more work to add it to graph editor too).
* Ultimately should probably be redone in C. Would keep it in Python until we have a real good
cleanup behavior though, much easier to experiment in later language.
Very dirty feature that will have to be reimplemented when the new asset engine makes it into blender.
This commit tweaks the filebrowser to detect sequences of images that form parts of a movie. The
files need to be in the format <number>filelame.ext or <number>.filename.ext
There is a new option next to hidden file option that makes it so this collapsing takes place.
When collapsing is on, any movie files that have the same filename will be collapsed to the first
detected file in the sequence. Selecting that file will select all files in the sequence.
There is a shortcut in the sequence editor in the Add menu, "Image Sequence" that enables collapsing
by default. Unfortunately, selecting multiple movies will not add multiple sequences to the sequencer,
at least for now, but it should make it quite easier for people to quickly select the whole range of
images for a movie. Importing the image sequence into the sequencer will use placeholders, so any missing images
will display as black.
Using ints and floats would require prefixing the Alembic metadata
keys, which becomes messy and ambiguous. Encoding other data types as
strings can be done on the python side as well.
properties.
This is necessary to distinguish e.g. vector semantics (linear vs. slerp
interpolation for positional/normal vectors). It would be simpler to
do this based purely on types, but the typing of common Alembic
properties is not sufficiently unique. Semantics arguments are enum
values, that can be omitted if the default interpolation should be used.
This features is needed for motion blur. All properties with position
semantics (transform matrices, mesh and curve vertex locations, etc.)
need to be interpolated for fractions of full frames, in order to
reproduce the motion and deformation correctly.
Alternatively we could store subframe time sampling for this subset of
properties. However, this would increase the amount of data stored,
and it might actually show artifacts from subframe interpolation in
Blender which is not visible to animators otherwise and should be
ignored.
archives, instead of Blender frame values.
This is easier to use for interpolation, the frame value is really only
required externally, before and after reading a sample.
This requires some modifications to the existing preset python class.
Serializing curve mappings can not be done with a simple property
assignment.
Also the fact that operator confirm popups drop all layout context
pointers means that we have to store the modifier name in the operator
in order to apply the preset to the correct modifier.
* Add space key to easily start-stop the player.
* Keep old behaviour of stopping when scrubbing.
* Sound scrubbing can be heard now even when scrubbing after pausing.
The previous way of selecting preview ("realtime") and render settings
on the cache library level was complicated and confusing. Now there are
just 2 buttons for baking either the preview or render level.
Technically the cache still works the same way, so a 3rd button could be
added for baking both passes into the same cache, should the need arise.
The preview cache now also uses the preview frame range, which should
help in quick testing of hair simulation settings. Render always uses
the scene frame range, like render buttons do.
For display in the viewport and rendering the cache will now use
whatever data is available in the archive. If the cache contains only
render data, the viewport will also draw full render data. Vice versa,
if the cache contains only preview data, this will also be used for
rendering.
Hair toggles for children and motion now are only used for the viewport
display. This simplifies the settings a lot and removes one potential
button to be overlooked.
cutting.
When using a dupli object from the same group as a target it is
sufficient to calculate the relative transform in the shared duplicator
local space. When using an external object though we have to transform
into world space first.
for child hairs.
The algorithm works by finding the first intersection of each child
hair with the target mesh. The child hairs have to be deformed with
their parents first (this usually happens *after* modifiers).
Support speed of sound based on how fps is different from the movie fps.
For high fps the picture thread can lag behind the sound still, need
some way to framedrop.
Basically it's a clean tool, but also removes a channel if the only
remaining keyframe has the default value only and is not used by
drivers or generative modifiers.
It's supposed to help with performance of the heavy scenes in
gooseberry.
Field test in gooseberry for now, masterification later.
Strand shapekeys will be interpreted as delta keys without a basis,
since the basis would be animated and therefore useless for static keys.
To avoid complexity in the already overburdened shapekey functions and
to skip old legacy code, the strands shapekeys now have their own
functions.
of an animated base.
This is necessary for strand shape keys. The basis of the data comes
from the cached animation or simulation results, i.e. we can't use the
fixed basis key or the result would always become static.
motion state.
This means shape keys work on the goal positions for hair as well as
the simulation results (hair motion).
If the simulation is created before shape keys are applied, the
resulting sim will be mixed with the shape keys, becoming more rigid
with increased shape weights.
OTOH the shape keys can also be applied to the animation result, before
doing hair simulation. In that case the shape will only affect the goal
positions and the bending shape of the hair, but the hair is otherwise
free to move.
gooseberry and alembic branches.
The shapekey code has been modified in both branches, adding particle
shapekeys in gooseberry and cache library shapekeys in alembic. The
two approaches are slightly different, but based on the same idea of
extending the 'from' owner info in Key, so that keys can be used without
a 'from' ID and/or with an index for identification.
This patch unifies the approach in both branches to make it slightly
less messy and avoid merge conflicts.
The shapekey code has been modified in both branches, adding particle
shapekeys in gooseberry and cache library shapekeys in alembic. The
two approaches are slightly different, but based on the same idea of
extending the 'from' owner info in Key, so that keys can be used without
a 'from' ID and/or with an index for identification.
for slices.
Also the time sampling for slice output properties must be passed down
from the output archive, since the input properties use the original
start frame and cycle times.
than relying on values from Scene.
This gives more flexibility when creating archives. A default variant
for opening archives using the scene settings is still available.
range to a new archive.
This feature is useful when cache size becomes to big and unwieldy.
For sending shots to a render farm a large cache can now be split into
smaller parts, which are spliced off and can be sent individually.
Still lots of corner cases to check:
* sound FPS not changing with speed settings of player
* picture and video still not 100% in synch
* Haven't checked what happens when audio is finished.
Some changes were made to make things nicer:
* Scrub now initiates on mouse click instead of mouse motion, makes
things more predictable.
* When scrubbing a movie with sound, don't pause playing after
scrubbing.
team.
There are 3 options here:
1) Keep range (previous behaviour)
2) Seconds - allows a specified offset in seconds around current frame
3) keyframes - zoom to include a number of keyframes around the cursor
Options 2 and 3 have their own properties to tweak the behaviour and all
options can be found in User Preferences->Interface under the 2D
viewports section.
Number 3 will probably need some refinement so commiting here for the
hwoozeberry team to test first.
This reverts commit 1b32ac9779.
The goal spring is not working as intended, but is better than having
no bending force at the roots at all. Needs a better solution (virtual
root vertex).
There are larger bugs still roaming free which need to be solved first.
Goal springs also are inherently unstable because the solver can not
properly estimate their Jacobian.
caches.
The 'find' function was returning a bool value, but this does not
guarantee non-null pointers. Removed the return value to avoid
confusion, now callers should simply check the returned pointers.
The filter group was used by omitting any object instances that were
not in the group. This reduces the cache size, but it also entirely
skips objects.
Now the filter group only prevents writing of the actual object data,
but still allows storing dupli instances and dummy entries in the cache.
Any objects from cached dupli lists that don't have cached data (mesh or
strands) will now use the original object data instead.
The cache bake operator would always create a job in the window manager.
However, when running in background mode via a script, the operator can
not be modal and the script would return right after starting the job.
Then Blender is stopped and the baking job with it.
To prevent this the operator now only runs in a job when executed from
the invoke function (or when 'use_job' is set explicitly).
shape.
Shape keys distinguish between the base shape (shape without any keys)
and the individual reference shapes for each shape key (which define
the delta offsets). For strand shapes, which have to work on top of
animation, the base shape must be the original cache result rather than
a static shape, but the delta for each keyblock is still calculated
wrt. an explicit shape.
group objects when editing shape keys.
The edit data (including CD_SHAPEKEY layers) is in the active object's
space, i.e. the duplicator. The original data however is cached strands
data, which is in the dupli object's space. All geometry data needs to
be transformed properly when entering/exiting edit mode.
This already exists for goal springs. Bending stiffness, however, is
preferable to global goal springs for physical realism. Controlling
stiffness in this way allows using bending forces to also simulate
unconventional hair, such as clumpy strands that are thicker and stiffer
at the base.
Note that hair interaction can also be simulated with this tool in some
way, although eventually better methods may be needed for such effects.
solver.
This happens when using goal springs, which are now defined as linear
springs between actual vertices and virtual goal vertices. The Jacobian
was not accounting for the possibility of zero rest length.
Both the gooseberry and alembic branches contain extensions of the Key
DNA structure, in order to make it work for particles and caches
respectively. This was giving badly resolved conflicts on merge.
function.
This is a feature for display in the viewport and rendering, which has
nothing to do with the core cache reading functionality. In the general
case you'd want the child data to remain unmodified.
Getting a consistent look here is difficult since editors apply their
own scaling. ideally, here we would have a consistent look with constant
font size but this is still to be realized in master and needs some
extra thought.
The parent matrix is used for single-parent children ('simple'), in
which case the pa->num_dmcache has to be used to get the correct
position on subdivided meshes.
This data is not strictly necessary for the strands drawing or rendering
or even hair simulation, because the hair root offset and rotation is
already cached explicitly. However, the strand edit mode needs this
information to correctly apply length constraints.
Strands require a valid DerivedMesh for calculating their root matrix
and surface mapping. The scheduler tasks were created such that strands
would be calculated while the DM task was not finished yet, leading to
missing DM data.
object.
The strand edit mode uses the local space of the active object, which
is the duplicator (and dupli cache owner). The strands data is in local
space of the original particle system object however, so have to
convert. This is a very hackish solution, using the first instance of
the strands data, which only works for single instance data.
Currently strand edit mode tool use the object data 'x mirror' flag.
This flag is only available on mesh objects, but the strand editing
can be used for dupli override caches etc. as well. Eventually strand
editing should get it's own independent flag to avoid this problem.
separate file.
This may seem a bit like overkill, but it helps ensure that no particle
depedencies messes up the strand editing code. The same will be done for
other use cases of the strand editing code in the future.
Now shape keys don't replace the cached base data entirely with the
static Basis shape. Instead the current state as coming from the cache
is interpreted as the variable refkey instead of the Basis key.
The Basis key is in fact redundant, but removing it would require
changing a lot of shared shapekey code, so it's left in for now.
The Key struct in the cache strands shape modifier is in fact "owned"
by the modifier, but linked in the Main blenddata, so it does not have
to be written explicitly.
the source cache and then applies modifiers afterward.
This only performs non-iterative modifiers, which don't require the
passage of time to work (e.g. shrinkwrap).
This includes storage of the shape keys in a `Key` instance in the
modifier data, and accompanying operators for adding, removing, moving,
etc. shape keys, as well as the necessary UI code.
pointer for 'from'.
The Key DNA has some very old and largely deprecated legacy code that
needs initializing, which requires either explicit info or deduction
from an ID. The cache modifier creates keys in a new environment without
an existing known ID type to deduce the data element settings from.
cached strands data.
This modifier acts as a container for shape key data (i.e. as part of
the cache library). Such shape data can be applied to cached strands
data, which allows tweaking of animated hair shapes.
This could work both as a shape for the strand goals (adding dynamics
on top) or as a final modification after dynamics. Both methods have
their advantages (pre-sim allows control and sim at the same time,
post-sim gives accurate shapes but becomes rigid).
color layers.
The layer data is added to the strands after creation, but can be
existing already. It should only be reallocated when the number of
layers changes, and must be freed cleanly in that case.
When using external forces to implement goal springs to explicit
positions in space, the system cannot calculate a stable solution based
on the goal velocities. The new approach implements goals as vertices
in the simulation, which are constrained to their animated locations.
This way they are treated like regular vertices, but the springs only
affect their non-constrained counterpart (the actual vertices).
When using the hair path deformation feature of the modifier, each copy
of the mesh can now be rotated around the path, in addition to changing
length and offset. This includes a constant phase angle as well as a
randomization factor.
simulation.
The hair sim skips the first frame (velocities are undefined there), but
still has to create the motion state data in order to have it written
as a sample. Otherwise the strands motion state samples start one sample
short and frames get mapped to one sample in the past. This then leads
to incorrect movement of all hair vertices other than the roots (which
are always clamped to the animated positions).
This fix should actually happen in wiggly-widgets branch but it's now
has some commits which are not in gooseberry and merging them night
be not really safe.
with a dupligroup and distributed rendering.
The particle duplis were generated using the global RNG (BLI_rand). This
is unstable once scenes become a bit more complex and objects are
evaluated in multiple threads.
This patch is not in master, because it changes the look of existing
particle setups.
This is experimental. It might work for simple collision-like features,
by keeping goal positions for hair above the mesh surface. However, the
nature of nearest-point lookup on meshes means that the goal position
can flip to the other side of a mesh rapidly, which would lead to
strong forces and unstable behavior.
This code should be seen as an experiment.
The UV and vertex color attribute export function expects the curve data
arrays to contain only a single attribute at a time. They must be
cleared before filling in data for each UV/vcol attribute.
content.
This group is only used for the baking operator (like the datatypes
filter), but has no effect when reading caches. The UI now uses a box
layout to reflect this.
Unlike particles, the Strands data stores UV coordinates and vertex
colors explicitly as a per-strand (const) property. This means Cycles
does not have to know the details of how particles map themselves to
a changing mesh surfaces (which is very complicated and fraught with
broken use cases and bugs). The UVs and colors are stored once for each
strand, since they are not expected to change over time (strands being
fixed to the mesh surface).
The idea is to evaluate derived meshes in multiple threads, which will
reduce overall write_sample() time. We can't make all routines threaded
in there because alembic's file IO can't be threaded.
In any case, this change gives 2x speedup of exporting render resolution
version of Franck here.
Experiment for animators to try - only do full notification of scene at
end of scrubbing, do only manual area update instead like we do for
animation. Also skip audio update unless we do audio scrubbing.
Alembic exceptions and prevent crashing.
Alembic can throw exceptions on relatively common and uncritical errors,
such as mismatching properties in files which don't fit the expected
schema. These cases should now be handled gracefully and simple reject
the cache file with an error message.
Customdata layers also store some base information, such as "active"
layer for rendering. This information is needed currently for syncing
particle UV and MCol data in cycles, even though the MTFACE layer type
itself is pretty much deprecated.
This otherwise prevents hair simulation motion showing up in renders.
The Alembic structure will have to be redesigned anyway. The current
concept of storing two separate entire scenes for viewport/render will
be replaced by a per-object detail level system. This allows performing
hair simulation only once and still use different resolutions etc.
where appropriate.
The idea is simple: make it so scene_update_for_newframe is only doing updates
of the stuff which is really needed for the currently baking group.
Implementation is a bit tricky since we don't have parent relations after the
DAG is built, so doing some graph traversal there.
This code is also now using simplified version of scene_update_for_newframe()
which means in theory we can try de-duplicating some pieces of code, but that
can be done later.
Additionally, the same approach can be used to optimize motion path calculation.
Apparently, even if the smoke is backed to an external files it still could be
tried to be simulated at the frames outside of the baked range.
Kinda weird feature which isn't really safe, but better not to crash here.
Not totally happy with the code yet, will check with Lukas or Daniel how it
could be improved further.
influence explicitly.
The previous code would only allow using the layers of the given object.
This is not useful for dupli overrides, because even finding which
layers an object in a dupligroup is in is cumbersome. It makes more
sense to use the layers of the duplicator instead.
There is an '_ex' version of the pdInitEffectors function now, with
an explicit layers argument. The simple version now also skips the
'precalc' argument, because this was true in every case except the
depsgraph dependency building anyway.
step.
This calculate can take a bit of time (some seconds to a minute in
tests), due to having to loop through all array samples. In many cases
only the basic structure is wanted.
The issue was caused by RNA passing ownership from the cache data used by Blender
to Cycles. This lead to situations when all of a sudden blender looses data it
was expecting to have.
Now instead of passing ownership we're just copying strands from the data, so both
Blender and Cycles are having it's own local data.
Ideally this data will be shared between viewport and Cycles, but that's a bit
more tricky to do without modifying RNA API. Would happen eventually tho.
A new panel is added for showing the structure and contents of archives
of a cache library (instead of simply dumping on the terminal). The
archive structure is stored in a lightweight tree structure, mirroring
the hierarchy of objects and properties in Alembic. These
object/property nodes can be expanded individually for easier navigation
through the archive.
This implements roughly the same functionality as the equivalent mesh
shape propagate operator, with some tweaks specific to hair editing.
The operator copies selected points to all the shape keys. Unlike meshes
these points may be shifted afterward to achieve consistent segment
length (this can be avoided by selected entire strands before using the
operator).
when switching the active key.
Particle shapes were always using the relative blending of keys when
evaluating hair data. This works ok for meshes, because their edit data
is entirely separate from the mesh data (using bmesh). For particles,
however, the edit mode is hardwired to the hair data, so when switching
keys in edit mode we must take care to replace everything with the
shape. Otherwise the hair data will be using blender shapes and the edit
data will overwrite any shape keys with that.
Placeholder images, means that the image sequence reserves a range for
images, displaying black while we wait for them to finish rendering.
This is meant as a feature to not break the layout of gooseberry
sequence edits while we wait for those frames to arrive.
This commit replaces name-based node matching in the mesh device update
with check of special type. It is more robust approach for adding new
nodes which could use image slots for storage. it's also adds updates
of environment texture nodes used in bump shader (this was missing in
the original image sync reshuffle commit).
Note that currently this has virtually no effect, because the mirror
option relies on exact positions of vertices, which does not happen with
random hair placement (the add brush has no mirror option yet).
Eventually topological mirroring should help with this case, but is not
implemented for either old or new strand edit yet.
These are a modified version of their BMEditMesh counterparts.
use_topology is not yet implemented for strands. Native strand topology
is not very useful for this. Instead, the topology of the scalp mesh
should be used for finding mirrored strand roots, then the arc- or
parametric length of a vertex from the root to find mirrored verts.
Conflicts:
source/blender/blenkernel/BKE_editstrands.h
When copying mesh data to bmesh the MVERT and similar customdata types
have to be omitted. Otherwise the bmesh instance ends up with NULL
pointers in customdata layers, but entries in the typemap != -1. The
effect was that when storing new steps after one or more undo, the
resulting original data would be copied, and subsequent undo steps
are ignored.
data masks explicitly.
A dummy mesh is used for strand edit undo storage like in mesh edit
to prevent unnecessary code duplication. However, when copying from/to
BMesh only the mesh data layers are copied by default, omitting the new
data layers for strands (currently only MSurfaceSample hair root data).
This uses the generalized undo stack system which is also used for
object data edit. An extension is necessary to tell the undo functions
which object is specifically used for generating undo data and
identifying the stack, since strand editing does not edit the obdata
itself.
consistent segment lengths when transforming vertices.
Warning: The implementation is not correct yet, but all the steps should
be there.
The main idea is to treat strands as a sequence of joints that are
displaced out of their original locations by a transform or other tool.
The solver then tries to find a global per-strand solution that keeps
the segment lengths unmodified, with a minimum change in angles from
the original starting shape. Such a solution is much more usable and
efficient than the current O(n^2) attempt of "spreading the error"
across the strand.
The inverse kinematics method is very flexible. It can also include
stretching, which would be very welcome for features like the length
tool. Different parts of the strand could be weighted separately using
scaling factors for the angle/stretch parameters.
Conflicts:
source/blender/physics/intern/implicit.h
mode.
This method is simple, but not really very usable. It works by
successively relaxing segments that are too long or too short, moving
both vertices along the edge between them. This is repeated N^2 times
(N: number of vertices on the strand).
A true IK solver could give a lot better results, as well as providing
many opportunities to apply weighting for targets (e.g. preferring to
move non-selected over selected vertices). Many different methods for
simple IK solvers exist, so there should be one that works well for
large number of simple strands. See e.g.
http://www.math.ucsd.edu/~sbuss/ResearchWeb/ikmethods/iksurvey.pdf
vertex positions.
This works a lot better with strokes perpendicular to the general hair
strand direction. With the previous comb tool such strokes would only
make a small dent in the hair curve and then vertices would slip out
of the tool circle. The edge combing affects the local direction of
strands, which acts as a kind of grabbing functionality by moving
further vertices in front of the tool circle. The result is that
drawing a curvy hair shape with the comb becomes much easier.
In addition, the new tool also uses edge filtering and weighting rather
than vertices. This means that small brushes also work well, instead
of having no effect when hitting the edge segments between vertices.
Further improvement could be achieved later by using a global strand
solver, which adjusts vertex positions based on an error metric along
the whole of the strand.
direction vector for the hair stroke tool.
This is necessary for directional tools such as combing, where the
stroke direction can lead to unwanted results if it changes too
abruptly.
The rationale behind this is that the BKE code could be used for
modeling hair and fur as well as a number of other features such as
grass. The primary addition to BMesh is the limitation to strand-like
topology (simple vertex chains, optionally rooted on a mesh surface).
The editor code OTOH is quite hair specific, since the result should
be suitable for hair simulation, and the workflow should mimick actual
hair grooming intuitively. Eventually the hair edit mode could become
a generalized strand edit mode with slightly different tool sets for
various purposes, but for now it is quite specifically built for hair.
Conflicts:
source/blender/blenkernel/CMakeLists.txt
source/blender/blenkernel/intern/particle.c
drawing code for edit mode.
The lighting uses the same method as the particle hair, interpreting
strand direction as the normal. This is nowhere near realistic hair
shading, but doing this with line shading alone in the fixed-function
pipeline is probably not possible. A GLSL shader could be used instead
for a more realistic alternative as part of the viewport project. At
least this simple shading mode gives some orientation feedback while
editing hair.
Currently uses the same approach as old particle edit mode (rescale
hair segments from the root on). A more sophisticated approach using
least-square error minimization of the displacement could yield better
results.
Stroke tools will be categorized by the hair elements they operate on:
vertices, segments or strands (roots). In addition to that a filter
function defines the influence of the brush. This should be defined by
the other brush settings and be largely independent of the main tool
mode.
This requires converting the old messy particle num/num_dmcache/fuv/foffset
data into the new mesh samples, which can potentially introduce floating
point errors and inaccuracies due to lack of face index mapping in the
new system. However, in any well-constructed particle system the hair
roots should be nearest to their num face, so mapping would be accurate
enough. If necessary face index data could be added to samples as a
legacy code hack, but probably it's best to eventually replace the
hair system as a whole anyway.
Currently particles only have a single weight value, controlling
pinning in the simulation (for root and virtual root verts) and goal
force scaling. This will be replaced by a full vertex group weight
system eventually.
This is more for testing purposes, since currently there is only a
single mass property for the psys as a whole. This should change in the
future though, to allow variable mass per strand or vertex.
Conflicts:
source/blender/bmesh/intern/bmesh_interp.c
Hair/Strand editing will only use a subset of the bmesh topology and
expect a specific topology that needs to be verified and enforced.
However, this extra requirement is much less work than reimplementing a
whole edit data system with the same feature set as bmesh and avoids
much redundant code.
Conflicts:
source/blender/blenkernel/intern/customdata.c
source/blender/makesdna/DNA_customdata_types.h
This means using mempools to store curve and vertex data, which allows
arbitrary addition and removal of data more easily. Also this includes
an iterator system similar to bmesh iterators (although the simpler
topology makes it a lot less complex).
Conflicts:
source/blender/blenkernel/intern/customdata.c
source/blender/makesdna/DNA_customdata_types.h
particle hairs remain visible.
Note that currently the hair root location (num/num_dmcache, fuv, foffset)
is not stored from edit data, so all hairs end up in a default location.
This makes it work more like editmesh, and avoid the awkward and
basically bad-level approach in particles, where the edit data is an
anonymous pointer in particle systems together with a callback for
freeing.
Conflicts:
source/blender/blenkernel/CMakeLists.txt
sampling system to keep the code simple.
Now there is a MSurfaceSampleStorage struct that encodes the storage
details, which the algorithms don't have to care about.
Disabling group -> duplicator dependencies would in theory make caches
more attractive because the invisible objects don't have to be updated
just because of the group.
However, the viewport and render starts to behave unpredictably without
these updates, because the dupli cache relies in many ways on the
objects it is supposed to override.
This option makes it so BVH does not use pre-aligned storage for triangle vertex
coordinates which was originally needed for faster coordinate lookup when doing
triangle intersection test. This array gives up to 10% performance comparing to
fetching individual coordinates but it also used 12 floats per BVH primitive,
which might translate to quite huge array in a complex scene.
Intention of this option is to investigate if this is a right direction to make
gooseberry files being able to render on local farm which is not totally great
in memory.
Current approach is not totally cheap, meaning even the case with the storage
enabled might be slower, but currently it's within 1%.
This works like the existing effectors when using "surface" mode: It
selects the closest point on the mesh surface and creates a force based
on distance and falloff.
Unlike the old effectors it also supports signed distance, based on
the surface normal, which gives more control over the allowable distance
of strands to the mesh surface.
cached group itself.
This allows using the dupli group objects themselves as force fields,
in particular for collision objects in strand simulation. Without this
feature only the original objects of are recognized by the effectors
system, and even if duplis worked properly their settings would not be
accessible due to linking and dupli group hiding. The cache modifier
circumvents this issue by providing a new force field system, separate
from the current effectors.
These classes were used previously to write parts of the Blender DNA
directly to Alembic. Their code is shared with other classes that are
still in use, so none of the really substantial parts have been deleted.
This only removes trivial C function wrappers for parts of the C++ code
that are not used directly any more from outside the bl_pointcache
library. Some internal parts may be removed later, this cleanup is
mostly to reduce code noise.
Using two full scene nodes for render/realtime data creates a lot of
duplication in both storage and processing time. Instead storing
specific data types like meshes in different versions keeps duplication
to the necessary minimum and allows easier fallback where available.
There used to be quite huge 3D arrays stored in memory which are only needed for
simulation steps and not used at all if the smoke is baked to file. That memory
is unmanaged by blender and not visible in the info space header and in practice
they could easily be gigabytes for hires smoke.
This commit only addressed hires smoke since it's the more important at this
point, and non-hires smoke wouldn't have such noticeable benefit.
In the case of tornado file it gives around 20% memory saving (which is about
26GB vs. 33GB on later frames of 01.03.02.A3 shot.
This means no motion state data is generated for render mode, this
requires some larger changes to the way render/realtime data is stored
in the caches.
Before this the hair sim would be applied indiscriminately to all the
strands in the cache data. Now an object/psys combination from the dupli
cache must be selected. Note that this is not the actual target of the
hair simulation, which still operates on the cache overrides instead.
The Object/Psys only functions as a selectable key, if no matching data
is found in the cache no hairsim will be applied.
This way we can get rid of inefficient memory usage caused by BVH boundbox
part being unused by leaf nodes but still being allocated for them. Doing
such split allows to save 6 of float4 values for QBVH per leaf node and 3
of float4 values for regular BVH per leaf node.
This translates into following memory save using 01.01.01.G rendered
without hair:
Device memory size Device memory peak Global memory peak
Before the patch: 4957 5051 7668
With the patch: 4467 4562 7332
The measurements are done against current master. Still need to run speed tests
and it's hard to predict if it's faster or not: on the one hand leaf nodes are
now much more coherent in cache, on the other hand they're not so much coherent
with regular nodes anymore.
Reviewers: brecht, juicyfruit
Subscribers: venomgfx, eyecandy
Differential Revision: https://developer.blender.org/D1236
when not needed.
The pathcache data is only required in the first frame to construct the
child strand shapes. For subsequent frames the children are calculated
using the initial shape and parent deformation, so particles don't need
to recalculate all the time.
This gives a significant performance increase of the baking process when
using a lot of complicated child hairs.
The basis for this optimization is that child strands have a shape that
does not actually change over time: the particle code does not enforce
this formally, but in fact all the clump/kink/roughness algorithms take
great care to not introduce changes of shape over time.
The final look of child hairs is achieved only by following the parent
hair deformation, i.e. by applying the offset of the matching parametric
position on the parent strand.
This means that for caching child strands it is sufficient to store the
full vertex data only in the first sample, and then apply the parent
deformation on subsequent frames using only the animated root matrices.
In test cases this seems to reduce the cache size to something between
10-20 % of the original size (down to some hundred MB from some 10 GB).
Further optimizations could be achieved by using smaller data types,
such as quaternions instead of 3x3 or 4x4 matrices for the remaining
child data.
Particles use 0..100 range for parent particle "times" (curve parameter)
and 0..1 for children. For caches this is now uniformly calculated in
the 0..1 range to avoid breaking child interpolation.
caches.
This allows child strands to follow the motion of parent strands as
calculated by the hair simulation. Unlike the particle system path
caching, this method does not regenerate all the children every frame.
Instead, it relies on an initial child setup that defines the base
shape, then applies the parent motion as a weighted linear deformation.
The result is in fact the same as with regular particle clumping, kink,
roughness etc.. Particles also take care to not change the child shape
when the parent moves, but this is not formalized anywhere (which makes
changing particle code quite difficult). So ignoring the particle code
is both permissible and efficient.
The idea is to avoid having original BVH and BVH packed into scene BVH and hence
reduce memory footprint.
This change doesn't give any measurable differences on it's own, but together
with D1215 and D1217 it gives quite nice results.
Reviewers: campbellbarton, brecht, juicyfruit
Subscribers: eyecandy
Differential Revision: https://developer.blender.org/D1218
This way memory overhead caused by the BVH building is not so visible and peak
memory usage will be reduced.
Implementing this idea is not so straightforward actually, because we need to
synchronize images used for true displacement before meshes. Detecting whether
image is used for true displacement is not so striaghtforward, so for now all
all displacement types will synchronize images used for them.
Such change brings memory usage from 4.1G to 4.0G with the 01_01_01_D scene
from gooseberry. With 01_01_01_G scene it's 7.6G vs. 6.8G (before and after
the patch).
Reviewers: campbellbarton, juicyfruit, brecht
Subscribers: eyecandy
Differential Revision: https://developer.blender.org/D1217
The idea is to give artists a simplier way to control memory usage in such
scenes as grass fields by doing automatic object culling based on whether
they're visible in the frame or not.
This is controlled on per-object level. In order to use this option few
steps are required:
- Allow renderer to use camera culling (Performance panel of render settings)
- Set camera cull margin (measured in relative value to the render resolution)
- Enable Camera Cull for objects which are desired to be culled
(object culling option could be found in Option panel in object buttons).
Interface decisions are not final for sure and to be refined if this
option is considered good enough for production.
Reviewers: juicyfruit, brecht, campbellbarton
Subscribers: venomgfx, eyecandy
Differential Revision: https://developer.blender.org/D1230
popup and clipboard output.
For a production-size archive the info string can become really large,
and putting it into a buffer takes a long time. As a debugging tool the
stdout printing is sufficient for now and can be done as a stringstream.
Arbitrary wind force "density" factor has been moved out of the force
function now, so cloth simulation can do this on it's own without
affecting the strand sim.
In addition to the original particle hair sim settings the parameters
for strand sim have a curve to define the strength of goal springs along
strands. This useful because currently there is no way to override the
weights of strands. This would require a new particle edit mode that can
work with non-particle data in a sane way ...
This takes an arbitrarily large amount of space in the UI and does
currently not have a good purpose.
Eventually this information could be displayed in a dedicated part of
the UI, with proper scrolling.
This code works much like the main object drawing code and has to take
the same precautions regarding replacing the derivedFinal pointer in
Objects. This pointer may be replaced during drawing calls, regardless
of the "ownership" indicated by needsFree.
Reading from an empty object in Alembic will throw an exception, which
is not easily handled yet. So rather avoid annoying crashes the clumsy
way for now.
The code for syncing Strands and StrandsChildren data to Cycles curves
is almost identical, so to avoid code duplication a little templated
traits type has been defined, which provides the appropriate accessors
for both cases. This is very local and should not be too confusing.
This creates child strands along with the parents. These are not yet
deformed by parents or simulation, and are also not written back into
subsequent caches yet.
data.
Child strands have their own struct type for vertices and curves to
avoid unnecessary overhead (parent curves store a full 3x3 matrix after
all).
Child strands may be constructed from particle pathcaches, or read from
curves data in alembic files.
These are dummy values currently. The UV and vcol values will be stored
in strands directly, unlike particles which evaluate them every time;
this is a much safer and more efficient approach that makes strand data
truely independent from the "emitter" mesh. Such data will be made
available later, primarily for child curves.
Still buggy, but the basic workflow is there:
When a cache library is used in conjunction with a group duplicator and
it has strands that match the particle systems, Cycles will use the
new Strands structure to construct its internal curves.
This is not strictly needed because the strands data is only created
at runtime at this point. However, it might be useful to later include
this in blend files.
Also the C++ RNA API has a bug that makes non-DNA collection properties
difficult (the length function is not implemented properly).
particles.
This is currently the same as the ParticlePathcache writer class, but
will be modified somewhat later to store additional information such as
parent weights. The purpose of this cache object is not to populate the
particle child caches, but to store renderable data associated to dupli
cache strands.
This is a separate struct to avoid storing unnecessary data (this means
a bit of code duplication for iterators). The child strands can be used
as the actual render data, while the parent strands usually would be
used only for simulation/deformation purposes.
This matrix is needed to create a stable and smooth coordinate system
along the strands, for things such as bending forces and child hair
deformation. The base matrix is defined on the "scalp" mesh and should
be stable wrt. deformation and animation of the mesh. For any point on
the strand a matrix is then calculated using parallel transport, i.e.
by rotating the base matrix successively along each curve corner.
The overall world space matrix for dupli sims has to be the combined
obmat of the cached object as well as the duplicator for the dupligroup
instance. The cached strand data is generally in object space, so the
matrix has to be applied to get all the forces and interactions right.
This compensates the transformation of the dupli instance being cached,
so that forces such as gravity are in the correct reference frame.
Note that this does not yet generate fictitious forces resulting from
a moving and/or accelerated frame of reference. For this we would also
have to calculate linear/angular velocity and acceleration of the dupli
object.
This is the first actual drawing/display setting for smoke, so a new
panel "Display" has been added to give it a home in the UI.
The name "thickness" has been chosen deliberately to distinguish it from
density, since the parameter only affects OpenGL drawing but not the
actual physical density values.
The strong stretch forces lead to awkward lengthening of segments when
the damping factor is too high.
In fact, in a natural hair strand the stretching usually means the hair
itself is curly and stretches as a helical spring. In that case
the damping is quite small compared to the stiffness, and little energy
is lost to the stretching (the hair becomes "bouncy"). When the hair is
very stiff the damping should also be small in order to avoid extreme
forces resulting from the hair root location constraint.
The solver can calculate the de-facto velocity of the root using the
difference of the already-updated vertex location and the state from the
previous step.
This will allow debug visualization data to be stored inside caches
along the actual simulation state.
While the regular simulation allows examining simulation data on-the-fly
by stepping through the regular timeline, the new baking mechanism used
for caches does not easily allow simulation data to be visualized frame
by frame. Caching this data will allow adding it to the global sim debug
data.
This would also still be very handy if the baking process itself becomes
more interactive again. Unlike the current simulation progression, the
cached data can be accessed randomly, so scrubbing throught the timeline
becomes possible.
This color is currently only displayed in the viewport (when enabling
"Texture" color mode in the Display settings). It will be used for
controlling the smoke color when using particles for smoke emission.
Conflicts:
source/blender/blenkernel/intern/particle.c
source/blender/editors/space_view3d/drawobject.c
source/blender/makesdna/DNA_particle_types.h
source/blender/makesdna/DNA_texture_types.h
source/blender/makesrna/intern/rna_particle.c
This extends the point density evaluation to also store RGB color values
in the array provided by Cycles.
Since internally all Cycles textures are 4-float RGBA textures anyway,
it does not make a lot of sense to store density and color separately.
This could eventually be preferable to avoid unnecessary storage.
This is basically copied from existing cloth sim settings, with a good
deal of cleanup and sanitization.
Unlike cloth parameters, the damping values are described as relative
to their associated stiffness values for springs. This is much easier
to use in practice and less prone to lead to unstable simulations.
Damping simply works best when the force is in the same order of
magnitude as the stiffness, so having a relative factor requires much
less adjustment on the user side.
Also renamed StrandSimParams to HairSimParams, since strands are only
the agnostic data structure, while these parameters are specifically
used to simulate hair-like behavior. Other simulations could use strands
but implement completely different kinds of physics (e.g. grass, ropes).
Allows mattieu's masterplan to keep overdrop at higher sequencer space
and all strips lower.
This won't align text so well though, but will leave it simple and he
can give feedback later.
This function is used in every part of the code, and has been causing
great pain when deleting 15 hours worth of baking in an instant.
The complexity of the code makes it unfeasible to fix this selectively,
so for now simply disallow the code from deleting any of the files.
For selected well-defined cases the deleting can be reenabled later,
e.g. when the user presses the `Bake` button and confirms deletion in
a popup.
Seems like there is currently now way to get the full data path
reliably. So instead of the old "..." this patch just displays
(null) which also isn't really useful.
modification.
The bake operator will now generate output based on the 'source_mode'
setting:
* When the source is SCENE it uses the basic object data as stored in
the Object ID datablocks (DerivedMesh, particle hair strands etc.)
* When the source is CACHE it fills a temporary DupliCache with data
from the cache archive (like it would for the display dupli_cache,
but also supporting render data). This dupli cache is carried over
between frames during baking, which allows modifiers to act as
simulations and sequentially advance motion states.
This commit implements point density texture for Cycles shading nodes.
It's done via creating voxel texture at shader compilation time, Not
totally memory efficient, but avoids adding sampling code to kernel
(which keeps render time as low as possible), In the future this will
be compensated by using OpenVDB for more efficient storage of sparse
volume data.
Sampling of the voxel texture is happening at blender side and the
same code is used as for Blender Internal's renderer.
This texture is controlled by only object, particle system and radius.
Linear falloff is used and there's no turbulence. This is because
falloff is expected to happen using Curve Mapping node. Turbulence
will be done as a distortion on the input coordinate. It's already
possible to fake it using nose textures and in the future we can add
more proper turbulence distortion node, which then could also be used
for 2D texture mapping.
OSL is not currently supported. There's no actual stoppers for support
it, but so far it's not really a priority at this point.
Reviewers: campbellbarton, juicyfruit, brecht
Subscribers: campbellbarton, dingto, eyecandy
Differential Revision: https://developer.blender.org/D1208
Note that the fixed-function OpenGL pipeline does not support true
strand normals. The shading model used copies the method implemented for
particles, using the edge directions as normals. This is totally
unphysical but at least gives some indication of direction. Viewport
refactor and programmable shaders are needed to make this work nicer.
This is used to prevent empty dupli lists when reading the cache fails.
In that case the duplilist function will now revert to default scene
evaluation.
libraries.
Having a cache archive output in each modifier is not really practical.
Now the cache library has at most 2 file paths. These are used based on
2 associated settings: source mode/path and display mode/path.
* The SOURCE mode determines whether the original scene data is used as
input or a cache archive. If the scene input is used the dupli group
objects will be evaluated as usual with Mesh data, modifiers, proxy
armatures, etc.. With cache input the data stored in a cache is used to
override the scene data instead.
* The DISPLAY mode is essentially a toggle for the whole cache modifier
stack. If it is set to 'source' the respective source data is used
without further modification. If set to 'result' the data from the
output cache archive is used, which can be generated using the bake
operator. During baking the data will be passed through the cache
modifiers to create a variation of the original source data.
Now the filtering is simply based on the data types that should go into
the cache, instead of selecting each object and component individually.
This is slightly more limited and may need to be revisited again later,
but for the time being it is much less confusing and clumsy. Filtering
by objects can be accomplished by creating groups accordingly. Making
groups specifically for caching is totally acceptable.
The draw code was restoring the derivedFinal mesh unconditionally after
drawing duplis. However, the drawing code can in some cases replace the
derivedFinal pointer during drawing (bad!). This then leads to invalid
pointer access.
Fix is to only touch the derivedFinal when it's actually a dupli cache
mesh.
The job invocation should happen only in editors/. Also it makes sense
to modify the bake operator such that it supports both the basic cache
library and an optional modifier output.
The design for this area is in progress anyway, probably the cache
library archive paths will be changed so that there is always one input
and optionally an output path, with all the modifiers working in
sequence.
Theoretically we could write a stitcher that writes only the parts of
the data affected by a modifier and simply copies the rest, but this
is much more involved and not necessary at this point.
Unlike the particle hair writer this one does not work with the particle
system data but the new Strands data. This will allow successive
manipulations of cached hair data by first storing the initial particle
grooming data ("hair edit"), read this data from the cache into a
Strands instance, then apply hair simulation and write the result back
into a second Strands cache.
Cache baking means the cache modifier should read input caches over the
given frame range and produce the correct output for writing into the
output cache file.
Cache modifiers can optionally implement a 'bake' function. This is used
through a bake operator from the cache modifier panel. Baking is
executed in a job, which will help with cancelling bakes and displaying
status info.
This is implemented badly: when using disk caches i reads the *entire*
cache from the disk to create the trail. In the process it also clears
the cached_frames array, which makes it look like the cache was deleted.
dupli cache.
This makes the cache modifier stack work more like actual modifiers:
Each will take the previous result and write it into its own output
file. The last output is the final result used for viewport display.
When using a particle inflow object, there is now an option "Set Color"
which uses particle texture color to override the uniform smoke emission
color.
Particles must have one or more textures with the "Color" influence
enabled (the resulting color can be visualized in the viewport using the
"Texture" display option). The color will then replace the default smoke
flow setting and allows variable color per particle.
Combined with "Strand/Particle" texture mapping this can also be used
to change the particle emission color over the lifetime of particles or
make variable colors for each particle in the system.
Note that this currently does not work with child particles.
This color is currently only displayed in the viewport (when enabling
"Texture" color mode in the Display settings). It will be used for
controlling the smoke color when using particles for smoke emission.
The rationale here is that we don't try to replace particle data
temporarily like we do with DerivedMesh. This would be needed for
drawing cached data overrides in the viewport and pass them to renderers
(unless these read Alembic directly) and later for performing dupli
simulation.
This data will be used for dupli simulations later on. Child path
generation could also be done based on this data without involvement of
particle systems.
This feature is mostly useful for the "view selected" operator. It is
also used in the "set origin to geometry" operator, but since the
cache overrides the object geometry anyway the effect may not be what
users expect (which is acceptable).
Note that Cycles currently only supports tessellated triangle/quad
meshes. Alembic PolyMesh generally has ngons, so external tessellation
is required until cycles gets a proper tessellation implementation of
its own.
standalone.
The cycles XML files now can refer to Alembic (.abc) files. This will
call the default alembic reader to read in scene data. Currently it
simply prints the Alembic file structure.
Eventually a proper schema needs to be defined for both xml and abc.
Also care has to be taken to handle potential conflicts between settings
both within xml/abc and between them.
This adds Alembic to the standalone application version of cycles.
Files can be specified as XML or Alembic, or use automatic detection
based on the filename extension.
Currently the Alembic reader just dumps the file structure to stdout
as a test.
This means we don't bluntly store all the data in a group, but use the
selection from the cache library. It also helps to avoid issues with
object visibility which is not yet stored in the cache.
overriden data that is owned by the cache.
This is not at all nice ... Hopefully it doesn't get too complicated to
work around all these drawing code and depsgraph issues, so the code
can be understood and replaced at some point in the future.
Caches now create 2 new roots below the main 'top' object of Alembic:
root and root_render for realtime and render data respectively.
This makes it easy to switch the whole archive to either of the modes
during baking and for constructing dupli caches.
Alternatively individual objects could store hires versions of their
data. This would also be more efficient if the cache contains many
simple objects which don't have 2 different variants. However, such
design decisions are difficult to make at this point and the
implementation can be modifier later.
This is the default now. It should make workflow a lot more foolproof
and convenient, since having only one of these modes active at a time
very easily leads to broken renders and confusing situations.
The problem is mostly due to the complicated way the depsgraph layer
feature is used to handle duplicator visibility. The duplicator is
declared as a child of its group's objects (even though no real
dependency exists!), so that a visible duplicator triggers updates of
invisible group objects, making instances of hidden groups possible.
However, dupli caches have to disable this dependency in order to avoid
unnecessary costly updates in hidden layers which are overridden by
cached data anyway. At the point where these dependencies are created
the evaluation context is unknown though, which means we cannot
distinguish between render and realtime evaluation for the purpose of
cache reading ...
duplis.
Particle systems can not be overridden from caches easily, there are too
many strings attached to the data and code to make this reliable.
Instead, a new simplified data structure for reading hair from caches
will be added, which replaces drawing and rendering of particle data.
The original particle data is not updated through duplis, so is usually
out of sync and should not be displayed.
pointers.
Relationship between CacheLibrary, duplicator Objects and Groups is
difficult. There are a number of somewhat conflicting goals:
- CacheLibraries write out data for objects and dupli groups. Multiple
objects can be stored in the same cache: CL *->* GR
- Objects can override a dupli group with different caches: OB *->1 CL
- As before, each object can be the duplicator for one group: OB *->1 GR
To combine these requirements, the first relationship will be made
indirect. Only the Object -> Group/CacheLib relations are explicit
pointers in the DNA. For finding all objects contained in a cache
library the usual recursive DNA tagging system must then be used.
unnecessary dependencies.
This flag will replace the current "read" mode on cache libraries.
Beside enabling cache reading, it also disables the current "fake"
dependencies between duplicators and their group objects. This is
exploiting the layer visibility mechanism in depsgraph to ensure that
animated group objects get evaluated when used by a visible duplicator,
even when they are not themselves visible. These dependencies cause
group object updates even if the duplicator is using cached results.
To avoid this unnecessary overhead and make caching worthwhile we
rebuild depsgraph without these relations when using the cache instead.
If a duplicator has cached data it will now replace the derivedFinal
mesh of objects with the cached version for drawing.
This is a compromise atm: It would be better to actually draw derived
meshes directly, so that we don't have to modify objects. Then we could
also have multiple different instances of the same orignal object
(in whatever way these might be defined). DNA Objects would then be
totally separate from duplis, but at this point the drawing and render
code makes this unfeasible.
The layout of the Alembic files resembles the DNA structure in Blender:
- On the top level (under the top/root node) there are Abc::Objects for
Blender ID datablocks (currently Object and Group)
- Objects store final data (DerivedMesh) and later simulation results
etc.
- Groups store their full duplilists for instancing. Currently there is
no recursive nesting of groups, since this would limit duplis to
dupligroups and exclude e.g. duplifaces.
On reading the duplilist gets reconstructed and stored in the DupliCache
for a duplicator empty (the group instance). DerivedMesh data is stored
in a hash table for each instanciated object and can later replace
finalDM in drawing and rendering.
Now the base types for readers/writers are not nominally forming the
interface any more (they may be removed entirely later). This makes
possible a cleaner init method directly in the Abc Writer/Reader
classes.
Further work may be required in this area.
This is more in line with how readers work in the Blender Alembic
implementation elsewhere.
Generally, readers are less persistent than writers: they are created
whenever cache results need to be updated (e.g. on frame changes) and
discarded afterward. Writers OTOH stay alive during the whole baking
job, since they keep the references to Alembic Writer instances and can
only be deleted once the writing for that part is done.
Note that the cache stores dupli matrices without the final parent
transform, since it only knows about the group itself. The duplicator
obmat is applied to the duplis after reading the cache.
Now we store duplilists entirely inside a single alembic object for the
group. This allows using all the generated duplis, which would be
difficult if the alembic file had to define all the possible recursive
dupli relations that Blender allows, beside straightforward Group duplis.
Uses the duplilist generated by Blender to define instances, instead of
recreating the group layout. This omits some information about actual
structure of the DNA, which might be useful later on. The main problem
is that the duplilist itself does not encode this, so it's a tradeoff
between either including the Group structure or omitting the other
dupli types, like face, vertex, particle duplis.
creation call.
This is executed *a lot* (even for simple things such as viewport
panning), so the code is probably not suitable in this form. At least
it could do a frame comparison to avoid unnecessary updates.
This is necessary for the current viewport drawing and rendering code,
which expected each dupli instance to represent a copy of data in the
DNA.
The code maps base-level objects in the cache to DNA Objects inside the
dupligroup by name. Only objects that can be found in the blend data
will be allowed for DupliObjects.
This is a placeholder for proper depsgraph integration. Eventually frame
changes and some other updates should rebuild dupligroup caches
automatically using the depsgraph. Until then this operator is a quick
way to test the IO from caches and the further drawing and rendering
(TODO).
BKE (DerivedMesh, particles, cloth).
The new cache implementation will be used for constructing dupli data
instead, bypassing the complexities of the modifier stack.
Conflicts:
source/blender/blenkernel/intern/cloth.c
source/blender/blenkernel/intern/particle.c
source/blender/blenkernel/intern/particle_system.c
Conflicts:
source/blender/blenkernel/intern/particle.c
source/blender/blenkernel/intern/particle_system.c
Alembic caches.
This creates representations (Abc::Object) for Blender Object and Group
datablocks in the Alembic files and uses Alembic instancing to define
the dupligroup hierarchy. This leads to a relatively flat hierarchy in
Alembic files:
Top -> Object/Group -> DerivedMesh/Particles/Hair/Cloth/Smoke/...
The dupligroup structure can not be represented by a hierarchical
structure such as the Alembic object nesting, because of the
many-to-many relationship between objects and groups (a group can
contain multiple objects, multiple objects can instance the same group).
Instead we use the instancing feature of Alembic to represent
dupligroups. This is created in 2 stages to ensure all the main ID
blocks have been serialized before creating references.
This is not clearly documented for Alembic, but apparently properties
inside compounds still need to be name uniquely for the whole object.
This is somewhat involved for Blender's CustomData, because we have
5 different customdata elements for meshes (vert, edge, face, poly,
loop) and each of these can have the same types and multiple layers of
the same type ...
CustomData layers are pruned by the CDDM_copy function when they have
CD_FLAG_NOCOPY set. This is based on later modifiers in the stack, which
can specify that they require certain data layers - but the caching
modifier itself should store only what is needed by later modifiers.
It means we cannot easily keep a full copy of the DM in the cache
modifier to writing into caches later.
For now the hackish solution is to temporarily disable NOCOPY flags when
copying the DM. This is really not nice and needs a better solution.
This is a skeleton feature that provides a general way of storing
CustomData types. Currently only ORIGINDEX layers are implemented, the
code is designed to make extension easy.
Storing CustomData layers in Alembic is a bit involved because the
complex structs often used as customdata need to be de-interleaved for
Alembic into a set of POD (plain-old-datatype) array properties.
In addition the property names should be unique, so that mapping abc
properties back to customdata layers is safe. This works by using 2
levels of compound properties: the first level stored per CD type
properties, with a number of properties for each layer of this type,
using either a name or index (for unnamed layers). The internal
properties can then in turn be compounds, if structs need to be
serialized into PODs.
Abc property readers/writers are created dynamically for the CustomData
compounds. This is necessary because we don't know in advance what kind
of data layers a DerivedMesh or other CD user will have, and this can
change each frame in theory. Alembic is easier with state data schemes,
but using it this way is possible (if somewhat cumbersome).
This is totally weird and convoluted, no idea if correct.
Conflicts:
source/blender/blenkernel/intern/particle_system.c
Conflicts:
source/blender/blenkernel/intern/particle_system.c
This creates a string with information about all the objects and
properties contained within a (Alembic) archive, used by a cache
library.
The operator has 3 modes of presenting the info string:
- stdout, ie. printing to the terminal
- popup window (not very useful usually due to size limits and lack of
scrolling)
- clipboard copy
result read from the cache.
Mixing this with the output_dm used for writing leads to undefined
situations where the DM was released but should actually be passed on.
This designates a cache library to be used either for the viewport or
for renders. A "Render" cache library will evaluate modifiers with
render settings and a "Viewport" cache library will use viewport
(realtime) settings.
When reading the cache, the library will only be
used for the assigned purpose, i.e. a Render cache does not work for
viewport caching and vice-versa (although a cache can be baked for one
setting and then switched afterward).
Note that render results will never be visible in the realtime viewport
due to the way object evaluation is handled in Blender at this point
(render settings are only evaluated explicitly during renderer sync).
Conflicts:
source/blender/blenkernel/intern/particle_system.c
Conflicts:
source/blender/blenkernel/intern/particle_system.c
out of pointcache into blenkernel.
This is quite simple and repetitive and there is not need to have this
in the main pointcache/Alembic API. The code is mostly concerned with
logic of DNA data, so pointcache shouldn't have to deal with it.
The pointcache library is now pretty much independent from ID blocks and
should not be responsible for handling file paths. The path construction
is also fairly straightforward now compared to the old point cache
system, with only basic conversion of relative to absolute paths for
loading archive files.
python code to unify symbols.
This is necessary because the operator for adding new items (as opposed
to the enable/disable button) cannot be shown with the same checkbox
button. The UI template function can display a custom button for the
operator, so the look becomes less confusing.
This now appends a default extension based on the cache backend used.
At this point this is always Alembic (.abc) but would allow other
backend formats in the future.
In addition to the object name filtering, items in cache library groups
can now be filtered by type as well.
Existing items in the cache are always displayed, so as to not hide
important information (what gets stored in the cache). The filtering
is primarily a utility to simplify searching inside the group for things
that should be added to the cache.
This requires a better design and is not so easy to implement properly
within the limits of RNA definition. These collections don't physically
exist in the DNA, they are mainly utilities for looping over
//potential// items in a cache library. For now the python code has to
be adapted to only show valid items, until the RNA provides a good
solution.
This is also used during the bake process to avoid confusion: The read
flag gets disabled for the baking cachelib, so that objects don't try
to read cache data that is supposed to be generated.
CacheLibrary datablock has a generic unlink function now, but currently
nothing actually links to cache libs themselves, so it's empty. Still
good to keep this in mind for the future.
The `bf_pointcache_alembic` code is a separate library, to avoid
muddling up core code with alembic includes and preprocessor defines.
Alembic stuff only belongs strictly into alembic code and can be
disabled cleanly.
The `bf_pointcache` and `bf_pointcache_alembic` libraries had a circular
dependency, because the alembic implementation functions were called
directly. Now there is a "Factory" class to abstract the creation of
concrete implementations for readers and writers.
`bf_pointcache_alembic` defines this factory and is registered
//outside// of the core `bf_pointcache` lib, so there is no linker
circularity.
This was an artifact from the previous way of mapping non-0 start frame
to time 0.0. Now we start at times > 0.0 to match with the start frame.
Both ways are possible, can be changed later if needed.
Writers were always starting at time 0.0, which means that for start
frames > 1 the readers would always be off. Now match the writer start
frame to the actual Blender start frame.
cache library system.
The Cache modifier is now an optional "break point" of the modifier
stack:
- Without a cache modifier the stack works as before. Baking will write
the final stack result. After baking the cache replaces the whole
stack.
- With a cache modifier the stack result at the modifier's position is
stored. The cache is then applied as the output of that modifier,
skipping preceding modifiers. That way additional modifiers can be
applied on top of the cache.
- When using multiple cache modifiers, only the last (active) one will
be used, since all previous cache results would be discarded anyway.
This can happen if an object gets deleted or isn't loaded for some
reason. The item should just be ignored in that case and removed at the
next opportunity (cleanup function).
of constructing names internally.
This helps prevent name collisions and guarantees a consistent naming
scheme for putting multiple items in the same cache.
refactoring simpler.
Since the new approach is not tied to the old set of point cache data
types there is really no need to carry their empty husks around. Once
the new caching system is defined in detail we can add back whatever
makes sense.
Now instead of each reader/writer creating its own archive, the archive
is created by the caller in advance and passed as a constructor
argument. This means that multiple items can be stored together in the
same archive.
iterating over all objects eligible for caching in the group.
This allows for nested dupligroup instances as well. All objects that
are instantiated at least once by any group can be included in the
respective cache, but get represented only once because the cached data
is the same anyway.
subtype/index.
This omits possible instancing and recursion by dupli groups, but since
the data of instances is always the same in Blender at this point, there
is little need to take them into account for caching.
At some point in the future it may become desirable to store full dupli
hierarchies in the cache, but it doesn't make sense to try to design a
fully-fledged path descriptor for this hypothetical case now.
object group.
This is somewhat experimental, eventually we may want to link to Objects
instead, or allow multiple cache targets for the same cache, etc.
and files.
At it's core this is just a file path, but many different cache users
may refer to this, so having a dedicated ID block helps. It can be
compared to Image datablocks, which also primarily are used for data
on storage, but can be packed with the blend file, and carry some
additional information that would be cumbersome to keep sync'ed
otherwise.
The name 'CacheLibrary' deliberately resembles the 'Library' datablock:
just as a Library stores ID blocks in a physical file, a CacheLibrary
stores cached data (in Alembic HDF5/Ogawa or other formats).
Conflicts:
source/blender/blenkernel/BKE_pointcache.h
source/blender/blenkernel/intern/pointcache.c
source/blender/makesdna/DNA_pointcache_types.h
Conflicts:
source/blender/makesrna/intern/rna_main_api.c
When writing DerivedMesh data, the modifier result at the point of the
modifier will be used for writing to the cache. If this modifier is not
used the derivedFinal mesh is used instead.
The pointcache API is designed to keep the general concept of caching
separate from the concrete Alembic implementation. Other types of file
export/import would be possible, e.g. for OpenVDB data.
Adds Alembic as a dependency and build support in cmake and scons.
Also extends the install_deps.sh script with a temporary installation
procedure for the Alembic libraries. This is still very hackish and
needs to be improved.
This lets users set a start frame at which a cached smoke simulation
starts. This offset is simply subtracted from the current scene frame
for evaluating the cache.
The rationale here is that we don't try to replace particle data
temporarily like we do with DerivedMesh. This would be needed for
drawing cached data overrides in the viewport and pass them to renderers
(unless these read Alembic directly) and later for performing dupli
simulation.
This data will be used for dupli simulations later on. Child path
generation could also be done based on this data without involvement of
particle systems.
This feature is mostly useful for the "view selected" operator. It is
also used in the "set origin to geometry" operator, but since the
cache overrides the object geometry anyway the effect may not be what
users expect (which is acceptable).
Note that Cycles currently only supports tessellated triangle/quad
meshes. Alembic PolyMesh generally has ngons, so external tessellation
is required until cycles gets a proper tessellation implementation of
its own.
standalone.
The cycles XML files now can refer to Alembic (.abc) files. This will
call the default alembic reader to read in scene data. Currently it
simply prints the Alembic file structure.
Eventually a proper schema needs to be defined for both xml and abc.
Also care has to be taken to handle potential conflicts between settings
both within xml/abc and between them.
This adds Alembic to the standalone application version of cycles.
Files can be specified as XML or Alembic, or use automatic detection
based on the filename extension.
Currently the Alembic reader just dumps the file structure to stdout
as a test.
This means we don't bluntly store all the data in a group, but use the
selection from the cache library. It also helps to avoid issues with
object visibility which is not yet stored in the cache.
overriden data that is owned by the cache.
This is not at all nice ... Hopefully it doesn't get too complicated to
work around all these drawing code and depsgraph issues, so the code
can be understood and replaced at some point in the future.
Caches now create 2 new roots below the main 'top' object of Alembic:
root and root_render for realtime and render data respectively.
This makes it easy to switch the whole archive to either of the modes
during baking and for constructing dupli caches.
Alternatively individual objects could store hires versions of their
data. This would also be more efficient if the cache contains many
simple objects which don't have 2 different variants. However, such
design decisions are difficult to make at this point and the
implementation can be modifier later.
This is the default now. It should make workflow a lot more foolproof
and convenient, since having only one of these modes active at a time
very easily leads to broken renders and confusing situations.
The problem is mostly due to the complicated way the depsgraph layer
feature is used to handle duplicator visibility. The duplicator is
declared as a child of its group's objects (even though no real
dependency exists!), so that a visible duplicator triggers updates of
invisible group objects, making instances of hidden groups possible.
However, dupli caches have to disable this dependency in order to avoid
unnecessary costly updates in hidden layers which are overridden by
cached data anyway. At the point where these dependencies are created
the evaluation context is unknown though, which means we cannot
distinguish between render and realtime evaluation for the purpose of
cache reading ...
duplis.
Particle systems can not be overridden from caches easily, there are too
many strings attached to the data and code to make this reliable.
Instead, a new simplified data structure for reading hair from caches
will be added, which replaces drawing and rendering of particle data.
The original particle data is not updated through duplis, so is usually
out of sync and should not be displayed.
pointers.
Relationship between CacheLibrary, duplicator Objects and Groups is
difficult. There are a number of somewhat conflicting goals:
- CacheLibraries write out data for objects and dupli groups. Multiple
objects can be stored in the same cache: CL *->* GR
- Objects can override a dupli group with different caches: OB *->1 CL
- As before, each object can be the duplicator for one group: OB *->1 GR
To combine these requirements, the first relationship will be made
indirect. Only the Object -> Group/CacheLib relations are explicit
pointers in the DNA. For finding all objects contained in a cache
library the usual recursive DNA tagging system must then be used.
unnecessary dependencies.
This flag will replace the current "read" mode on cache libraries.
Beside enabling cache reading, it also disables the current "fake"
dependencies between duplicators and their group objects. This is
exploiting the layer visibility mechanism in depsgraph to ensure that
animated group objects get evaluated when used by a visible duplicator,
even when they are not themselves visible. These dependencies cause
group object updates even if the duplicator is using cached results.
To avoid this unnecessary overhead and make caching worthwhile we
rebuild depsgraph without these relations when using the cache instead.
If a duplicator has cached data it will now replace the derivedFinal
mesh of objects with the cached version for drawing.
This is a compromise atm: It would be better to actually draw derived
meshes directly, so that we don't have to modify objects. Then we could
also have multiple different instances of the same orignal object
(in whatever way these might be defined). DNA Objects would then be
totally separate from duplis, but at this point the drawing and render
code makes this unfeasible.
The layout of the Alembic files resembles the DNA structure in Blender:
- On the top level (under the top/root node) there are Abc::Objects for
Blender ID datablocks (currently Object and Group)
- Objects store final data (DerivedMesh) and later simulation results
etc.
- Groups store their full duplilists for instancing. Currently there is
no recursive nesting of groups, since this would limit duplis to
dupligroups and exclude e.g. duplifaces.
On reading the duplilist gets reconstructed and stored in the DupliCache
for a duplicator empty (the group instance). DerivedMesh data is stored
in a hash table for each instanciated object and can later replace
finalDM in drawing and rendering.
Now the base types for readers/writers are not nominally forming the
interface any more (they may be removed entirely later). This makes
possible a cleaner init method directly in the Abc Writer/Reader
classes.
Further work may be required in this area.
This is more in line with how readers work in the Blender Alembic
implementation elsewhere.
Generally, readers are less persistent than writers: they are created
whenever cache results need to be updated (e.g. on frame changes) and
discarded afterward. Writers OTOH stay alive during the whole baking
job, since they keep the references to Alembic Writer instances and can
only be deleted once the writing for that part is done.
Note that the cache stores dupli matrices without the final parent
transform, since it only knows about the group itself. The duplicator
obmat is applied to the duplis after reading the cache.
Now we store duplilists entirely inside a single alembic object for the
group. This allows using all the generated duplis, which would be
difficult if the alembic file had to define all the possible recursive
dupli relations that Blender allows, beside straightforward Group duplis.
Uses the duplilist generated by Blender to define instances, instead of
recreating the group layout. This omits some information about actual
structure of the DNA, which might be useful later on. The main problem
is that the duplilist itself does not encode this, so it's a tradeoff
between either including the Group structure or omitting the other
dupli types, like face, vertex, particle duplis.
creation call.
This is executed *a lot* (even for simple things such as viewport
panning), so the code is probably not suitable in this form. At least
it could do a frame comparison to avoid unnecessary updates.
This is necessary for the current viewport drawing and rendering code,
which expected each dupli instance to represent a copy of data in the
DNA.
The code maps base-level objects in the cache to DNA Objects inside the
dupligroup by name. Only objects that can be found in the blend data
will be allowed for DupliObjects.
This is a placeholder for proper depsgraph integration. Eventually frame
changes and some other updates should rebuild dupligroup caches
automatically using the depsgraph. Until then this operator is a quick
way to test the IO from caches and the further drawing and rendering
(TODO).
BKE (DerivedMesh, particles, cloth).
The new cache implementation will be used for constructing dupli data
instead, bypassing the complexities of the modifier stack.
Conflicts:
source/blender/blenkernel/intern/cloth.c
source/blender/blenkernel/intern/particle.c
source/blender/blenkernel/intern/particle_system.c
Alembic caches.
This creates representations (Abc::Object) for Blender Object and Group
datablocks in the Alembic files and uses Alembic instancing to define
the dupligroup hierarchy. This leads to a relatively flat hierarchy in
Alembic files:
Top -> Object/Group -> DerivedMesh/Particles/Hair/Cloth/Smoke/...
The dupligroup structure can not be represented by a hierarchical
structure such as the Alembic object nesting, because of the
many-to-many relationship between objects and groups (a group can
contain multiple objects, multiple objects can instance the same group).
Instead we use the instancing feature of Alembic to represent
dupligroups. This is created in 2 stages to ensure all the main ID
blocks have been serialized before creating references.
This is not clearly documented for Alembic, but apparently properties
inside compounds still need to be name uniquely for the whole object.
This is somewhat involved for Blender's CustomData, because we have
5 different customdata elements for meshes (vert, edge, face, poly,
loop) and each of these can have the same types and multiple layers of
the same type ...
CustomData layers are pruned by the CDDM_copy function when they have
CD_FLAG_NOCOPY set. This is based on later modifiers in the stack, which
can specify that they require certain data layers - but the caching
modifier itself should store only what is needed by later modifiers.
It means we cannot easily keep a full copy of the DM in the cache
modifier to writing into caches later.
For now the hackish solution is to temporarily disable NOCOPY flags when
copying the DM. This is really not nice and needs a better solution.
This is a skeleton feature that provides a general way of storing
CustomData types. Currently only ORIGINDEX layers are implemented, the
code is designed to make extension easy.
Storing CustomData layers in Alembic is a bit involved because the
complex structs often used as customdata need to be de-interleaved for
Alembic into a set of POD (plain-old-datatype) array properties.
In addition the property names should be unique, so that mapping abc
properties back to customdata layers is safe. This works by using 2
levels of compound properties: the first level stored per CD type
properties, with a number of properties for each layer of this type,
using either a name or index (for unnamed layers). The internal
properties can then in turn be compounds, if structs need to be
serialized into PODs.
Abc property readers/writers are created dynamically for the CustomData
compounds. This is necessary because we don't know in advance what kind
of data layers a DerivedMesh or other CD user will have, and this can
change each frame in theory. Alembic is easier with state data schemes,
but using it this way is possible (if somewhat cumbersome).
This creates a string with information about all the objects and
properties contained within a (Alembic) archive, used by a cache
library.
The operator has 3 modes of presenting the info string:
- stdout, ie. printing to the terminal
- popup window (not very useful usually due to size limits and lack of
scrolling)
- clipboard copy
result read from the cache.
Mixing this with the output_dm used for writing leads to undefined
situations where the DM was released but should actually be passed on.
This designates a cache library to be used either for the viewport or
for renders. A "Render" cache library will evaluate modifiers with
render settings and a "Viewport" cache library will use viewport
(realtime) settings.
When reading the cache, the library will only be
used for the assigned purpose, i.e. a Render cache does not work for
viewport caching and vice-versa (although a cache can be baked for one
setting and then switched afterward).
Note that render results will never be visible in the realtime viewport
due to the way object evaluation is handled in Blender at this point
(render settings are only evaluated explicitly during renderer sync).
Conflicts:
source/blender/blenkernel/intern/particle_system.c
out of pointcache into blenkernel.
This is quite simple and repetitive and there is not need to have this
in the main pointcache/Alembic API. The code is mostly concerned with
logic of DNA data, so pointcache shouldn't have to deal with it.
The pointcache library is now pretty much independent from ID blocks and
should not be responsible for handling file paths. The path construction
is also fairly straightforward now compared to the old point cache
system, with only basic conversion of relative to absolute paths for
loading archive files.
python code to unify symbols.
This is necessary because the operator for adding new items (as opposed
to the enable/disable button) cannot be shown with the same checkbox
button. The UI template function can display a custom button for the
operator, so the look becomes less confusing.
This now appends a default extension based on the cache backend used.
At this point this is always Alembic (.abc) but would allow other
backend formats in the future.
In addition to the object name filtering, items in cache library groups
can now be filtered by type as well.
Existing items in the cache are always displayed, so as to not hide
important information (what gets stored in the cache). The filtering
is primarily a utility to simplify searching inside the group for things
that should be added to the cache.
This requires a better design and is not so easy to implement properly
within the limits of RNA definition. These collections don't physically
exist in the DNA, they are mainly utilities for looping over
//potential// items in a cache library. For now the python code has to
be adapted to only show valid items, until the RNA provides a good
solution.
This is also used during the bake process to avoid confusion: The read
flag gets disabled for the baking cachelib, so that objects don't try
to read cache data that is supposed to be generated.
CacheLibrary datablock has a generic unlink function now, but currently
nothing actually links to cache libs themselves, so it's empty. Still
good to keep this in mind for the future.
The `bf_pointcache_alembic` code is a separate library, to avoid
muddling up core code with alembic includes and preprocessor defines.
Alembic stuff only belongs strictly into alembic code and can be
disabled cleanly.
The `bf_pointcache` and `bf_pointcache_alembic` libraries had a circular
dependency, because the alembic implementation functions were called
directly. Now there is a "Factory" class to abstract the creation of
concrete implementations for readers and writers.
`bf_pointcache_alembic` defines this factory and is registered
//outside// of the core `bf_pointcache` lib, so there is no linker
circularity.
This was an artifact from the previous way of mapping non-0 start frame
to time 0.0. Now we start at times > 0.0 to match with the start frame.
Both ways are possible, can be changed later if needed.
Writers were always starting at time 0.0, which means that for start
frames > 1 the readers would always be off. Now match the writer start
frame to the actual Blender start frame.
cache library system.
The Cache modifier is now an optional "break point" of the modifier
stack:
- Without a cache modifier the stack works as before. Baking will write
the final stack result. After baking the cache replaces the whole
stack.
- With a cache modifier the stack result at the modifier's position is
stored. The cache is then applied as the output of that modifier,
skipping preceding modifiers. That way additional modifiers can be
applied on top of the cache.
- When using multiple cache modifiers, only the last (active) one will
be used, since all previous cache results would be discarded anyway.
This can happen if an object gets deleted or isn't loaded for some
reason. The item should just be ignored in that case and removed at the
next opportunity (cleanup function).
of constructing names internally.
This helps prevent name collisions and guarantees a consistent naming
scheme for putting multiple items in the same cache.
refactoring simpler.
Since the new approach is not tied to the old set of point cache data
types there is really no need to carry their empty husks around. Once
the new caching system is defined in detail we can add back whatever
makes sense.
Now instead of each reader/writer creating its own archive, the archive
is created by the caller in advance and passed as a constructor
argument. This means that multiple items can be stored together in the
same archive.
iterating over all objects eligible for caching in the group.
This allows for nested dupligroup instances as well. All objects that
are instantiated at least once by any group can be included in the
respective cache, but get represented only once because the cached data
is the same anyway.
subtype/index.
This omits possible instancing and recursion by dupli groups, but since
the data of instances is always the same in Blender at this point, there
is little need to take them into account for caching.
At some point in the future it may become desirable to store full dupli
hierarchies in the cache, but it doesn't make sense to try to design a
fully-fledged path descriptor for this hypothetical case now.
object group.
This is somewhat experimental, eventually we may want to link to Objects
instead, or allow multiple cache targets for the same cache, etc.
and files.
At it's core this is just a file path, but many different cache users
may refer to this, so having a dedicated ID block helps. It can be
compared to Image datablocks, which also primarily are used for data
on storage, but can be packed with the blend file, and carry some
additional information that would be cumbersome to keep sync'ed
otherwise.
The name 'CacheLibrary' deliberately resembles the 'Library' datablock:
just as a Library stores ID blocks in a physical file, a CacheLibrary
stores cached data (in Alembic HDF5/Ogawa or other formats).
Conflicts:
source/blender/blenkernel/BKE_pointcache.h
source/blender/blenkernel/intern/pointcache.c
source/blender/makesdna/DNA_pointcache_types.h
Conflicts:
source/blender/makesrna/intern/rna_main_api.c
When writing DerivedMesh data, the modifier result at the point of the
modifier will be used for writing to the cache. If this modifier is not
used the derivedFinal mesh is used instead.
The pointcache API is designed to keep the general concept of caching
separate from the concrete Alembic implementation. Other types of file
export/import would be possible, e.g. for OpenVDB data.
Adds Alembic as a dependency and build support in cmake and scons.
Also extends the install_deps.sh script with a temporary installation
procedure for the Alembic libraries. This is still very hackish and
needs to be improved.
This reverts commit 91d0f6f113.
Artists here seem to dislike the interface being stuck after a change to
modifiers, reverting until an interactive solution is coded.
**Warning: WIP!** Basic functionality works fine and there shouldn't be any crashes, however, if you occur issues, feel free to report them to me (not in the bug tracker!)
Some more effort is needed to get this ready for master, but I thought it would be nice as a little present for the Gooseberry-team (I heard some of you were requesting this?) and the ones using the Gooseberry-builds :)
Oh, and better not look at that code, it's ugly and a lot of changes are planned, I just wanted to get something working before getting into details.
screen.
Apparently the screen on the given file did not have a scene attached.
Not sure how this is possible exactly, but for now just guard against it
at load time by assigning default scene in that case.
It was only happening on 32bit platforms because of alignment
differences when allocating class.
Now got rid of copy of eigen matricies stored by value in the
residual block which solves aligment issues and should also
give some unmeasurable speedup.
This hit animators already, basically when using sound sync we can
hit negative frames. This happens because we always subtracted the full
range of the triple buffer size from the timing, even when buffers were
flushed.
Also, old code read the offset from the offset of the reader. The
problem here, is that due to threading there is a time offset between
the when this offset is set and when it is offloaded to the buffers,
which means that we could get quite some variance between time
reporting.
Now sounds keep a private byte offset which is incremented right before
invalidating old buffers. This should make the combination of OpenAL
time report + byte offset more accurate. For even more accuracy we might
spinlock while updating those values but for now left it as is for fear
of the lock interfering with frame update performance. We can try to be
smarter here, storing old value while update is happening, and use
trylock and the old values if it fails but for now commit the simple
version.
The issue was caused by recent DM to mesh conversion which was taking ownership,
and it was failing if there are any referenced layers in the custom data.
Now disable passing ownership if there are any referenced layers.
The idea is pretty simple: instead of making temporary copy of all the
related custom data layers just pass the ownership from the DM to the
mesh.
This is really handy in cases when you've got DM which you need to
convert to Mesh datablock and wouldn't need that DM after conversion
anyway.
Foe example, render database conversion, exporters and even Modifier
Apply will benefit from this option.
Reviewers: campbellbarton
Differential Revision: https://developer.blender.org/D1127
The purpose of this change is to add extra possibility to render engines and
export scripts to reduce peak memory footprint during their operation.
This new argument should be used with care since it'll leave mesh in not really
compatible with blender format, but it's ok to be used on temp meshes.
Unfortunately, it's hard to get scene where it'll show huge benefit because
in my tests with cycles peak memory is reached in MEM_printmemlist_stats().
However, in the file with sintel dragon it gives around 1gig of memory benefit
after removing the polys which would allow other heavy to compute stuff such as
hair (or even pointiness calculation) to not be a peak memory usage.
In any case, this change is nice to have IMO, and only means more parts of
scene export code should be optimized memory-wise.
Reviewers: campbellbarton
Differential Revision: https://developer.blender.org/D1125
Issue this commit is addressed to is that particle system and particle modifier
will contain caches once derived mesh was requested and this cached data will
never be freed.
This could easily lead to unwanted memory peaks during synchronization stage
of rendering.
The idea is to have RNA function in object which would free caches which can't
be freed otherwise. This function is not intended to deal with derived final
since it might be used by other objects (for example by object with boolean
modifier).
This cache freeing is only happening in the background rendering and locked
interface rendering.
From quick tests with victor file this change reduces peak memory usage by
command line rendering by around 6% (1780MB vs. 1883MB). For rendering from
the interface it's about 12% (1763MB vs. 1998MB).
Reviewers: campbellbarton, lukastoenne
Differential Revision: https://developer.blender.org/D1121
for clumping instead of deformed location.
The orco location must be used for roughness to ensure a stable shape,
but for moving child keys toward the parent (clumping) the deformed
location must be used.
This randomisation was using the deformed parent coordinates for
calculating noise vectors, which causes unwanted movement as the parent
hair deforms. Instead the `orco` coordinates must be used for all noise
vectors, since these are from the undeformed mesh.
Rationale for this feature goes like this:
In meshes the influence of shape keys can be limited to certain vertex
groups. This allows shapes to be applied selectively on parts of the
mesh and possibly even be animated by changing vertex group weights over
time.
With hair shape keys there is no equivalent feature to vertex groups
(defining a vertex group on hair keys would be rather tedious anyway).
It would be possible to use the emitter mesh vgroups to assign a
per-strand blending weight, but since hairs usually are much more dense
than mesh vertices this would sacrifice accuracy.
A better option is to allow textures to influence the hair shape key
blending. For this purpose there is now a new texture influence.
A shape key name needs to be assigned to the MTex in addition to a
factor. It will then act as a multiplier for the shape key weight,
i.e. the base shapekey value still works as an overall control.
Draw motionpaths after scene. They are not really XRays since they don't
require any depth info so add separate list for them. Feature could be a
little more polished to avoid too many state changes but for now just
commit something that works (tm)
problematic (still!)
It seems due to floating point precision issues we have to account for
even more cases.
Added colinear check for one more triangle edge-vertex and assumed that
if no collision test is found then triangle is completely inside box.
Such cases are mostly from float precision not catching triangle just
outside bucket. Now tests are much better for simple tests (paint/flood
fill cube from ortho view, paint sphere), however there are still some
rare cases of stray pixels.
By default a surface-based force will push things away from the surface
in both directions, regardless of whether a point is "inside" or
"outside" (judging by the surface normal). The new option makes a force
field always push things away in the direction of the normal, so that
it becomes less likely to get points "trapped" inside a mesh object.
building the BVH.
A long long time ago (rB3816554cbc1a40dc5199c8e56e45817ec09128d5) it
was coded such that edges would be used instead of faces for surface
distance calculation. This is pretty much never what you actually want.
modifiers, for use in shaders.
The particle instance modifier can now store 2 custom data layers:
- Index: the integer index of the particle
- Value: a randomized floating point number for shader variation
These layers have user-defined names, so multiple particle instance
modifiers can be used without overwriting customdata layers. In Cycles
the data can be accessed using an Attribute node with the same names.
This allows using the same particle system for multiple objects without
creating too much repetitiveness. Each instance object can select a
range of the particles to actually use for instancing (default 1.0 means
all particles are used). To further avoid overlap with multiple
instancing objects, the offset value can be used to make each system
use a specific range of particles.
This commit adds a few generalizations to the VBO
code so that modifiers can create and populate their own GPU objects.
The VBO code originally supported CDDerivedMesh only. The design moves slightly
towards the viewport refactor where the rendering system requests data from the
modifiers.
In this commit only basic support for vertices and normals is provided and
some features from blender's VBO system, suchs as mapping to original faces,
unique element indices for vertices and loose vertex/edge support are missing.
Also, the quick navigation feature of the subsurf modifier won't be supported
for now.
What we do have is full support for solid shading with multiple materials,
flat/smooth shading and a big performance boost.
It's a bit messy, but that is to be expected: all of the areas involved
(particles, shapekeys, depsgraph, drivers) are badly designed and
supposed to get major refactoring ...
Auto View automatically adjusts the view based on selection, so that the view is
always focused on the current selection.
A checkbox in the header is used to access it and it works for the following
selection methods: Toggle All, Border, Circle, Lasso, Left, Right, More, Less,
Linked, Column (so all except of single selection, in which this can be a bit
annoying)
Reviewed by @Aligorith (thanks for that :) )
Only recompute if cost is below -FLT_EPSILON, we can get cases where both cases generate
very tiny negative costs (see 'Cylinder.004' mesh in .blend attached to report).
space the particle data should be interpreted in.
By default the space will now be `Local`, meaning that copies of the
mesh are made with the offset of the respective particle in the particle
object's local space, rather than using the world space offset of the
particle //inside the modified object space//. This behavior is much
more intuitive and consistent with true duplicators, such as face duplis.
Old files will still have `World` setting, so existing blend files are
not changed.
This is obviously total madness, this feature is totally unusable when
the coder is not sitting next to you ... But so are the rest of particle
settings, the only solution is a future node system.
The internal cloth modifier effector weights get replaced temporarily
to make the cloth sim use the particle weight settings instead. But
the particle sim was not putting back the original weights, which can be
non-NULL in case the cloth sim allocated these already. Messy design ...
between stroke and single-add mode.
This was requested especially for use with tablets. With a pen it is
difficult to set a precise point and the tool ends up making multiple
hairs close together all the time. Disabling the stroke option helps
adding individual hairs.
Avoid opening the file when doing uncached reading because ffmpeg takes
quite a long time to read the first frame. Instead, avi jpeg is almost
instantaneous here.
This will leave the anim struct without an Imbuf and that can cause
other unexpected issues elsewhere so commiting on gooseberry first
to try.
Speedup is quite impressive though.
Needless to say, code here quickly becomes a mess and the proxy system
should be made saner but for now just commit to keep things working at
the studio.
This is incompatible with particle data structures in their current form.
Hull drawing requires sorting child particles based on the distance from
their primary parent. However, this changes the order of children, which
is the main method of generating random numbers for them. In the
viewport this is not a problem, but when rendering the children are
constantly recreated, using the respective deformed emitter mesh each
time. This leads to changing child orders when using the convex hull
sorting, and therefore different randomisation values.
To properly implement child hull drawing we would have to generate a
stable parent-child offset metric as well as avoiding any resorting in
the actual data arrays. This in turn requires terribly inefficient
drawing iteration, which could become a bottleneck by itself even before
taking cache coherence or OpenGL optimization requirements into account
(collecting child data into a dedicated buffer for drawing).
Failed proxies will now attempt to fetch a smaller proxy first before
fetching the full resolution. This might allow us to see if we are
hitting a bandwidth issue (due to high res) or a file query issue (due
to more file queries)
to the hair dynamics input DM.
Also this calculation has to happen before caching paths, otherwise
there is a 1-update lag because parent paths still use old values.
and when switching the active key during edit mode.
This is different from how shape key editing works on meshes: there the
edit data (BMEditMesh) stores customdata layers for shape keys, then
writes them back to the mesh. The hair edit mode is a lot more messy and
confusing, it has to update the base data immeditately (with potential
consequences for undo ...)
The code was assuming that child 0 is always valid, but in fact has to
be treated like all others that can be disable due to preview percentage,
virtual parents, etc.
The current algorithm generates a triangle strip to fill the end of
each child bundle. This is not quite ideal, because even though the
base child groups are constructed to be convex, the resulting child
paths can become concave again by clumping, roughness, hair dynamics
etc.. This can create face inversion as well as ugly shading artifacts,
so a nicer algorithm may be desirable.
child hulls.
Note that the perpendicular direction around the hair bundles is not
smooth-shaded. Smooth shading doesn't make as much sense there because
large angles are common in this direction and give awkward shading
results.
This was used as part of the "sim preview" feature, where some amount of
vertices were tagged as disabled in the particle system. Due to the
mind twisting complexity of using the nested cloth modifier to simulate
hair strands indirectly it became necessary to still store all the
vertices, but then disable them again on the solver level ... If this
ever gets reimplemented it must be done in a sane way, avoiding the
cloth step altogether.
mode.
This was caused by variation of the number of keys on child hairs due
to shortening of hair curves based on euclidian distances. The other
kink modes also shorten hairs, but use the parametric distance instead,
which does not vary with deformation of hairs.
By default this now copies from one object's local space to another
object's local space (instead of the previous world space). This is
more useful when transferring particles between objects, because it
doesn't require moving objects on top of each other, as long as they
have similar shapes.
another, including edit data (grooming).
This uses basically the same method as the existing connect/disconnect
feature. The main difference is that it allows working with multiple
objects and transferring the //particle/hair data// instead of the
//mesh// data (which is what connect/disconnect expects). This is a much
more realistic workflow when rigging, topology etc. changes and
groomed hair has to be transferred to the changed model.
This is BAD code, but the particle kinking does not make it easy to
write a non-local modifier that requires neighboring positions,
curvature, etc. The feature is needed for Gooseberry.
This adds another level of clumping on child hairs. When enabled, child
hairs chose a secondary clumping target using a Voronoi pattern. This
adds visual detail on a smaller scale, which is useful particularly when
the number of parents is relatively small.
Natural fibres behave in a similar way when they become sticky and
intertwined. Hairs close to each other form a first twisted strand, then
combine into larger strands. Similar features can be found in ropes:
http://en.wikipedia.org/wiki/Hair_twistshttp://en.wikipedia.org/wiki/Rope
Scope update is very slow for high resolutions, and currently blocks
the UI thread(!). This is especially terrible in paint modes, where
each stroke causes a scope update and unacceptable freezing.
The scopes update method tries to avoid this somewhat by skipping if the
toolbar is disabled, but this doesn't help when painting where brush
tools etc. are frequently needed. It's also a bad-level poll, with the
core system accessing a UI element.
Eventually scope updates should become a low-priority background job,
as well as becoming threaded. Until then this polling provides a usable
workaround to the most outrageous cases.
This is an alternative method to the current fixed function with a
clump factor and "shape" parameter. This function is quite limited and
does not give the desired result in many cases (e.g. long, parallel
rasta strands are problematic). So rather than trying to add more
parameters there is now a fully user-defined optional curve for setting
the tapering shape.
This contains a few pieces of code for a future "modifier" system that
would allow more flexible combination of effects. Eventually a node
system is the way to go, but the current code makes that impossible.
to prevent double-freeing/invalid mem access.
This can happen with the "virtual parents" feature, which generates both
parent and child paths. Each task free function also freed the shared
context, leading to double freeing.
and graph editor.
This was a tricky commit that was not so straightforward to make work.
The information for bones is not easy to come by in the animation curves,
however we do have some string manipulation tricks to make it happen.
For now committing to gooseberry branch for testing, it will be ported
to master after most usual use cases have been confirmed as working.
(Current test with all rotation modes and translation seems to work, but
Not sure how well this will hold up with drivers etc)
Cloth data is used both for hair and actual cloth, which makes things
really difficult. The face number was used for distinguishing the two
types (no faces == hair mesh), but the extra hair data necessary for
hair sim is generated by particles and not available for edge-only cloth
meshes. This really needs to be sanitized ...
Now simply add a flag to the armature modifier to use facemaps. Facemaps
on the mesh object with the same name as the armature bones will get
displayed as widgets.
This is necessary because the hair dynamics settings are not part of the
ParticleSettings datablock, but part of the convoluted cloth modifier
inside the particle system struct. In the future this will be recoded
properly, but in the meantime presets provide a simple an unobtrusive
way to have reusable dynamics settings for hair.
approach does not work very well.
Using a cross section estimate still causes large oscillations due to
varying hair force based on angles. It also requires a sensible hair
thickness value (particle radius) which is difficult to control and
visualize at this point.
The new model is based purely on per-vertex forces, which seems to be
much more stable. It's also somewhat justified by the fact that each
hair vertex represents a certain mass.
* Test display code that displays the active facemap. Will not work on
subsurf modifier yet (crash)
* Fix loading of files with facemaps
* Facemap data now reside on polys instead of tessfaces.
The previous calculation was modulated with the angle between the wind
direction and the segments, which leads to very oscillating behavior.
Now the formula includes an estimate for the geometric cross section
of a hair segment based on the incident angle and the hair thickness
(currently just the particle size). This gives a more stable behavior
and more realistic response to wind.
This commit adds a few generalizations to the VBO
code so that modifiers can create and populate their own GPU objects.
The VBO code originally supported CDDerivedMesh only. The design moves
slightly towards the viewport refactor where the rendering system
requests data from modifiers.
What we do have is support for solid shading with multiple
materials, flat/smooth shading and a big performance boost.
Performance could
In this commit only basic support for vertices and normals is provided
and some features from blender's VBO system, such as mapping to
original faces, unique element indices for vertices and loose vertex/
and can be added later. The one feature that is missing now is the quick
navigation feature of the multires modifier (which uses the same code).
- Why this commit is made on the widget branch -
Facemap widgets need to avoid drawing the whole mesh when we do
collision detection on them. For subsurf drawing we need to iterate
through the whole mesh every time. What we need instead is sort
indexed elemet drawing according to the facemap each face belongs to.
This screams VBOs but since I was going to add that, I thought that
I could push it a bit further and add proper solid shading support.
This commit adds a few generalizations to the VBO
code so that modifiers can create and populate their own GPU objects.
The VBO code originally supported CDDerivedMesh only. The design moves
slightly towards the viewport refactor where the rendering system
requests data from modifiers.
In this commit only basic support for vertices and normals is provided
and some features from blender's VBO system, such as mapping to
original faces, unique element indices for vertices and loose vertex/
and can be added later. The one feature that is missing now is the quick
navigation feature of the multires modifier (which uses the same code).
What we do have is full support for solid shading with multiple
materials, flat/smooth shading and a big performance boost.
Performance could
- Why this commit is made on the widget branch -
Facemap widgets need to avoid drawing the whole mesh when we do
collision detection on them. For subsurf drawing we need to iterate
through the whole mesh every time. What we need instead is sort
indexed elemet drawing according to the facemap each face belongs to.
This screams VBOs but since I was going to add that, I thought that
I could push it a bit further and add proper solid shading support.
This module will contain mirrored functions for calculating and applying
weights for points on a mesh. This includes barycentric and UV weighting
and possibly more advanced global weighting such as harmonic weights.
The naming should follow this scheme:
<type>_{2d,3d}_{calc,apply}
e.g.
poly_2d_calc
poly_2d_apply
uv_3d_calc
...
Reviewers: campbellbarton
Differential Revision: https://developer.blender.org/D939
A bone using a facemap will not be displayed at all, rather it will use
the facemap of the mesh as an interaction area. The facemap still does
nothing since it's not yet hooked up to the customdata and widget code.
That will come next.
They are set when a highlighted widget intersection is detected and on
area level.
There's a discussion about using owners and a stack or array for cursors
but that needs some more thought and design.
Due to this we -obviously- rename this to overdrop
I am not sure if others would agree here, but it's pretty safe to do
this on a branch first. Rationale is that it's much nicer to work on
full screen with this.
backdrop is now functional.
The widget could communicate with the sequencer properties directly, but
here we set it to control the operator properties as a demonstration.
After some minor stress testing, time to give this to gooseberry team.
Areas support more than one widgetmap - will be useful to partition area
in different transform regions like data, pixel, 3D (will be done in a
separate refactor).
Also get rid of the context widget hack in favour of adding the
widgetmap handler to the operator handler itself, so handling will
be unified when the widget controls a property or spawns an operator
Handle events for widgetmap first when and pass to operator when
operator is active.
This is still a pretty confusing design, working on a simpler one now.
This commit makes it possible to use scenes as a kind of
multi-user metastrip (with their own time).
Currently this supports rendering & drawing nested strips,
but no convenient way to tab-enter into a scene strip.
* Minor cleanup - propname does not need to be stored anymore.
* Code to support modal widgetmap registration for operators - still
untested, but will be tested soon on sequencer cage widget
* Widgets take parameters to initialize property slots that are used for
feedback or control.
Cage now uses this to feed offset/scale to different properties.
* Initialize common properties during widget registration.
remove and add widgetgroup types from the system.
Start operator that will control sequencer backdrop. Architecture here
still needs a little work so good compatibility with Add-ons can be
ensured.
commit and operators to set faces in a group in edit mode.
Face maps are groupings of faces, similar to vertex groups, however,
each face can only belong to one face map.
They will be used for widget interaction, but there will possibly be
more uses for them in the future.
Code needs some cleanup still here, will apply as work is being done.
There is some code here for object mode interaction but it hasn't been
tested yet. This will probably be done with the widgets themselves.
The file wasn't being comiling by CMake, remove it from SCons compilation as well.
Not sure if the same is required in original branch, maybe it'll be redone anyway.
For now let's make it so gooseberry branch is compiling nicely on the buildbot.
transform the x direction of the backdrop in sequencer when a viewer
node is active.
There are still some issues with property transform not being a proper
operator, but we can fix that easily.
To make full 2D transform work we need positions stored in one property.
* Get rid of invalid flag (we avoid drawing widgets by dereferencing RNA
now so it should be OK)
* Add intersect function for 2D widgets (still needs correct mapping to
be any useful though)
A stupid hack is needed here, changing the way the factor is applied to
angular bending springs. In cloth sim the bending factor of individual
springs is applied as a mix value between the bending stiffness and a
max value, but this max value isn't even used in hair sim so that
approach becomes useless.
This helps to create some variation in a hair system, which can
otherwise become very uniform and boring. It's yet another confusing
setting in a system that should have been nodified, but only option for
now (broken windows ...)
Fix interaction when pivot is beside the camera. basically we now do all
calculations in 3D space and we do not scale correct the offset in 3D -
this creates a nasty dependency loop between drawing and calculation for
widgets bound to properties - ie offset depends on scale but scale
depends on screen position - ie offset.
Also added an extra callback to get the final position of the widget in
3d space and use that to calculate the scale. This takes care of
bringing a close to the camera widget to the background and the widget
keeping its initial size. The final position can be different from the
initial position, especially when the widget is offset from the original
position.
framing method instead of the Frenet frame.
The Frenet frame is very succeptible to sudden twists along straight
sections of a curve where the second derivative (curvature) becomes 0.
We now use plane/line intersection which seems to work quite well and
agrees to great extent with the transform system as well. There still
some small discrepancy but may also be related to scaling.
to support multiple hash identifiers.
Using explicit hashing functions for every sim debug call defeats the
purpose of having a quick feedback system. Now this can be done simply
by passing an arbitrary number of hash inputs (integers) at the end of
the function calls, which are then combined by a system of variadic
macros (based on the ELEM feature). Up to 8 identifiers are supported
currently, but more could be added easily if needed.
solver input and output.
This uses the central difference method (instead of combined forward/
backward difference), which makes it easier to correctly account for
grid borders.
samples.
This is just an intermediate method to make sure the density is valid.
Eventually the closest-point method should be used, but for testing
the poisson solver this is easier to debug.
This allows setting a target density which the fluid simulation will
take into account as an additional term in the pressure Poisson
equation. Based on two papers
"Detail Preserving Continuum Simulation of Straight Hair" (McAdams et al. 2009)
and
"Two-way Coupled SPH and Particle Level Set Fluid Simulation" (Losasso et al. 2008)
Currently the target pressure is specified directly, but it will be
a lot more convenient to define this in terms of a geometric value such
as "number of hairs per area" (combined with hair "thickness").
It may be better to use transform code for widgets but this will cause
nested operators for widget/operator and needs some consideration.
For transform e.g. we would have one transform operator taking care of
transformation of the widget, then feeding this back to regular object
transform.
Now widgetmaps get created and destroyed with the area. Not sure if it's
the best design but it avoids too many creations and recreations.
arrow offset now calculated at property binding time - no RNA access
during interaction means no chance of crash during undo.
There are several more or less new customdata layers that currently cannot be accessed via Python (or some are exposed via BMesh API but not via Mesh API). This patch aims to expose one of those layers - CD_PAINT_MASK.
It'd be pretty useful for existing and future addons targeting sculpt workflow. Currently to get some access to the mask we employ a hackish approach via hiding/revealing masked vertices, this adds mode switches and doesn't allow to get actual mask values which could be useful if converted into vertex group weights for later use in e.g. modifiers. With this patch we'd be able to access mask data directly.
Reviewers: campbellbarton
Reviewed By: campbellbarton
Subscribers: radcapricorn
Projects: #bf_blender
Differential Revision: https://developer.blender.org/D782
on the grid.
This uses the Eigen conjugate-gradient solver to solve the implicit
Poisson equation for the pressure Laplacian:
div(grad(p)) = div(v)
As described in "Detail Preserving Continuum Simulation of Straight Hair"
(McAdams, Selle, 2009).
To make this work, we need separate type/instance for the widgets. This
is a bit ugly but it is necessary if we want widgets on each editor to
depend of per editor-options or visibility state.
This is a bit more awkward for artists to use, but necessary for
a stable solution of the hair continuum calculation. The grid size is
defined by the user, the extent of the grid is then calculated based on
the hair geometry. A hard upper limit prevents bad memory allocation
in case too small values are entered.
This is a leftover from previous approach of hair collisions (with
insufficient results). The hair volumetrics actually implements
"collision" with solid objects as well, but uses a Neumann boundary
condition on the main grid for this purpose.
This is based on the paper
"Detail Preserving Continuum Simulation of Straight Hair"
(McAdams, Selle, Ward, 2009)
The main difference is that hair line segments are used rather than only
rasterizing velocity at the vertices. This gives a much better coverage
of the hair volume grid, otherwise gaps can be produced at smaller grid
cell sizes and the distribution is uneven along the hair curve.
The algorithm for rasterizing is a variation of Bresenham's algorithm
extended onto 3D grids.
Still pretty much exploring the best way to move here but currently this
works by wrapping objects in RNA pointers, pretty much like buttons do.
Also modified the arrow widget for lamps to use the new code. The new
"unmbrella" widget works now as expected for lamps - of course fine
tuning is also needed.
* Add gpu options for depth of field to camera - still inactive.
* GPUFXOptions now passed to the compositing system startup
so users can swap options if they wish to
This commit changes read-write data again, people should reset their
values again (sorry for that but this is still WIP)
* Add gpu options for depth of field to camera - still inactive.
* GPUFXOptions now passed to the compositing system startup
so users can swap options if they wish to
This commit changes read-write data again, people should reset their
values again (sorry for that but this is still WIP)
This is working mostly from the 3D viewport currently, rendering from
the render buttons or the sequencer will not use the FX yet. Still it's
a solid step towards that direction. Also moved options out of the v3d
struct. Old options will be lost and people may get some warnings,
however simply enableing and disabling one of the compositing settings
will bring the controls back.
Algorithm used is now a full implementation of
"Practical Post-Process depth of field", presented here [1],
with a few modifications as to how circle of confusion is
applied at the final pass.
[1] http://http.developer.nvidia.com/GPUGems3/gpugems3_ch28.html
solver step.
Calculating forces and jacobians from linearly interpolated grid values
is problematic due to discontinuities at the grid boundaries. The new
approach of modifying velocities after the backward euler solver step
was suggested in a newer paper
"Detail Preserving Continuum Simulation of Straight Hair"
(McAdams, Selle 2009)
more intuitive.
Also removed a couple of unused or useless features from the UI:
* collider friction is unused and replaced in favor of true collision
* spring damping refers to structural springs (stretch), which is
not noticable in hair due to extreme stiffness atm.
* pressure factors are not sure since this feature is too unstable atm.
Interpolating hairs in a meaningful way is a quite difficult problem.
It works ok-ish for child hairs as long as they don't move, but with
motion the direction of interpolated hairs can become quite nonsensical
quickly.
Probably a better way to create simulation previews is to limit
simulation to a particular well-defined area (like render preview
borders), but run it in full detail in that area. The error from
omitting some interaction should still be much less than orientation
errors from interpolation.
easier.
This code is badly broken and needs to be replaced, but at least having
a workable code structure might help with quick hacks to fix the worst
cases.
shape instead of a brush tool.
The brush cutting tool for hair, while useful, is not very accurate and
often requires rotating the model constantly to get the right trimming
on every side. This makes adjustments to a hair shape a very tedious
process.
On the other hand, making proxy meshes for hair shapes is a common
workflow. The new operator allows using such rough meshes as boundaries
for hair. All hairs that are outside the shape mesh are removed, while
those cutting it at some length are shortened accordingly.
The operator can be accessed in the particle edit mode toolbar via the
"Shape Cut" button. The "Shape Object" must be set first and stays
selected as a tool setting for repeatedly applying the shape.
more intuitive.
Also removed a couple of unused or useless features from the UI:
* collider friction is unused and replaced in favor of true collision
* spring damping refers to structural springs (stretch), which is
not noticable in hair due to extreme stiffness atm.
* pressure factors are not sure since this feature is too unstable atm.
Interpolating hairs in a meaningful way is a quite difficult problem.
It works ok-ish for child hairs as long as they don't move, but with
motion the direction of interpolated hairs can become quite nonsensical
quickly.
Probably a better way to create simulation previews is to limit
simulation to a particular well-defined area (like render preview
borders), but run it in full detail in that area. The error from
omitting some interaction should still be much less than orientation
errors from interpolation.
* Scons builds correctly
* Separate vertex shader file for DOF, will make handling main easier
* Downsample color buffer + blur it. Circle of confusion is calculated
from zplane instead of length of distance from camera.
* Cleanup compositing buffers better when not needed.
* Support passes for the dof effect through defines in main - easy
solution to allow not having too many files for one shader effect.
easier.
This code is badly broken and needs to be replaced, but at least having
a workable code structure might help with quick hacks to fix the worst
cases.
Issue here was position reconstruction could use depths from pixels off
the initial position. Using linear filtering here eliminates the issue.
Usually this is not correct however given that for depth discontinuities
we will get different depths anyway, the cases where we get smooth
interpolation of depths helps a lot in image quality.
Basically change the way SSAO samples the screen by using a circular
filter instead. This is inspired by HBAO though we still don't use this.
The quality settings change the number and density of samples. We can
definitely improve things here though.
We also jitter the sampling locations per pixel. Generally this adds a
kind of noise. Some banding is, unfortunately still apparent and small
distances will introduce noise. This can be fixed but I will have to see
if it can be done without much of a cost.
shape instead of a brush tool.
The brush cutting tool for hair, while useful, is not very accurate and
often requires rotating the model constantly to get the right trimming
on every side. This makes adjustments to a hair shape a very tedious
process.
On the other hand, making proxy meshes for hair shapes is a common
workflow. The new operator allows using such rough meshes as boundaries
for hair. All hairs that are outside the shape mesh are removed, while
those cutting it at some length are shortened accordingly.
The operator can be accessed in the particle edit mode toolbar via the
"Shape Cut" button. The "Shape Object" must be set first and stays
selected as a tool setting for repeatedly applying the shape.
explicit attenuation control (by using just max distance).
Also it now supports orthographic cameras properly. The maximum distance is
now defined in world space units so it should be slightly easier to understand
and uniform across perspective and orthographic cameras.
The optimizations can be generalized for orthographic cameras but the code is
more complex and the runtime advantage is questionable in that case
(in the end a matrix transform is 4 dot products which are not that terrible)
so commented out the code there for now.
This needed some adjustments from the formula I found on the article on
view space reconstruction, since OpenGL makes different assumptions about its
projection matrix.
SSAO does not work yet correctly under new model assumptions but we are going
to substitute with nice horizon based ambient occlusion.
* highlighted vs active widget.
Active widget takes all input and basically highjacks drawing of all
other widgets in the widgetmap.
* operator names for widgets. Now widgets will spawn operators based on
names that are passed on them. They will also modify a named property of
the operator and pass it on, after which operator can process it.
The sound system really needs better design for the sequencer and
patching it up now won't really help us in the long run.
Also the sequencer kept leaking file descriptors when preserving
the audio handlles on undo making the branch unusable on mac and
windows.
It's almost certain patching over this will lead to more trouble, better
handle it separately and keep the system working for now.
Kept threaded loading of waveforms since we control the file input
directly there and leads to nice speedup, but we still clear the whole
sound + the waveform on undo, which is pretty bad.
* Move lamp operators to a proper place
* Store a list of widgets to avoid polling too many times
* Fix wrong indices when widgetgroup was not used.
* Lamp widget now uses an arrow widget. This will be refined to make a
nice prototype for operator/widget interaction.
Avoid moving the 'from' pointer around in DNA. This way files stay back-
as well as forward-compatible. Only the additional type enum and
sub-index is stored in a new from_extra struct in shape keys now.
This generates a somewhat believable overall look for the hair system
by blending simulated hairs. For small number of hairs and small
preview ratios this can get quite inaccurate, but that's the tradeoff
for getting preview functionality ...
This is still terribly messy, especially because every change of the
particle system has to be piped through the dummy cloth modifier somehow.
The automatic caching system also tends to get in the way a lot; after
changing the preview factor one basically always has to start at frame 1
currently because the cloth modifier has to be reconstructed and forgets
about all caching.
* Add option for shaded/non shaded widgets
* Normalize arrow widget size to 1.0 so size is predictable. Probably
will use the same scheme for other widgets as well
format (vertices + normals + triangle vertex indices)
This will allow us to create widgets in blender instead of defining them
programmatically.
May also support facegroups for different colors in the future though
they must be somehow tied to the UI colors.
Especially if we have many widgets on screen, sorting them will be
difficult and for mesh-armature widgets it will be unavoidable if we
want to avoid tweaking "back" surfaces.
There is first code for display of an arrow widget. The manipulator will
use those when they are ready.
Basically the manipulator is now a WidgetGroup. WidgetGroups are a new entity and
they manage a group of related widgets. They should be responsible for state update,
drawing and polling of their widgets and can be bound to specific rules.
There is a big design plan on a whiteboard beside me, it will take a few
big commits still to take shape though. One thing at a time, I am first making
reusable arrow widgets that will allow us replace the translate widgets properly.
There are a few reusable widgets planned, more to come later.
distribution and path caching for child particles.
This gives a significant improvement of viewport playback performance
with higher child particle counts. Particles previously used their own
threads and had a rather high limit for threading. Also threading
apparently was disabled because only 1 thread was being used ...
This is not necessary: the implicit solver data can keep track instead
of how many off-diagonal matrix blocks are in use (provided the
allocation limit is calculated correctly). Every time a spring is
created it then simply increments this counter and uses the block index
locally - no need to store this persistently.
Without this the particle system only shows the actual non-simulated
hairs ("guide hairs") during edit mode. These hairs are used for goals
as well, so showing them in the regular viewport is pretty important.
Also the usual hair curves are interpolated along the entire length,
which makes it very difficult to see exact vertex positions, unless
using exact powers of 2 for the segment number and match the display
steps.
too.
Rationale - widgets might be useful to have even on rendered scenes -
we'll have to see about how this will work
Also use area initialization code to register region specific widgets once.
lala
The curl radius for children in interpolated mode was calculated using
the total offset from the parent particle. This leads to very large
radii when the distance is large due to sparse parents. Such behavior is
also very unrealistic because the curl radius is mostly constant and
defined by the material properties.
All the child hairs are roughly parallel by default. To simulate the
agglomeration of children into hair wisps the "flatness" parameter is
now used to clump them together.
This should use an "active" system, similar to buttons to detect if last
widget has changed and act accordingly. Currently, when the active
widget changes, there is no change in highlights.
Code that handles 3D object intersection via GPU selection. We might
want to use raycasting here, but leaving that for when we have it.
Manipulator code now uses this API to do intersection testing
Widgets use a similar notification system as operators. It might be
worth using WM_BREAK messages like the rest of the handlers. For now
this should do.
With the default 5 substeps the simulation can otherwise still become
unstable. This is just a preliminary measure anyway until the length
variance can be fixed properly.
This is more involved than using simple straight bending targets
constructed from the neighboring segments, but necessary for restoring
groomed rest shapes.
The targets are defined by parallel-transporting a coordinate frame
along the hair, which smoothly rotates to avoid sudden twisting (Frenet
frame problem). The rest positions of hair vertices defines the target
vectors relative to the frame. In the deformed motion state the frame
is then recalculated and the targets constructed in world/root space.
This commit moves sound loading out of library linking. The approach
chosen here is to do lazy initialization by basically validating the
sound before attaching to the scene.
Loading the sound buffer requires a valid Main pointer, which means we
have to pass this around in many places. We might also consider caching
the waveforms in this way too, but for now we're still using the
threaded update.
We'll have to test this somewhat to see if it behaves well..There are
corner cases which might not be covered. Sounds are muted if we undo
during an animation, but this bug existed in master as well.
Sound loading can take too much so move it to a job and continue. This makes
interaction much better. A similar system should be usable for movie previews.
derivatives for stabilization.
The bending forces are based on a simplified torsion model where each
neighboring point of a vertex creates a force toward a local goal. This
can be extended later by defining the goals in a local curve frame, so
that natural hair shapes other than perfectly straight hair are
supported.
Calculating the jacobians for the bending forces analytically proved
quite difficult and doesn't work yet, so the fallback method for now
is a straightforward finite difference method. This works very well and
is not too costly. Even the original paper ("Artistic Simulation of
Curly Hair") suggests this approach.
This returns a general status (success/no-convergence/other) along with
basic statistics (min/max/average) for the error value and the number
of iterations. It allows some general estimation of the simulation
quality and detection of critical settings that could become a problem.
Better visualization and extended feedback can follow later.
waveform display.
Basically, we store the waveform. This is not really recommended but
until we have nice threaded creation for the strips that doesn't block
the interface it's a nice solution for gooseverry.
May be wise to limit the undo memory for people who use that because
basically each operation will store a copy of the waveform in the file.
This makes the bending a truely local effect. Eventually target
directions should be based in a local coordinate frame that gets
parallel transported along the curve. This will allow non-straight
rest shapes for hairs as well as supporting twist forces. However,
calculating locally transformed spring forces is more complicated.
This commit has first WIP code for widgets API.
Generally widgets should be registered similar to dropboxes, that is,
any code can query for a widgetmap for a certain space and area type
and the window manager will take care of initializing the handlers
automatically.
The owner will be able remove and readd widgets to a certain widgetmap
dynamically. Generally owners should cleanup their widgets though initial code
cleans up leftover widgets automatically.
All this is the theory still, some parts are in that commit, more to come
later, but it's a solid base to build from for an initial commit.
These are much better suited for creating stiff hair. The previous
bending springs are based on "push" type spring along the hypothenuse
of 3 hair vertices. This sort of spring requires a very large force
in the direction of the spring for any angular effect, and is still
unstable in the equilibrium.
The new bending spring model is based on "target" vectors defined in a
local hair frame, which generates a force perpendicular to the hair
segment. For further details see
"Artistic Simulation of Curly Hair" (Pixar technical memo #12-03a)
or
"A Mass Spring Model for Hair Simulation" (Selle, Lentine, Fedkiw 2008)
Currently the implementation uses a single root frame that is not yet
propagated along the hair, so the resulting rest shape is not very
natural. Also damping and derivatives are still missing.
single transform matrix.
Dynamic properties of the transformation are only needed during the
setup phase when they should be read from external data (hair system
roots) and generate fictitious forces on each point.
This is part of the original method from "Volumetric Methods for
Simulation and Rendering of Hair". The current filter is a simple box
filter. Other energy-preserving filters such as gaussian filtering
can be implemented later.
The filter size is currently given as a cell count. This is not ideal,
rather it should use a geometrical length value, but this is too
abstract for proper artistical use. Eventually defining the whole grid
in terms of spatial size might work better (possibly using an external
object).
at a the margin distance ("outer" softbody margin).
This has to be clamped arbitrarily unfortunately, otherwise the
repulsion force can add too much energy into the system. A factor of
4 * restitution impulse seems to give good results for now, this can
be refined later on if necessary.
This is now also decoupled from the internal solver data. The grid is
created as an opaque structure, filled with vertex or collider data
(todo), and then forces can be calculated by interpolating the grid at
random locations. These forces and derivatives are then fed into the
solver.
The hair solver needs sane input to converge within reasonable time
steps. In particular the spring lengths must not be too difference
(factor 0.01..100 or so max, this is comparable to rigid body simulation
of vastly different masses, which is also unstable).
The basic hair system generate strands with equally spaced points, which
is good solver material. However, the hair edit operators, specifically
the cutting tool, can move points along the strands, creating tightly
packed hair points. This puts the solver under enormous stress and
causes the "explosions" observed already during the Sintel project.
The simple solution for now is to exclude very short hairs from the
simulation. Later the cutting tool should be modified such that it
keeps the segments roughly at the same length and throws away vertices
when the hair gets too short (same goes for the extension tool).
The hair system should have a general mechanism for making sure that
situations such as this don't occur. This will have to be a design
consideration for replacements in any future hair system.
Also avoid recreating the framebuffers and gpu/color textures each
frame.
Happiness :)
There are still some glithes when scaling the areas, I'll look at those
next.
* Expose attenuation value - allows to change influence of far objects
* Change influence of far objects to quadratic, eliminates some extreme
fringing from far occluding surfaces.
This works by using the calculated view space normal and accumulating
coverage of a certain area by nearby pixels. There are two sliders to
control the effect:
* Scale controls the area around each pixel that the shader "collides"
against
* Darkening scales the occlusion effect.
The effect works, but due to the way the normals are calculated, the
normals are never smooth shaded (that would require a separate render
target to store them) and the edges or polygons can be too apparent.
This is not really fixable at the moment unless we move to deferred
pipeline.
The FX system is stll not well optimized and rendering does not always
work correctly, but it's good to have this out for people to play with.
moving hair root reference frames.
This calculates Euler, Coriolis and Centrifugal forces which result
from describing hair in a moving reference frame.
http://en.wikipedia.org/wiki/Fictitious_force
frames.
These forces don't have to be calculated for each individual
contribution. Rather they can be split off and be calculated on top of
the basic force vector rotation (todo).
There are currently 3 types of springs: basic linear springs, goal
springs toward a fixed global target (not recommended, but works) and
bending springs.
These are agnostic to the specific spring definition in the cloth system
so hair systems can use the same API without converting everything to
cloth first.
code.
The implicit solver itself should remain agnostic to the specifics of
the Blender data (cloth vs. hair). This way we could avoid the bloated
data conversion chain from particles/hair to derived mesh to cloth
modifier to implicit solver data and back. Every step in this chain adds
overhead as well as rounding errors and a possibility for bugs, not to
speak of making the code horribly complicated.
The new subfolder is named "physics" since it should be the start of a
somewhat "unified" physics systems combining all the various solvers in
the same place and managing things like synchronized time steps.
This commit introduces offscreen rendering for the 3D viewport.
There is test code that calculates depth and normal data
in screen space.
Currently just DOF is supported with a few parameters to control the
effect
This code recreates the framebuffer and texture objects every frame
which will make it -slow-. Use at your own risk.
handle only one collision contact at a time.
Collision still randomly explodes, even with differing results on the
same file. This could indicate a threading issue, possibly also related
to the dependency graph since multiple objects are involved in
collisions.
This reverts commit c52b8ae818.
Sadly, at this point solver convergence is an exception rather than the
rule... Individual hairs can "explode" easily and thus disable the whole
simulation, which isn't helpful either.
This helps keep the simulation stable as long as there are only a few
substeps that become too constrained for the solver.
Eventually we need better feedback about these solver results, so that
artists can tweak situations specifically to resolve bad solver results.
This is somewhat similar to the camera tracker, which also can run into
cases that cannot be resolved and have to be fixed manually.
The Eigen solver is not quite stable currently (possibly due to
incorrect porting of force calculations). It also still lacks threading
support and optimized matrix construction, making it slower in
comparison. Eventually would still like to switch, but fixing these
issues takes time.
This adds transformations for each hair from world to "root space".
Currently positions and velocities are simply transformed for the solver
data and inverse-transformed when copying the results back to the cloth
data. This way the hair movement becomes independent from the movement
of the emitter object. Eventually the "fictitious" forces originating
from emitter movement can be added back in a controlled way.
http://en.wikipedia.org/wiki/Fictitious_force
Ignoring these fictitious forces or scaling their effect is physically
correct, because in the absence of external forces the hair will always
return to rest position in this root frame.
External forces currently are not yet transformed into the root space.
mode.
Eigen can become very slow in debug mode, which is a bit of a problem.
It relies heavily on compiler optimizations to remove function calls
etc. More optimizations may be desirable, possibly putting the implicit
solver into its own little library and enabling optimizations in debug
mode there could help.
This will allow us to implement moving reference frames for hair and
make "fictitious" forces optional, aiding in creating stable and
controllable hair systems.
Adding data in this place is a nasty hack, but it's too difficult to
encode as a DM data layer and the whole cloth modifier/DM intermediate
data copying for hair should be removed anyway.
This is not nice at all, but for some reason (possibly time scale) the
old force values are much too high and cause the solver to become
unstable. These will be revisited later anyway, so for now such scaling
should be fine.
constraining.
The algorithm is described in the paper "Large Steps in Cloth Simulation"
(Baraff/Witkin 1998). The same method was (incorrectly) implemented in
the old cloth solver.
It is based on restricting the degrees of freedom (ndof) of vertices
using a block matrix and a vector of target velocity deltas.
See chapter 5 of the paper for details.
Note that goal springs currently are really bad ... They have a factor
on hairs that "fades" goal influence from the root to the tip. The last
point on the hair is completely free, which makes the goal springs
pretty much useless on their own without supporting bend stiffness.
Can only assume this was added to compensate unphysical behavior of
goal springs when using uniform weight, but it's a poor replacement for
true localized bending forces ...
a custom built solver.
The old cloth solver is broken unfortunately. Eigen is a designated
linear algebra library and very likely their implementation is a lot
better (can't compare until it's implemented though).
Only basic gravity is active atm, spring forces, external force fields,
damping and volumetric friction have to be added back by converting
the data into the Eigen format.
responses.
The S matrix together with the z Vector encodes the degrees of freedom
of a colliding hair point and the target velocity change. In a collision
the hair vertex is restricted in the normal direction (when moving
toward the collider) and the collision dynamics define target velocity.
This simply uses the position above the triangle instead of the
intersection point of the vertex path. The other method was broken
anyway, but also has a problem catching all the contacts reliably. The
new method might have a few false positives but that is acceptable.
the contents of the strip around.
Only tested with movie strips now, metastrips won't work. Also there
might be some lingering bugs. Sonetimes refresh is needed to get
contents showing up correctly.
solver that properly supports constraints with some degrees-of-freedom.
The previous solver implementation only used the S matrix (constraint
filter matrix) for pinning vertices, in which case all elements are
zero and the error doesn't show up. With partial constraints (useful for
collision contacts) the matrix has non-zero off-diagonal elements and
the algorithm easily diverges.
There are also initial steps for implementing collision prevention as
described in the Baraff/Witkin paper "Large Steps in Cloth Simulation"
(http://www.cs.cmu.edu/~baraff/papers/sig98.pdf).
This is a first test, the contacts are very explosive atm because they
basically pin hair vertices globally on collision, which leads to
stretching of the springs which is then suddenly released in the next
frame.
Instead of handling contact tests and collision response in the same
function in collision.c, first generate contact points and return them
as a list, then free at the end of the stepping function. This way the
contact response can be integrated into the conjugate gradient method
properly instead of using the hackish and unstable double evaluation
that is currently used.
The original BLI method for line/triangle intersection returns false
in case the line does not actually intersect, but in order to generate
repulsion forces we need to also handle contacts inside the margin.
timestep segment.
This ensures the distance for a collision pair is the one of the current
point position, and the response gets calculated accordingly.
simulation.
Note that this currently generates an extreme amount of points, by
making a edit pathcache curve for each hair in every frame! But at least
doesn't simply crash now.
This implements a penalty force as well as a repulsion force to avoid
further penetration, as suggested in
"Simulating Complex Hair with Robust Collision Handling"
(http://graphics.snu.ac.kr/publications/2005-choe-HairSim/Choe_2005_SCA.pdf)
Friction forces are still missing. More problematic is handling of
moving colliders, when face swap places with the hair vertex and a
collision is missed, putting the vertex inside the mesh volume. Larger
margins might help, but ultimately using Bullet collision detection is
probably more reliable and failsafe.
as forces, velocities, contact points etc.
This uses a hash table to store debug elements (dots, lines, vectors at
this point). The hash table allows continuous display of elements that
are generated only in certain time steps, e.g. contact points, while
avoiding massive memory allocation. In any case, this system is really
a development feature, but very helpful in finding issues with the
internal solver data.
This is still using the old BVH tree collision methods to generate
contact points, similar to what cloth does. This should be replaced
by a Bullet collision check, but generating contacts in this way is
easier for now, and lets us test responses and stability (although in
more complex collision cases the BVH method fails utterly, beside being
terribly inefficient with many colliders).
on itself.
This uses the same voxel structure as the hair smoothing algorithm.
A slightly different method was suggested in the original paper
(Volumetric Methods for Simulation and Rendering of Hair), but this is
based on directing hair based on a target density, which is another
way of implementing global goals. Our own approach is to define a
pressure threshold above which the hair is repelled in the density
gradient direction to simulate internal pressure from collisions.
This is an important hair interaction feature that simulates friction
between hairs in an efficient way. The method is based on the paper
"Volumetric Methods for Simulation and Rendering of Hair"
( http://graphics.pixar.com/library/Hair/paper.pdf )
It was partially implemented already, but didn't work in this simplified
version. The same voxel structure can be used for implemeting repelling
forces on hair based on density, which can help a hair system maintain
volume instead of collapsing in on itself.
the suggested tent function from the original paper.
Plain float->int conversion for the grid location otherwise leads to
skewed data and unnecessary loss of information.
Example of using a :class:`bge.types.SCA_MouseSensor`,
and two :class:`bge.types.KX_ObjectActuator` to implement MouseLook:
Example of using a :class:`bge.types.SCA_MouseSensor`, and two :class:`bge.types.KX_ObjectActuator` to implement MouseLook:
..note::
This can also be achieved with the :class:`bge.types.KX_MouseActuator`.
@@ -78,9 +77,7 @@ Constants
..DATA:: VSYNC_ADAPTIVE
Enables adaptive vsync if supported.
Adaptive vsync enables vsync if the framerate is above the monitors refresh rate.
Otherwise, vsync is diabled if the framerate is too low.
Enables adaptive vsync if supported. Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. Otherwise, vsync is diabled if the framerate is too low.
..data:: LEFT_EYE
@@ -111,55 +108,40 @@ Functions
Set the width and height of the window (in pixels). This also works for fullscreen applications.
..note:: Only works in the standalone player, not the Blender-embedded player.
:arg width:width in pixels
:type width:integer
:arg height:height in pixels
:type height:integer
..function:: setFullScreen(enable)
Set whether or not the window should be fullscreen.
..note:: Only works in the standalone player, not the Blender-embedded player.
:arg enable:``True`` to set full screen, ``False`` to set windowed.
:type enable:bool
..function:: getFullScreen()
Returns whether or not the window is fullscreen.
..note:: Only works in the standalone player, not the Blender-embedded player; there it always returns False.
:rtype:bool
..function:: getDisplayDimensions()
Get the display dimensions, in pixels, of the display (e.g., the
monitor). Can return the size of the entire view, so the
combination of all monitors; for example, ``(3840, 1080)`` for two
side-by-side 1080p monitors.
Get the actual display dimensions, in pixels, of the physical display (e.g., the monitor).
:rtype:tuple (width,height)
:type dimension:list [width,heigh]
..function:: makeScreenshot(filename)
Writes an image file with the current displayed frame.
The image is written to *'filename'*.
The path may be absolute (eg. ``/home/foo/image``) or relative when started with
``//`` (eg. ``//image``). Note that absolute paths are not portable between platforms.
If the filename contains a ``#``,
it will be replaced by an incremental index so that screenshots can be taken multiple
times without overwriting the previous ones (eg. ``image-#``).
The image is written to *'filename'*. The path may be absolute (eg. "/home/foo/image") or relative when started with
"//" (eg. "//image"). Note that absolute paths are not portable between platforms.
If the filename contains a "#", it will be replaced by an incremental index so that screenshots can be taken multiple
times without overwriting the previous ones (eg. "image-#").
Settings for the image are taken from the render settings (file format and respective settings,
gamma and colospace conversion, etc).
The image resolution matches the framebuffer, meaning, the window size and aspect ratio.
When running from the standalone player, instead of the embedded player, only PNG files are supported.
Additional color conversions are also not supported.
Settings for the image are taken from the render settings (file format and respective settings, gamma and colospace
conversion, etc). The image resolution matches the framebuffer, meaning, the window size and aspect ratio.
When running from the standalone player, instead of the embedded player, only PNG files are supported. Additional
color conversions are also not supported.
:arg filename:path and name of the file to write
:type filename:string
@@ -167,14 +149,13 @@ Functions
..function:: enableVisibility(visible)
Deprecated; doesn't do anything.
Doesn't really do anything...
..function:: showMouse(visible)
Enables or disables the operating system mouse cursor.
:arg visible:
:type visible:boolean
@@ -182,15 +163,15 @@ Functions
Sets the mouse cursor position.
:arg x:X-coordinate in screen pixel coordinates.
:type x:integer
:arg y:Y-coordinate in screen pixel coordinates.
:type y:integer
..function:: setBackgroundColor(rgba)
Deprecated and no longer functional. Use :py:meth:`bge.types.KX_WorldInfo.backgroundColor` instead.
Sets the window background color. (Deprecated: use KX_WorldInfo.background_color)
:type rgba:list [r, g, b, a]
..function:: setEyeSeparation(eyesep)
@@ -234,7 +215,6 @@ Functions
Set the material mode to use for OpenGL rendering.
Look from a point/object to another point/object and find first object hit within dist that matches prop.
if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None, None, None) if no hit.
@@ -851,8 +828,6 @@ base class --- :class:`SCA_IObject`
* 2: return value is a 5-tuple and the 5th element is a 2-tuple (u, v) with the UV mapping of the hit point or None if no hit, or the object doesn't use a mesh collision shape, or doesn't have a UV mapping.
:type poly:integer
:arg mask:collision mask: The collision mask (16 layers mapped to a 16-bit integer) is combined with each object's collision group, to hit only a subset of the objects in the scene. Only those objects for which ``collisionGroup & mask`` is true can be hit.
:type mask:bitfield
:return:(object, hitpoint, hitnormal) or (object, hitpoint, hitnormal, polygon) or (object, hitpoint, hitnormal, polygon, hituv).
* object, hitpoint and hitnormal are None if no hit.
@@ -974,16 +949,6 @@ base class --- :class:`SCA_IObject`
:return:The current frame of the action
:rtype:float
..method:: getActionName(layer=0)
Gets the name of the current action playing in the supplied layer.
:arg layer:The layer that you want to get the action name from.
:type layer:integer
:return:The name of the current action
:rtype:string
..method:: setActionFrame(frame, layer=0)
Set the current frame of the action playing in the supplied layer.
Represents an internal texture used for certain effect
The uniform is an integer representing an internal texture used for certain effect
(color band, etc).
:type:integer
:value:12
..data:: GPU_DYNAMIC_SAMPLER_2DIMAGE
Represents a texture loaded from an image file.
The uniform is an integer representing a texture loaded from an image file.
:type:integer
:value:13
..data:: GPU_DYNAMIC_SAMPLER_2DSHADOW
Represents a texture loaded from a shadow buffer file.
The uniform is an float representing the bumpmap scaling.
:type:integer
:value:14
..data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE
The uniform is an integer representing a shadow buffer corresponding to a lamp
casting shadow.
:value:15
GLSL Mist Uniforms
^^^^^^^^^^^^^^^^^^
..data:: GPU_DYNAMIC_MIST_ENABLE:
See :class:`bpy.types.WorldMistSettings.use_mist`.
:type:float (0 or 1)
..data:: GPU_DYNAMIC_MIST_START
See :class:`bpy.types.WorldMistSettings.start`.
:type:float
See :class:`bpy.types.WorldMistSettings.depth`.
..data:: GPU_DYNAMIC_MIST_DISTANCE
:type:float
See :class:`bpy.types.WorldMistSettings.intensity`.
..data:: GPU_DYNAMIC_MIST_INTENSITY
:type:float
..data:: GPU_DYNAMIC_MIST_TYPE
See :class:`bpy.types.WorldMistSettings.falloff`.
:type:float (used as an index into the type)
..data:: GPU_DYNAMIC_MIST_COLOR
GLSL World Uniforms
^^^^^^^^^^^^^^^^^^^
..data:: GPU_DYNAMIC_HORIZON_COLOR
See :class:`bpy.types.World.horizon_color`.
:type:float3
..data:: GPU_DYNAMIC_AMBIENT_COLOR
See :class:`bpy.types.World.ambient_color`.
:type:float3
GLSL Material Uniforms
^^^^^^^^^^^^^^^^^^^^^^
..data:: GPU_DYNAMIC_MAT_DIFFRGB
See :class:`bpy.types.Material.diffuse_color`.
:type:float3
..data:: GPU_DYNAMIC_MAT_REF
See :class:`bpy.types.Material.diffuse_intensity`.
:type:float
..data:: GPU_DYNAMIC_MAT_SPECRGB
See :class:`bpy.types.Material.specular_color`.
:type:float3
..data:: GPU_DYNAMIC_MAT_SPEC
See :class:`bpy.types.Material.specular_intensity`.
:type:float
..data:: GPU_DYNAMIC_MAT_HARD
See :class:`bpy.types.Material.specular_hardness`.
:type:float
..data:: GPU_DYNAMIC_MAT_EMIT
See :class:`bpy.types.Material.emit`.
:type:float
..data:: GPU_DYNAMIC_MAT_AMB
See :class:`bpy.types.Material.ambient`.
:type:float
..data:: GPU_DYNAMIC_MAT_ALPHA
See :class:`bpy.types.Material.alpha`.
:type:float
GLSL Attribute Type
GLSL attribute type
-------------------
.._attribute-type:
@@ -429,7 +291,9 @@ layer that contains the vertex attribute.
..code-block::python
mesh.uv_layers[attribute["name"]]
mesh.uv_textures[attribute["name"]]
:value:5
..data:: CD_MCOL
@@ -442,6 +306,8 @@ layer that contains the vertex attribute.
mesh.vertex_colors[attribute["name"]]
:value:6
..data:: CD_ORCO
Vertex attribute is original coordinates. Data type is vector 3 float.
@@ -453,6 +319,8 @@ layer that contains the vertex attribute.
mesh.vertices
:value:14
..data:: CD_TANGENT
Vertex attribute is the tangent vector. Data type is vector 4 float.
@@ -462,6 +330,8 @@ layer that contains the vertex attribute.
C function to compute the tangent layer from the other layers can be obtained from
blender.org.
:value:18
Functions
=========
@@ -471,12 +341,8 @@ Functions
..function:: export_shader(scene,material)
Extracts the GLSL shader producing the visual effect of material in scene for the purpose of
reusing the shader in an external engine.
This function is meant to be used in material exporter
so that the GLSL shader can be exported entirely.
The return value is a dictionary containing the
reusing the shader in an external engine. This function is meant to be used in material exporter
so that the GLSL shader can be exported entirely. The return value is a dictionary containing the
shader source code and all associated data.
:arg scene:the scene in which the material in rendered.
@@ -488,91 +354,76 @@ Functions
The dictionary contains the following elements:
-``["fragment"]``: string
* ["fragment"]: string
fragment shader source code.
-``["vertex"]``: string
* ["vertex"]: string
vertex shader source code.
-``["uniforms"]``: sequence
* ["uniforms"]: sequence
list of uniforms used in fragment shader, can be empty list. Each element of the
sequence is a dictionary with the following elements:
-``["varname"]``: string
* ["varname"]: string
name of the uniform in the fragment shader. Always of the form 'unf<number>'.
-``["datatype"]``: integer
* ["datatype"]: integer
data type of the uniform variable. Can be one of the following:
..hlist::
:columns:2
*:data:`gpu.GPU_DATA_1I` : use glUniform1i
*:data:`gpu.GPU_DATA_1F` : use glUniform1fv
*:data:`gpu.GPU_DATA_2F` : use glUniform2fv
*:data:`gpu.GPU_DATA_3F` : use glUniform3fv
*:data:`gpu.GPU_DATA_4F` : use glUniform4fv
*:data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv
*:data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv
-:data:`gpu.GPU_DATA_1I` : use ``glUniform1i``
-:data:`gpu.GPU_DATA_1F` : use ``glUniform1fv``
-:data:`gpu.GPU_DATA_2F` : use ``glUniform2fv``
-:data:`gpu.GPU_DATA_3F` : use ``glUniform3fv``
-:data:`gpu.GPU_DATA_4F` : use ``glUniform4fv``
-:data:`gpu.GPU_DATA_9F` : use ``glUniformMatrix3fv``
-:data:`gpu.GPU_DATA_16F` : use ``glUniformMatrix4fv``
-``["type"]``: integer
*["type"] : integer
type of uniform, determines the origin and method of calculation. See uniform-type_.
Depending on the type, more elements will be be present.
-``["lamp"]``: :class:`bpy.types.Object`
Reference to the lamp object from which the uniforms value are extracted.
Set for the following uniforms types:
* ["lamp"]: :class:`bpy.types.Object`
Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types:
..hlist::
:columns:2
:columns:3
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
-:data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
-:data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY`
*:data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
*:data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`
Notes:
- The uniforms
:data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`,
:data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`,
:data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and
:data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
refer to the lamp object position and orientation,
both of can be derived from the object world matrix:
* The uniforms:data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT`
refer to the lamp object position and orientation, both of can be derived from the object world matrix:
..code-block::python
obmat=uniform["lamp"].matrix_world
where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array,
the lamp world location location is in ``obmat[3]``.
the lamp world location location is in obmat[3].
- The uniform types
:data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and
:data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL`
refer to the lamp data bloc that you get from:
* The uniform types:data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` refer to the lamp data bloc that you get from:
.. code-block:: python
la = uniform["lamp"].data
from which you get ``lamp.energy`` and ``lamp.color``
from which you get la.energy and la.color
- Lamp duplication is not supported: if you have duplicated lamps in your scene
* Lamp duplication is not supported: if you have duplicated lamps in your scene
(i.e. lamp that are instantiated by dupligroup, etc), this element will only
give you a reference to the orignal lamp and you will not know which instance
of the lamp it is refering too. You can still handle that case in the exporter
by distributing the uniforms amongst the duplicated lamps.
-``["image"]``: :class:`bpy.types.Image`
Reference to the image databloc.
Set for uniform type
:data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`.
You can get the image data from:
* ["image"]: :class:`bpy.types.Image`
Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from:
..code-block::python
@@ -581,63 +432,60 @@ Functions
# image size as a 2-dimensional array of int
uniform["image"].size
-``["texnumber"]``: integer
* ["texnumber"]: integer
Channel number to which the texture is bound when drawing the object.
Set for uniform types
:data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`,
:data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and
:data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
Set for uniform types:data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`.
This is provided for information only: when reusing the shader outside blencer,
you are free to assign the textures to the channel of your choice and to pass
that number channel to the GPU in the uniform.
-``["texpixels"]``: byte array
texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
Although the corresponding uniform is a 2D sampler,
the texture is always a 1D texture of n x 1 pixel.
The texture size n is provided in ["texsize"] element.
* ["texpixels"]: byte array
texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. Although
the corresponding uniform is a 2D sampler, the texture is always a 1D texture
of n x 1 pixel. The texture size n is provided in ["texsize"] element.
These texture are only used for computer generated texture (colorband, etc).
The texture data is provided so that you can make a real image out of it in the exporter.
The texture data is provided so that you can make a real image out of it in the
exporter.
-``["texsize"]``: integer
* ["texsize"]: integer
horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`.
The texture data is in ["texpixels"].
-``["attributes"]``: sequence
* ["attributes"]: sequence
list of attributes used in vertex shader, can be empty. Blender doesn't use
standard attributes except for vertex position and normal. All other vertex
attributes must be passed using the generic ``glVertexAttrib`` functions.
attributes must be passed using the generic glVertexAttrib functions.
The attribute data can be found in the derived mesh custom data using RNA.
Each element of the sequence is a dictionary containing the following elements:
-``["varname"]``: string
* ["varname"]: string
name of the uniform in the vertex shader. Always of the form 'att<number>'.
-``["datatype"]``: integer
* ["datatype"]: integer
data type of vertex attribute, can be one of the following:
-:data:`gpu.GPU_DATA_2F`: use ``glVertexAttrib2fv``
-:data:`gpu.GPU_DATA_3F`: use ``glVertexAttrib3fv``
-:data:`gpu.GPU_DATA_4F`: use ``glVertexAttrib4fv``
-:data:`gpu.GPU_DATA_4UB`: use ``glVertexAttrib4ubv``
*:data:`gpu.GPU_DATA_2F`: use glVertexAttrib2fv
*:data:`gpu.GPU_DATA_3F`: use glVertexAttrib3fv
*:data:`gpu.GPU_DATA_4F`: use glVertexAttrib4fv
*:data:`gpu.GPU_DATA_4UB`: use glVertexAttrib4ubv
-``["number"]``: integer
Generic attribute number. This is provided for information only.
Blender doesn't use ``glBindAttribLocation`` to place generic attributes at specific location,
* ["number"]: integer
generic attribute number. This is provided for information only. Blender
doesn't use glBindAttribLocation to place generic attributes at specific location,
it lets the shader compiler place the attributes automatically and query the
placement with ``glGetAttribLocation``.
The result of this placement is returned in this element.
placement with glGetAttribLocation. The result of this placement is returned in
this element.
When using this shader in a render engine, you should either use
``glBindAttribLocation`` to force the attribute at this location or use
``glGetAttribLocation`` to get the placement chosen by the compiler of your GPU.
glBindAttribLocation to force the attribute at this location or use
glGetAttribLocation to get the placement chosen by the compiler of your GPU.
-``["type"]``: integer
* ["type"]: integer
type of the mesh custom data from which the vertex attribute is loaded.
See attribute-type_.
-``["name"]``: string or integer
* ["name"]: string or integer
custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`.
Example:
@@ -664,14 +512,14 @@ Notes
.._mat4_lamp_to_perspective:
#. Calculation of the ``mat4_lamp_to_perspective`` matrix for a spot lamp.
1. Calculation of the *mat4_lamp_to_perspective* matrix for a spot lamp.
The following pseudo code shows how the ``mat4_lamp_to_perspective`` matrix is computed
The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed
in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type:
..code-block::python
#Get the lamp datablock with:
#Get the lamp datablock with:
lamp=bpy.data.objects[uniform["lamp"]].data
# Compute the projection matrix:
@@ -683,11 +531,11 @@ Notes
# The size of the projection plane is computed with the usual formula:
When writing your own scripts python is great for new developers to pick up and become productive,
but you can also pick up odd habits or at least write scripts that are not easy for others to understand.
When writing your own scripts python is great for new developers to pick up and become productive, but you can also pick up odd habits or at least write scripts that are not easy for others to understand.
For your own work this is of course fine,
but if you want to collaborate with others or have your work included with blender there are practices we encourage.
For your own work this is of course fine, but if you want to collaborate with others or have your work included with blender there are practices we encourage.
Style Conventions
=================
For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles
amongst our own scripts and make it easier to use python scripts from other projects.
For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects.
Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender.
@@ -22,17 +18,22 @@ This style guide is known as pep8 and can be found `here <http://www.python.org/
A brief listing of pep8 criteria.
- camel caps for class names: MyClass
- all lower case underscore separated module names: my_module
- indentation of 4 spaces (no tabs)
- spaces around operators. ``1 + 1``, not ``1+1``
- only use explicit imports, (no importing ``*``)
- don't use single line: ``if val: body``, separate onto 2 lines instead.
* camel caps for class names: MyClass
* all lower case underscore separated module names: my_module
* indentation of 4 spaces (no tabs)
* spaces around operators. ``1 + 1``, not ``1+1``
* only use explicit imports, (no importing '*')
* don't use single line: ``if val: body``, separate onto 2 lines instead.
As well as pep8 we have other conventions used for blender python scripts.
- Use single quotes for enums, and double quotes for strings.
* Use single quotes for enums, and double quotes for strings.
Both are of course strings but in our internal API enums are unique items from a limited set. eg.
@@ -41,11 +42,9 @@ As well as pep8 we have other conventions used for blender python scripts.
- pep8 also defines that lines should not exceed 79 characters,
we felt this is too restrictive so this is optional per script.
* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script.
Periodically we run checks for pep8 compliance on blender scripts,
for scripts to be included in this check add this line as a comment at the top of the script.
Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script.
``# <pep8 compliant>``
@@ -59,75 +58,72 @@ User Interface Layout
Some notes to keep in mind when writing UI layouts:
- UI code is quite simple. Layout declarations are there to easily create a decent layout.
General rule here: If you need more code for the layout declaration,
then for the actual properties, you do it wrong.
* UI code is quite simple. Layout declarations are there to easily create a decent layout.
General rule here: If you need more code for the layout declaration, then for the actual properties, you do it wrong.
Example layouts:
- layout()
The basic layout is a simple Top -> Bottom layout.
* layout()
The basic layout is a simple Top -> Bottom layout.
..code-block::python
layout.prop()
layout.prop()
layout.prop()
layout.prop()
- layout.row()
Use row(), when you want more than 1 property in one line.
* layout.row()
Use row(), when you want more than 1 property in one line.
..code-block::python
row=layout.row()
row.prop()
row.prop()
row = layout.row()
row.prop()
row.prop()
- layout.column()
* layout.column()
Use column(), when you want your properties in a column.
..code-block::python
col=layout.column()
col.prop()
col.prop()
col = layout.column()
col.prop()
col.prop()
* layout.split()
- layout.split()
This can be used to create more complex layouts.
For example you can split the layout and create two column() layouts next to each other.
This can be used to create more complex layouts. For example you can split the layout and create two column() layouts next to each other.
Don't use split, when you simply want two properties in a row. Use row() for that.
..code-block::python
split=layout.split()
col=split.column()
col.prop()
col.prop()
col=split.column()
col.prop()
col.prop()
split=layout.split()
col=split.column()
col.prop()
col.prop()
col=split.column()
col.prop()
col.prop()
Declaration names:
Try to only use these variable names for layout declarations:
- row for a row() layout
- col for a column() layout
- split for a split() layout
- flow for a column_flow() layout
- sub for a sub layout (a column inside a column for example)
* row for a row() layout
* col for a column() layout
* split for a split() layout
* flow for a column_flow() layout
* sub for a sub layout (a column inside a column for example)
Script Efficiency
=================
List Manipulation (General Python Tips)
---------------------------------------
@@ -137,8 +133,7 @@ Searching for list items
In Python there are some handy list functions that save you having to search through the list.
Even though you're not looping on the list data **python is**,
so you need to be aware of functions that will slow down your script by searching the whole list.
Even though you're not looping on the list data **python is**, so you need to be aware of functions that will slow down your script by searching the whole list.
..code-block::python
@@ -150,16 +145,11 @@ so you need to be aware of functions that will slow down your script by searchin
Modifying Lists
^^^^^^^^^^^^^^^
In python we can add and remove from a list, this is slower when the list length is modified,
especially at the start of the list, since all the data after the index of
modification needs to be moved up or down 1 place.
In python we can add and remove from a list, this is slower when the list length is modified, especially at the start of the list, since all the data after the index of modification needs to be moved up or down 1 place.
The most simple way to add onto the end of the list is to use
``my_list.append(list_item)`` or ``my_list.extend(some_list)`` and the fastest way to
remove an item is ``my_list.pop()`` or ``del my_list[-1]``.
The most simple way to add onto the end of the list is to use``my_list.append(list_item)`` or ``my_list.extend(some_list)`` and the fastest way to remove an item is ``my_list.pop()`` or ``del my_list[-1]``.
To use an index you can use ``my_list.insert(index, list_item)`` or ``list.pop(index)``
for list removal, but these are slower.
To use an index you can use ``my_list.insert(index, list_item)`` or ``list.pop(index)`` for list removal, but these are slower.
Sometimes its faster (but more memory hungry) to just rebuild the list.
@@ -203,8 +193,7 @@ Use...
my_list.extend([a,b,c...])
Note that insert can be used when needed,
but it is slower than append especially when inserting at the start of a long list.
Note that insert can be used when needed, but it is slower than append especially when inserting at the start of a long list.
This example shows a very sub-optimal way of making a reversed list.
@@ -216,8 +205,7 @@ This example shows a very sub-optimal way of making a reversed list.
reverse_list.insert(0,list_item)
Python provides more convenient ways to reverse a list using the slice method,
but you may want to time this before relying on it too much:
Python provides more convenient ways to reverse a list using the slice method, but you may want to time this before relying on it too much:
..code-block::python
@@ -232,8 +220,7 @@ Use ``my_list.pop(index)`` rather than ``my_list.remove(list_item)``
This requires you to have the index of the list item but is faster since ``remove()`` will search the list.
Here is an example of how to remove items in 1 loop,
removing the last items first, which is faster (as explained above).
Here is an example of how to remove items in 1 loop, removing the last items first, which is faster (as explained above).
..code-block::python
@@ -245,9 +232,7 @@ removing the last items first, which is faster (as explained above).
my_list.pop(list_index)
This example shows a fast way of removing items,
for use in cases where you can alter the list order without breaking the scripts functionality.
This works by swapping 2 list items, so the item you remove is always last.
This example shows a fast way of removing items, for use in cases where you can alter the list order without breaking the scripts functionality. This works by swapping 2 list items, so the item you remove is always last.
..code-block::python
@@ -266,9 +251,7 @@ When removing many items in a large list this can provide a good speedup.
Avoid Copying Lists
^^^^^^^^^^^^^^^^^^^
When passing a list/dictionary to a function,
it is faster to have the function modify the list rather than returning
a new list so python doesn't have to duplicate the list in memory.
When passing a list/dictionary to a function, it is faster to have the function modify the list rather than returning a new list so python doesn't have to duplicate the list in memory.
Functions that modify a list in-place are more efficient than functions that create new lists.
@@ -313,26 +296,20 @@ Python’s string joining function. To join a list of strings
is quite fast too (better for converting data types). String arithmetic is slowest.
join is fastest on many strings,`string formatting <http://docs.python.org/py3k/library/string.html#string-formatting>`_ is quite fast too (better for converting data types). String arithmetic is slowest.
Parsing Strings (Import/Exporting)
----------------------------------
Since many file formats are ASCII,
the way you parse/export strings can make a large difference in how fast your script runs.
Since many file formats are ASCII, the way you parse/export strings can make a large difference in how fast your script runs.
There are a few ways to parse strings when importing them into Blender.
Parsing Numbers
^^^^^^^^^^^^^^^
Use ``float(string)`` rather than ``eval(string)``, if you know the value will be an int then ``int(string)``,
float() will work for an int too but it's faster to read ints with int().
Use ``float(string)`` rather than ``eval(string)``, if you know the value will be an int then ``int(string)``, float() will work for an int too but it's faster to read ints with int().
Checking String Start/End
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -345,8 +322,7 @@ Use...
>>> if line.startswith("vert "):
Using ``startswith()`` is slightly faster (approx 5%) and also avoids a possible
error with the slice length not matching the string length.
Using ``startswith()`` is slightly faster (approx 5%) and also avoids a possible error with the slice length not matching the string length.
my_string.endswith("foo_bar") can be used for line endings too.
@@ -360,19 +336,15 @@ Use try/except Sparingly
The **try** statement is useful to save time writing error checking code.
However **try** is significantly slower than an **if** since an exception has to be set each time,
so avoid using **try** in areas of your code that execute in a loop and runs many times.
However **try** is significantly slower than an **if** since an exception has to be set each time, so avoid using **try** in areas of your code that execute in a loop and runs many times.
There are cases where using **try** is faster than checking whether the condition will raise an error,
so it is worth experimenting.
There are cases where using **try** is faster than checking whether the condition will raise an error, so it is worth experimenting.
Value Comparison
----------------
Python has two ways to compare values ``a == b`` and ``a is b``,
the difference is that ``==`` may run the objects comparison function ``__cmp__()`` whereas ``is`` compares identity,
that both variables reference the same item in memory.
Python has two ways to compare values ``a == b`` and ``a is b``, the difference is that ``==`` may run the objects comparison function ``__cmp__()`` whereas ``is`` compares identity, that both variables reference the same item in memory.
In cases where you know you are checking for the same value which is referenced from multiple places, ``is`` is faster.
@@ -390,4 +362,3 @@ While developing a script it's good to time it to be aware of any changes in per
This document attempts to help you work with the Blender API in areas
that can be troublesome and avoid practices that are known to give instability.
This document attempts to help you work with the Blender API in areas that can be troublesome and avoid practices that are known to give instability.
.._using_operators:
@@ -11,15 +10,16 @@ that can be troublesome and avoid practices that are known to give instability.
Using Operators
===============
Blender's operators are tools for users to access, that Python can access them too is very useful
nevertheless operators have limitations that can make them cumbersome to script.
Blender's operators are tools for users to access, that python can access them too is very useful nevertheless operators have limitations that can make them cumbersome to script.
Main limits are...
- Can't pass data such as objects, meshes or materials to operate on (operators use the context instead)
- The return value from calling an operator gives the success (if it finished or was canceled),
* Can't pass data such as objects, meshes or materials to operate on (operators use the context instead)
* The return value from calling an operator gives the success (if it finished or was canceled),
in some cases it would be more logical from an API perspective to return the result of the operation.
- Operators poll function can fail where an API function would raise an exception giving details on exactly why.
* Operators poll function can fail where an API function would raise an exception giving details on exactly why.
Why does an operator's poll fail?
@@ -32,28 +32,20 @@ When calling an operator gives an error like this:
Which raises the question as to what the correct context might be?
Typically operators check for the active area type, a selection or active object they can operate on,
but some operators are more picky about when they run.
Typically operators check for the active area type, a selection or active object they can operate on, but some operators are more picky about when they run.
In most cases you can figure out what context an operator needs
simply be seeing how it's used in Blender and thinking about what it does.
In most cases you can figure out what context an operator needs simply be seeing how it's used in Blender and thinking about what it does.
Unfortunately if you're still stuck - the only way to **really** know
whats going on is to read the source code for the poll function and see what its checking.
Unfortunately if you're still stuck - the only way to **really** know whats going on is to read the source code for the poll function and see what its checking.
For Python operators it's not so hard to find the source
since it's included with Blender and the source file/line is included in the operator reference docs.
For python operators it's not so hard to find the source since it's included with Blender and the source file/line is included in the operator reference docs.
Downloading and searching the C code isn't so simple,
especially if you're not familiar with the C language but by searching the
operator name or description you should be able to find the poll function with no knowledge of C.
Downloading and searching the C code isn't so simple, especially if you're not familiar with the C language but by searching the operator name or description you should be able to find the poll function with no knowledge of C.
..note::
Blender does have the functionality for poll functions to describe why they fail,
but its currently not used much, if you're interested to help improve our API
feel free to add calls to ``CTX_wm_operator_poll_msg_set`` where its not obvious why poll fails.
Blender does have the functionality for poll functions to describe why they fail, but its currently not used much, if you're interested to help improve our API feel free to add calls to ``CTX_wm_operator_poll_msg_set`` where its not obvious why poll fails.
>>> bpy.ops.gpencil.draw()
RuntimeError: Operator bpy.ops.gpencil.draw.poll() Failed to find Grease Pencil data to draw into
@@ -62,45 +54,36 @@ operator name or description you should be able to find the poll function with n
The operator still doesn't work!
--------------------------------
Certain operators in Blender are only intended for use in a specific context,
some operators for example are only called from the properties window where they check the current material,
modifier or constraint.
Certain operators in Blender are only intended for use in a specific context, some operators for example are only called from the properties window where they check the current material, modifier or constraint.
Examples of this are:
-:mod:`bpy.ops.texture.slot_move`
-:mod:`bpy.ops.constraint.limitdistance_reset`
-:mod:`bpy.ops.object.modifier_copy`
-:mod:`bpy.ops.buttons.file_browse`
*:mod:`bpy.ops.texture.slot_move`
*:mod:`bpy.ops.constraint.limitdistance_reset`
*:mod:`bpy.ops.object.modifier_copy`
*:mod:`bpy.ops.buttons.file_browse`
Another possibility is that you are the first person to attempt to use this operator
in a script and some modifications need to be made to the operator to run in a different context,
if the operator should logically be able to run but fails when accessed from a script
it should be reported to the bug tracker.
Another possibility is that you are the first person to attempt to use this operator in a script and some modifications need to be made to the operator to run in a different context, if the operator should logically be able to run but fails when accessed from a script it should be reported to the bug tracker.
Stale Data
==========
No updates after setting values
-------------------------------
Sometimes you want to modify values from Python and immediately access the updated values, eg:
Sometimes you want to modify values from python and immediately access the updated values, eg:
Once changing the objects :class:`bpy.types.Object.location`
you may want to access its transformation right after from :class:`bpy.types.Object.matrix_world`,
but this doesn't work as you might expect.
Once changing the objects :class:`bpy.types.Object.location` you may want to access its transformation right after from :class:`bpy.types.Object.matrix_world`, but this doesn't work as you might expect.
Consider the calculations that might go into working out the object's final transformation, this includes:
- animation function curves.
- drivers and their Python expressions.
- constraints
- parent objects and all of their f-curves, constraints etc.
* animation function curves.
* drivers and their pythons expressions.
* constraints
* parent objects and all of their f-curves, constraints etc.
To avoid expensive recalculations every time a property is modified,
Blender defers making the actual calculations until they are needed.
To avoid expensive recalculations every time a property is modified, Blender defers making the actual calculations until they are needed.
However, while the script runs you may want to access the updated values.
In this case you need to call :class:`bpy.types.Scene.update` after modifying values, for example:
@@ -111,9 +94,7 @@ In this case you need to call :class:`bpy.types.Scene.update` after modifying va
bpy.context.scene.update()
Now all dependent data (child objects, modifiers, drivers... etc)
has been recalculated and is available to the script.
Now all dependent data (child objects, modifiers, drivers... etc) has been recalculated and is available to the script.
Can I redraw during the script?
-------------------------------
@@ -122,33 +103,23 @@ The official answer to this is no, or... *"You don't want to do that"*.
To give some background on the topic...
While a script executes Blender waits for it to finish and is effectively locked until its done,
while in this state Blender won't redraw or respond to user input.
Normally this is not such a problem because scripts distributed with Blender
tend not to run for an extended period of time,
nevertheless scripts *can* take ages to execute and its nice to see whats going on in the view port.
While a script executes Blender waits for it to finish and is effectively locked until its done, while in this state Blender won't redraw or respond to user input.
Normally this is not such a problem because scripts distributed with Blender tend not to run for an extended period of time, nevertheless scripts *can* take ages to execute and its nice to see whats going on in the view port.
Tools that lock Blender in a loop and redraw are highly discouraged
since they conflict with Blenders ability to run multiple operators
at once and update different parts of the interface as the tool runs.
Tools that lock Blender in a loop and redraw are highly discouraged since they conflict with Blenders ability to run multiple operators at once and update different parts of the interface as the tool runs.
So the solution here is to write a **modal** operator, that is - an operator which defines a modal() function,
See the modal operator template in the text editor.
So the solution here is to write a **modal** operator, that is - an operator which defines a modal() function, See the modal operator template in the text editor.
Modal operators execute on user input or setup their own timers to run frequently,
they can handle the events or pass through to be handled by the keymap or other modal operators.
Modal operators execute on user input or setup their own timers to run frequently, they can handle the events or pass through to be handled by the keymap or other modal operators.
Transform, Painting, Fly-Mode and File-Select are example of a modal operators.
Writing modal operators takes more effort than a simple ``for`` loop
that happens to redraw but is more flexible and integrates better with Blenders design.
Writing modal operators takes more effort than a simple ``for`` loop that happens to redraw but is more flexible and integrates better with Blenders design.
**Ok, Ok! I still want to draw from Python**
**Ok, Ok! I still want to draw from python**
If you insist - yes its possible, but scripts that use this hack wont be considered
for inclusion in Blender and any issues with using it wont be considered bugs,
this is also not guaranteed to work in future releases.
If you insist - yes its possible, but scripts that use this hack wont be considered for inclusion in Blender and any issues with using it wont be considered bugs, this is also not guaranteed to work in future releases.
..code-block::python
@@ -158,18 +129,16 @@ this is also not guaranteed to work in future releases.
Modes and Mesh Access
=====================
When working with mesh data you may run into the problem where a script fails to run as expected in edit-mode.
This is caused by edit-mode having its own data which is only written back to the mesh when exiting edit-mode.
When working with mesh data you may run into the problem where a script fails to run as expected in edit-mode. This is caused by edit-mode having its own data which is only written back to the mesh when exiting edit-mode.
A common example is that exporters may access a mesh through ``obj.data`` (a :class:`bpy.types.Mesh`)
but the user is in edit-mode, where the mesh data is available but out of sync with the edit mesh.
A common example is that exporters may access a mesh through ``obj.data`` (a :class:`bpy.types.Mesh`) but the user is in edit-mode, where the mesh data is available but out of sync with the edit mesh.
In this situation you can...
- Exit edit-mode before running the tool.
- Explicitly update the mesh by calling :class:`bmesh.types.BMesh.to_mesh`.
- Modify the script to support working on the edit-mode data directly, see: :mod:`bmesh.from_edit_mesh`.
- Report the context as incorrect and only allow the script to run outside edit-mode.
* Exit edit-mode before running the tool.
* Explicitly update the mesh by calling :class:`bmesh.types.BMesh.to_mesh`.
* Modify the script to support working on the edit-mode data directly, see: :mod:`bmesh.from_edit_mesh`.
* Report the context as incorrect and only allow the script to run outside edit-mode.
.._info_gotcha_mesh_faces:
@@ -177,55 +146,35 @@ In this situation you can...
NGons and Tessellation Faces
============================
Since 2.63 NGons are supported, this adds some complexity
since in some cases you need to access triangles/quads still (some exporters for example).
Since 2.63 NGons are supported, this adds some complexity since in some cases you need to access triangles/quads still (some exporters for example).
There are now 3 ways to access faces:
-:class:`bpy.types.MeshPolygon` -
this is the data structure which now stores faces in object mode
(access as ``mesh.polygons`` rather than ``mesh.faces``).
-:class:`bpy.types.MeshTessFace` -
the result of triangulating (tessellated) polygons,
the main method of face access in 2.62 or older (access as ``mesh.tessfaces``).
-:class:`bmesh.types.BMFace` -
the polygons as used in editmode.
*:class:`bpy.types.MeshPolygon` - this is the data structure which now stores faces in object mode (access as ``mesh.polygons`` rather then ``mesh.faces``).
*:class:`bpy.types.MeshTessFace` - the result of triangulating (tessellated) polygons, the main method of face access in 2.62 or older (access as ``mesh.tessfaces``).
*:class:`bmesh.types.BMFace` - the polygons as used in editmode.
For the purpose of the following documentation,
these will be referred to as polygons, tessfaces and bmesh-faces respectively.
For the purpose of the following documentation, these will be referred to as polygons, tessfaces and bmesh-faces respectively.
Using the :mod:`bmesh` api is completely separate api from :mod:`bpy`,
typically you would would use one or the other based on the level of editing needed,
not simply for a different way to access faces.
Using the :mod:`bmesh` api is completely separate api from :mod:`bpy`, typically you would would use one or the other based on the level of editing needed, not simply for a different way to access faces.
Creating
@@ -233,18 +182,9 @@ Creating
All 3 datatypes can be used for face creation.
- polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible,
you must have all your vertes and faces ready and create them all at once.
This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces),
rather they reference an index and size in :class:`bpy.types.Mesh.loops` which are a fixed array too.
- tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons,
however for scripts upgrading from 2.62 this is by far the most straightforward option.
This works by creating tessfaces and when finished -
they can be converted into polygons by calling :class:`bpy.types.Mesh.update`.
The obvious limitation is ngons can't be created this way.
- bmesh-faces are most likely the easiest way for new scripts to create faces,
since faces can be added one by one and the api has features intended for mesh manipulation.
While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time.
* polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in :class:`bpy.types.Mesh.loops` which are a fixed array too.
* tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. The obvious limitation is ngons can't be created this way.
* bmesh-faces are most likely the easiest way for new scripts to create faces, since faces can be added one by one and the api has features intended for mesh manipulation. While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time.
Editing
@@ -252,24 +192,18 @@ Editing
Editing is where the 3 data types vary most.
-Polygons are very limited for editing,
changing materials and options like smooth works but for anything else
they are too inflexible and are only intended for storage.
- Tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated.
- BMesh-Faces are by far the best way to manipulate geometry.
*polygons are very limited for editing, changing materials and options like smooth works but for anything else they are too inflexible and are only intended for storage.
* tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated.
* bmesh-faces are by far the best way to manipulate geometry.
Exporting
---------
All 3 data types can be used for exporting,
the choice mostly depends on whether the target format supports ngons or not.
All 3 data types can be used for exporting, the choice mostly depends on whether the target format supports ngons or not.
-Polygons are the most direct & efficient way to export providing they convert into the output format easily enough.
-Tessfaces work well for exporting to formats which dont support ngons,
in fact this is the only place where their use is encouraged.
- BMesh-Faces can work for exporting too but may not be necessary if polygons can be used
since using bmesh gives some overhead because its not the native storage format in object mode.
*polygons are the most direct & efficient way to export providing they convert into the output format easily enough.
*tessfaces work well for exporting to formats which dont support ngons, in fact this is the only place where their use is encouraged.
* bmesh-faces can work for exporting too but may not be necessary if polygons can be used since using bmesh gives some overhead because its not the native storage format in object mode.
Upgrading Importers from 2.62
@@ -279,9 +213,9 @@ Importers can be upgraded to work with only minor changes.
The main change to be made is used the tessellation versions of each attribute.
Once the data is created call :class:`bpy.types.Mesh.update` to convert the tessfaces into polygons.
@@ -289,9 +223,7 @@ Once the data is created call :class:`bpy.types.Mesh.update` to convert the tess
Upgrading Exporters from 2.62
-----------------------------
For exporters the most direct way to upgrade is to use tessfaces as with importing
however its important to know that tessfaces may **not** exist for a mesh,
the array will be empty as if there are no faces.
For exporters the most direct way to upgrade is to use tessfaces as with importing however its important to know that tessfaces may **not** exist for a mesh, the array will be empty as if there are no faces.
So before accessing tessface data call: :class:`bpy.types.Mesh.update```(calc_tessface=True)``.
@@ -299,8 +231,7 @@ So before accessing tessface data call: :class:`bpy.types.Mesh.update` ``(calc_t
EditBones, PoseBones, Bone... Bones
===================================
Armature Bones in Blender have three distinct data structures that contain them.
If you are accessing the bones through one of them, you may not have access to the properties you really need.
Armature Bones in Blender have three distinct data structures that contain them. If you are accessing the bones through one of them, you may not have access to the properties you really need.
..note::
@@ -310,9 +241,7 @@ If you are accessing the bones through one of them, you may not have access to t
Edit Bones
----------
``bpy.context.object.data.edit_bones`` contains a editbones;
to access them you must set the armature mode to edit mode first (editbones do not exist in object or pose mode).
Use these to create new bones, set their head/tail or roll, change their parenting relationships to other bones, etc.
``bpy.context.object.data.edit_bones`` contains a editbones; to access them you must set the armature mode to edit mode first (editbones do not exist in object or pose mode). Use these to create new bones, set their head/tail or roll, change their parenting relationships to other bones, etc.
Example using :class:`bpy.types.EditBone` in armature editmode:
@@ -332,9 +261,7 @@ Returns an editbone only in edit mode.
Bones (Object Mode)
-------------------
``bpy.context.object.data.bones`` contains bones.
These *live* in object mode, and have various properties you can change,
note that the head and tail properties are read-only.
``bpy.context.object.data.bones`` contains bones. These *live* in object mode, and have various properties you can change, note that the head and tail properties are read-only.
Example using :class:`bpy.types.Bone` in object or pose mode:
This is where animation data resides, i.e. animatable transformations
are applied to pose bones, as are constraints and ik-settings.
``bpy.context.object.pose.bones`` contains pose bones. This is where animation data resides, i.e. animatable transformations are applied to pose bones, as are constraints and ik-settings.
Examples using :class:`bpy.types.PoseBone` in object or pose mode:
@@ -371,27 +296,19 @@ Examples using :class:`bpy.types.PoseBone` in object or pose mode:
..note::
Notice the pose is accessed from the object rather than the object data,
this is why blender can have 2 or more objects sharing the same armature in different poses.
Notice the pose is accessed from the object rather than the object data, this is why blender can have 2 or more objects sharing the same armature in different poses.
..note::
Strictly speaking PoseBone's are not bones, they are just the state of the armature,
stored in the :class:`bpy.types.Object` rather than the :class:`bpy.types.Armature`,
the real bones are however accessible from the pose bones - :class:`bpy.types.PoseBone.bone`
Strictly speaking PoseBone's are not bones, they are just the state of the armature, stored in the :class:`bpy.types.Object` rather than the :class:`bpy.types.Armature`, the real bones are however accessible from the pose bones - :class:`bpy.types.PoseBone.bone`
Armature Mode Switching
-----------------------
While writing scripts that deal with armatures you may find you have to switch between modes,
when doing so take care when switching out of edit-mode not to keep references
to the edit-bones or their head/tail vectors.
Further access to these will crash blender so its important the script
clearly separates sections of the code which operate in different modes.
While writing scripts that deal with armatures you may find you have to switch between modes, when doing so take care when switching out of editmode not to keep references to the edit-bones or their head/tail vectors. Further access to these will crash blender so its important the script clearly separates sections of the code which operate in different modes.
This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode,
however for operator access you may still need to enter pose mode.
This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, however for operator access you may still need to enter pose mode.
Data Names
@@ -426,13 +343,10 @@ Or with name assignment...
Data names may not match the assigned values if they exceed the maximum length, are already used or an empty string.
Its better practice not to reference objects by names at all,
once created you can store the data in a list, dictionary, on a class etc,
there is rarely a reason to have to keep searching for the same data by name.
Its better practice not to reference objects by names at all, once created you can store the data in a list, dictionary, on a class etc, there is rarely a reason to have to keep searching for the same data by name.
If you do need to use name references, its best to use a dictionary to maintain
a mapping between the names of the imported assets and the newly created data,
this way you don't run this risk of referencing existing data from the blend file, or worse modifying it.
If you do need to use name references, its best to use a dictionary to maintain a mapping between the names of the imported assets and the newly created data, this way you don't run this risk of referencing existing data from the blend file, or worse modifying it.
..code-block::python
@@ -444,22 +358,18 @@ this way you don't run this risk of referencing existing data from the blend fil
# normally some code, or function calls...
# use own dictionary rather than bpy.data
# use own dictionary rather then bpy.data
mesh=mesh_name_mapping[meshid]
Library Collisions
------------------
Blender keeps data names unique - :class:`bpy.types.ID.name` so you can't name two objects,
meshes, scenes etc the same thing by accident.
Blender keeps data names unique - :class:`bpy.types.ID.name` so you can't name two objects, meshes, scenes etc the same thing by accident.
However when linking in library data from another blend file naming collisions can occur,
so its best to avoid referencing data by name at all.
However when linking in library data from another blend file naming collisions can occur, so its best to avoid referencing data by name at all.
This can be tricky at times and not even blender handles this correctly in some case
(when selecting the modifier object for eg you can't select between multiple objects with the same name),
but its still good to try avoid problems in this area.
This can be tricky at times and not even blender handles this correctly in some case (when selecting the modifier object for eg you can't select between multiple objects with the same name), but its still good to try avoid problems in this area.
If you need to select between local and library data, there is a feature in ``bpy.data`` members to allow for this.
@@ -484,23 +394,21 @@ If you need to select between local and library data, there is a feature in ``bp
Relative File Paths
===================
Blenders relative file paths are not compatible with standard Python modules such as ``sys`` and ``os``.
Blenders relative file paths are not compatible with standard python modules such as ``sys`` and ``os``.
Built in Python functions don't understand blenders ``//`` prefix which denotes the blend file path.
Built in python functions don't understand blenders ``//`` prefix which denotes the blend file path.
A common case where you would run into this problem is when exporting a material with associated image paths.
>>> bpy.path.abspath(image.filepath)
>>> bpy.path.abspath(image.filepath)
When using blender data from linked libraries there is an unfortunate complication
since the path will be relative to the library rather than the open blend file.
When the data block may be from an external blend file pass the library argument from the :class:`bpy.types.ID`.
When using blender data from linked libraries there is an unfortunate complication since the path will be relative to the library rather then the open blend file. When the data block may be from an external blend file pass the library argument from the :class:`bpy.types.ID`.
These returns the absolute path which can be used with native Python modules.
These returns the absolute path which can be used with native python modules.
Unicode Problems
@@ -541,28 +449,23 @@ Here are 2 ways around filesystem encoding issues:
>>> bpy.context.object.name = filepath_utf8
Unicode encoding/decoding is a big topic with comprehensive Python documentation,
to avoid getting stuck too deep in encoding problems - here are some suggestions:
Unicode encoding/decoding is a big topic with comprehensive python documentation, to avoid getting stuck too deep in encoding problems - here are some suggestions:
- Always use utf-8 encoding or convert to utf-8 where the input is unknown.
- Avoid manipulating filepaths as strings directly, use ``os.path`` functions instead.
- Use ``os.fsencode()`` / ``os.fsdecode()`` instead of built in string decoding functions when operating on paths.
- To print paths or to include them in the user interface use ``repr(path)`` first
or ``"%r" % path`` with string formatting.
* Always use utf-8 encoiding or convert to utf-8 where the input is unknown.
..note::
* Avoid manipulating filepaths as strings directly, use ``os.path`` functions instead.
Sometimes it's preferrable to avoid string encoding issues by using bytes instead of Python strings,
when reading some input its less trouble to read it as binary data
though you will still need to decide how to treat any strings you want to use with Blender,
some importers do this.
* Use ``os.fsencode()`` / ``os.fsdecode()`` rather then the built in string decoding functions when operating on paths.
* To print paths or to include them in the user interface use ``repr(path)`` first or ``"%r" % path`` with string formatting.
***Possibly** - use bytes instead of python strings, when reading some input its less trouble to read it as binary data though you will still need to decide how to treat any strings you want to use with Blender, some importers do this.
Strange errors using 'threading' module
=======================================
Python threading with Blender only works properly when the threads finish up before the script does.
By using ``threading.join()`` for example.
Python threading with Blender only works properly when the threads finish up before the script does. By using ``threading.join()`` for example.
Heres an example of threading supported by Blender:
@@ -601,8 +504,7 @@ Heres an example of threading supported by Blender:
t.join()
This an example of a timer which runs many times a second and moves
the default cube continuously while Blender runs **(Unsupported)**.
This an example of a timer which runs many times a second and moves the default cube continuously while Blender runs **(Unsupported)**.
..code-block::python
@@ -619,48 +521,38 @@ the default cube continuously while Blender runs **(Unsupported)**.
my_timer()
Use cases like the one above which leave the thread running once the script finishes
may seem to work for a while but end up causing random crashes or errors in Blender's own drawing code.
Use cases like the one above which leave the thread running once the script finishes may seem to work for a while but end up causing random crashes or errors in Blender's own drawing code.
So far, no work has gone into making Blender's Python integration thread safe,
so until its properly supported, best not make use of this.
So far, no work has gone into making Blender's python integration thread safe, so until its properly supported, best not make use of this.
..note::
Pythons threads only allow co-currency and won't speed up your scripts on multi-processor systems,
the ``subprocess`` and ``multiprocess`` modules can be used with Blender and make use of multiple CPU's too.
Pythons threads only allow co-currency and won't speed up your scripts on multi-processor systems, the ``subprocess`` and ``multiprocess`` modules can be used with Blender and make use of multiple CPU's too.
Help! My script crashes Blender
===============================
Ideally it would be impossible to crash Blender from Python
however there are some problems with the API where it can be made to crash.
Ideally it would be impossible to crash Blender from python however there are some problems with the API where it can be made to crash.
Strictly speaking this is a bug in the API but fixing it would mean adding memory verification
on every access since most crashes are caused by the Python objects referencing Blenders memory directly,
whenever the memory is freed, further Python access to it can crash the script.
But fixing this would make the scripts run very slow,
or writing a very different kind of API which doesn't reference the memory directly.
Strictly speaking this is a bug in the API but fixing it would mean adding memory verification on every access since most crashes are caused by the python objects referencing Blenders memory directly, whenever the memory is freed, further python access to it can crash the script. But fixing this would make the scripts run very slow, or writing a very different kind of API which doesn't reference the memory directly.
Here are some general hints to avoid running into these problems.
- Be aware of memory limits,
especially when working with large lists since Blender can crash simply by running out of memory.
- Many hard to fix crashes end up being because of referencing freed data,
when removing data be sure not to hold any references to it.
- Modules or classes that remain active while Blender is used,
should not hold references to data the user may remove, instead,
fetch data from the context each time the script is activated.
- Crashes may not happen every time, they may happen more on some configurations/operating-systems.
* Be aware of memory limits, especially when working with large lists since Blender can crash simply by running out of memory.
* Many hard to fix crashes end up being because of referencing freed data, when removing data be sure not to hold any references to it.
* Modules or classes that remain active while Blender is used, should not hold references to data the user may remove, instead, fetch data from the context each time the script is activated.
* Crashes may not happen every time, they may happen more on some configurations/operating-systems.
..note::
To find the line of your script that crashes you can use the ``faulthandler`` module.
See `faulthandler docs <http://docs.python.org/dev/library/faulthandler.html>`_.
While the crash may be in Blenders C/C++ code,
this can help a lot to track down the area of the script that causes the crash.
While the crash may be in Blenders C/C++ code, this can help a lot to track down the area of the script that causes the crash.
Undo/Redo
@@ -680,36 +572,28 @@ This example shows how you can tell undo changes the memory locations.
>>> hash(bpy.context.object)
-9223372036849951740
As suggested above, simply not holding references to data when Blender is used
interactively by the user is the only way to ensure the script doesn't become unstable.
As suggested above, simply not holding references to data when Blender is used interactively by the user is the only way to ensure the script doesn't become unstable.
Undo & Library Data
^^^^^^^^^^^^^^^^^^^
One of the advantages with Blenders library linking system that undo
can skip checking changes in library data since it is assumed to be static.
One of the advantages with Blenders library linking system that undo can skip checking changes in library data since it is assumed to be static.
Tools in Blender are not allowed to modify library data.
Python however does not enforce this restriction.
This can be useful in some cases, using a script to adjust material values for example.
But its also possible to use a script to make library data point to newly created local data,
which is not supported since a call to undo will remove the local data
but leave the library referencing it and likely crash.
But its also possible to use a script to make library data point to newly created local data, which is not supported since a call to undo will remove the local data but leave the library referencing it and likely crash.
So it's best to consider modifying library data an advanced usage of the API
and only to use it when you know what you're doing.
So it's best to consider modifying library data an advanced usage of the API and only to use it when you know what you're doing.
any references to a meshes vertices/polygons/uvs, armatures bones,
curves points etc cannot be accessed after switching edit-mode.
Switching edit-mode ``bpy.ops.object.mode_set(mode='EDIT')`` / ``bpy.ops.object.mode_set(mode='OBJECT')`` will re-allocate objects data, any references to a meshes vertices/polygons/uvs, armatures bones, curves points etc cannot be accessed after switching edit-mode.
Only the reference to the data its self can be re-accessed, the following example will crash.
@@ -724,8 +608,7 @@ Only the reference to the data its self can be re-accessed, the following exampl
print(polygons)
So after switching edit-mode you need to re-access any object data variables,
the following example shows how to avoid the crash above.
So after switching edit-mode you need to re-access any object data variables, the following example shows how to avoid the crash above.
..code-block::python
@@ -739,15 +622,13 @@ the following example shows how to avoid the crash above.
print(polygons)
These kinds of problems can happen for any functions which re-allocate
the object data but are most common when switching edit-mode.
These kinds of problems can happen for any functions which re-allocate the object data but are most common when switching edit-mode.
Array Re-Allocation
-------------------
When adding new points to a curve or vertices's/edges/polygons to a mesh,
internally the array which stores this data is re-allocated.
When adding new points to a curve or vertices's/edges/polygons to a mesh, internally the array which stores this data is re-allocated.
..code-block::python
@@ -758,20 +639,15 @@ internally the array which stores this data is re-allocated.
# this will crash!
point.co=1.0,2.0,3.0
This can be avoided by re-assigning the point variables after adding the new one or by storing
indices's to the points rather than the points themselves.
This can be avoided by re-assigning the point variables after adding the new one or by storing indices's to the points rather then the points themselves.
The best way is to sidestep the problem altogether add all the points to the curve at once.
This means you don't have to worry about array re-allocation and its faster too
since reallocating the entire array for every point added is inefficient.
The best way is to sidestep the problem altogether add all the points to the curve at once. This means you don't have to worry about array re-allocation and its faster too since reallocating the entire array for every point added is inefficient.
Removing Data
-------------
**Any** data that you remove shouldn't be modified or accessed afterwards,
this includes f-curves, drivers, render layers, timeline markers, modifiers, constraints
along with objects, scenes, groups, bones.. etc.
**Any** data that you remove shouldn't be modified or accessed afterwards, this includes f-curves, drivers, render layers, timeline markers, modifiers, constraints along with objects, scenes, groups, bones.. etc.
The ``remove()`` api calls will invalidate the data they free to prevent common mistakes.
@@ -782,13 +658,12 @@ The following example shows how this precortion works.
mesh=bpy.data.meshes.new(name="MyMesh")
# normally the script would use the mesh here...
bpy.data.meshes.remove(mesh)
print(mesh.name)# <- give an exception rather than crashing:
print(mesh.name)# <- give an exception rather then crashing:
# ReferenceError: StructRNA of type Mesh has been removed
But take care because this is limited to scripts accessing the variable which is removed,
the next example will still crash.
But take care because this is limited to scripts accessing the variable which is removed, the next example will still crash.
..code-block::python
@@ -801,11 +676,9 @@ the next example will still crash.
sys.exit
========
Some Python modules will call ``sys.exit()`` themselves when an error occurs,
while not common behavior this is something to watch out for because it may seem
as if Blender is crashing since ``sys.exit()`` will close Blender immediately.
Some python modules will call ``sys.exit()`` themselves when an error occurs, while not common behavior this is something to watch out for because it may seem as if blender is crashing since ``sys.exit()`` will quit blender immediately.
For example, the ``argparse`` module will print an error and exit if the arguments are invalid.
For example, the ``optparse`` module will print an error and exit if the arguments are invalid.
An ugly way of troubleshooting this is to set ``sys.exit = None`` and see what line of python code is quitting, you could of course replace ``sys.exit`` with your own function but manipulating python in this way is bad practice.
An ugly way of troubleshooting this is to set ``sys.exit = None`` and see what line of Python code is quitting,
you could of course replace ``sys.exit`` with your own function but manipulating Python in this way is bad practice.
This document is to give an understanding of how Python and Blender fit together,
covering some of the functionality that isn't obvious from reading the API reference and example scripts.
This document is to give an understanding of how python and blender fit together, covering some of the functionality that isn't obvious from reading the API reference and example scripts.
Python in Blender
=================
Blender embeds a Python interpreter which is started with Blender and stays active.
This interpreter runs scripts to draw the user interface and is used for some of Blender's internal tools too.
Blender embeds a python interpreter which is started with blender and stays active. This interpreter runs scripts to draw the user interface and is used for some of Blender's internal tools too.
This is a typical Python environment so tutorials on how to write Python scripts
will work running the scripts in Blender too.
Blender provides the :mod:`bpy` module to the Python interpreter.
This module can be imported in a script and gives access to Blender data, classes, and functions.
Scripts that deal with Blender data will need to import this module.
This is a typical python environment so tutorials on how to write python scripts will work running the scripts in blender too. Blender provides the :mod:`bpy` module to the python interpreter. This module can be imported in a script and gives access to blender data, classes, and functions. Scripts that deal with blender data will need to import this module.
Here is a simple example of moving a vertex of the object named **Cube**:
@@ -28,96 +21,84 @@ Here is a simple example of moving a vertex of the object named **Cube**:
When you run this in the interactive console you will see the 3D viewport update.
This modifies Blender's internal data directly. When you run this in the interactive console you will see the 3D viewport update.
The Default Environment
=======================
When developing your own scripts it may help to understand how Blender sets up its Python environment.
Many Python scripts come bundled with Blender and can be used as a reference
because they use the same API that script authors write tools in.
Typical usage for scripts include: user interface, import/export,
scene manipulation, automation, defining your own toolset and customization.
When developing your own scripts it may help to understand how blender sets up its python environment. Many python scripts come bundled with blender and can be used as a reference because they use the same API that script authors write tools in. Typical usage for scripts include: user interface, import/export, scene manipulation, automation, defining your own toolset and customization.
On startup Blender scans the ``scripts/startup/`` directory for Python modules and imports them.
The exact location of this directory depends on your installation.
On startup blender scans the ``scripts/startup/`` directory for python modules and imports them. The exact location of this directory depends on your installation. `See the directory layout docs <http://wiki.blender.org/index.php/Doc:2.6/Manual/Introduction/Installing_Blender/DirectoryLayout>`_
Script Loading
==============
This may seem obvious but it's important to note the difference
between executing a script directly or importing it as a module.
This may seem obvious but it's important to note the difference between executing a script directly or importing it as a module.
Scripts that extend Blender - define classes that exist beyond the scripts execution,
this makes future access to these classes (to unregister for example)
more difficult than importing as a module where class instance is kept
in the module and can be accessed by importing that module later on.
Scripts that extend blender - define classes that exist beyond the scripts execution, this makes future access to these classes (to unregister for example) more difficult than importing as a module where class instance is kept in the module and can be accessed by importing that module later on.
For this reason it's preferable to only use directly execute scripts that don't extend Blender by registering classes.
For this reason it's preferable to only use directly execute scripts that don't extend blender by registering classes.
Here are some ways to run scripts directly in Blender.
Here are some ways to run scripts directly in blender.
- Loaded in the text editor and press **Run Script**.
- Typed or pasted into the interactive console.
- Execute a Python file from the command line with Blender, eg:
* Loaded in the text editor and press **Run Script**.
..code-block::sh
* Typed or pasted into the interactive console.
blender --python /home/me/my_script.py
* Execute a python file from the command line with blender, eg:
``blender --python /home/me/my_script.py``
To run as modules:
- The obvious way, ``import some_module`` command from the text window or interactive console.
- Open as a text block and tick "Register" option, this will load with the blend file.
- copy into one of the directories ``scripts/startup``, where they will be automatically imported on startup.
- define as an addon, enabling the addon will load it as a Python module.
* The obvious way, ``import some_module`` command from the text window or interactive console.
* Open as a text block and tick "Register" option, this will load with the blend file.
* copy into one of the directories ``scripts/startup``, where they will be automatically imported on startup.
* define as an addon, enabling the addon will load it as a python module.
Addons
------
Some of Blenders functionality is best kept optional,
alongside scripts loaded at startup we have addons which are kept in their own directory ``scripts/addons``,
and only load on startup if selected from the user preferences.
Some of blenders functionality is best kept optional, alongside scripts loaded at startup we have addons which are kept in their own directory ``scripts/addons``, and only load on startup if selected from the user preferences.
The only difference between addons and built-in Python modules is that addons must contain a ``bl_info``
variable which Blender uses to read metadata such as name, author, category and URL.
The only difference between addons and built-in python modules is that addons must contain a **bl_info** variable which blender uses to read metadata such as name, author, category and URL.
The user preferences addon listing uses **bl_info** to display information about each addon.
`See Addons <http://wiki.blender.org/index.php/Dev:2.5/Py/Scripts/Guidelines/Addons>`_ for details on the **bl_info** dictionary.
Integration through Classes
===========================
Running Python scripts in the text editor is useful for testing but you'll
want to extend Blender to make tools accessible like other built-in functionality.
Running python scripts in the text editor is useful for testing but you’ll want to extend blender to make tools accessible like other built-in functionality.
The Blender Python api allows integration for:
The blender python api allows integration for:
-:class:`bpy.types.Panel`
-:class:`bpy.types.Menu`
-:class:`bpy.types.Operator`
-:class:`bpy.types.PropertyGroup`
-:class:`bpy.types.KeyingSet`
-:class:`bpy.types.RenderEngine`
*:class:`bpy.types.Panel`
*:class:`bpy.types.Menu`
*:class:`bpy.types.Operator`
*:class:`bpy.types.PropertyGroup`
*:class:`bpy.types.KeyingSet`
*:class:`bpy.types.RenderEngine`
This is intentionally limited. Currently, for more advanced features such as mesh modifiers,
object types, or shader nodes, C/C++ must be used.
This is intentionally limited. Currently, for more advanced features such as mesh modifiers, object types, or shader nodes, C/C++ must be used.
For Python integration Blender defines methods which are common to all types.
This works by creating a Python subclass of a Blender class which contains variables and functions
specified by the parent class which are pre-defined to interface with Blender.
For python intergration Blender defines methods which are common to all types. This works by creating a python subclass of a Blender class which contains variables and functions specified by the parent class which are pre-defined to interface with Blender.
For example:
@@ -134,20 +115,15 @@ For example:
bpy.utils.register_class(SimpleOperator)
First note that we subclass a member of :mod:`bpy.types`,
this is common for all classes which can be integrated with Blender and
used so we know if this is an Operator and not a Panel when registering.
First note that we subclass a member of :mod:`bpy.types`, this is common for all classes which can be integrated with blender and used so we know if this is an Operator and not a Panel when registering.
Both class properties start with a ``bl_`` prefix.
This is a convention used to distinguish Blender properties from those you add yourself.
Both class properties start with a **bl_** prefix. This is a convention used to distinguish blender properties from those you add yourself.
Next see the execute function, which takes an instance of the operator and the current context.
A common prefix is not used for functions.
Next see the execute function, which takes an instance of the operator and the current context. A common prefix is not used for functions.
Lastly the register function is called, this takes the class and loads it into Blender. See `Class Registration`_.
Lastly the register function is called, this takes the class and loads it into blender. See `Class Registration`_.
Regarding inheritance, Blender doesn't impose restrictions on the kinds of class inheritance used,
the registration checks will use attributes and functions defined in parent classes.
Regarding inheritance, blender doesn't impose restrictions on the kinds of class inheritance used, the registration checks will use attributes and functions defined in parent classes.
class mix-in example:
@@ -165,20 +141,11 @@ class mix-in example:
bpy.utils.register_class(SimpleOperator)
Notice these classes don't define an ``__init__(self)`` function.
While ``__init__()`` and ``__del__()`` will be called if defined,
the class instances lifetime only spans the execution.
So a panel for example will have a new instance for every redraw,
for this reason there is rarely a cause to store variables in the panel instance.
Instead, persistent variables should be stored in Blenders
ata so that the state can be restored when Blender is restarted.
Notice these classes don't define an ``__init__(self)`` function. While ``__init__()`` and ``__del__()`` will be called if defined, the class instances lifetime only spans the execution. So a panel for example will have a new instance for every redraw, for this reason there is rarely a cause to store variables in the panel instance. Instead, persistent variables should be stored in Blenders data so that the state can be restored when blender is restarted.
..note::
..note:: Modal operators are an exception, keeping their instance variable as blender runs, see modal operator template.
Modal operators are an exception, keeping their instance variable as Blender runs, see modal operator template.
So once the class is registered with Blender, instancing the class and calling the functions is left up to Blender.
In fact you cannot instance these classes from the script as you would expect with most Python API's.
So once the class is registered with blender, instancing the class and calling the functions is left up to blender. In fact you cannot instance these classes from the script as you would expect with most python API's.
To run operators you can call them through the operator api, eg:
@@ -187,8 +154,7 @@ To run operators you can call them through the operator api, eg:
importbpy
bpy.ops.object.simple_operator()
User interface classes are given a context in which to draw, buttons window, file header, toolbar etc,
then they are drawn when that area is displayed so they are never called by Python scripts directly.
User interface classes are given a context in which to draw, buttons window, file header, toolbar etc, then they are drawn when that area is displayed so they are never called by python scripts directly.
Registration
@@ -198,10 +164,9 @@ Registration
Module Registration
-------------------
Blender modules loaded at startup require ``register()`` and ``unregister()`` functions.
These are the *only* functions that Blender calls from your code, which is otherwise a regular Python module.
Blender modules loaded at startup require ``register()`` and ``unregister()`` functions. These are the *only* functions that blender calls from your code, which is otherwise a regular python module.
A simple Blender/Python module can look like this:
A simple blender/python module can look like this:
..code-block::python
@@ -219,16 +184,12 @@ A simple Blender/Python module can look like this:
if__name__=="__main__":
register()
These functions usually appear at the bottom of the script containing class registration sometimes adding menu items.
You can also use them for internal purposes setting up data for your own tools but take care
since register won't re-run when a new blend file is loaded.
These functions usually appear at the bottom of the script containing class registration sometimes adding menu items. You can also use them for internal purposes setting up data for your own tools but take care since register won't re-run when a new blend file is loaded.
The register/unregister calls are used so it's possible to toggle addons and reload scripts while Blender runs.
If the register calls were placed in the body of the script, registration would be called on import,
meaning there would be no distinction between importing a module or loading its classes into Blender.
The register/unregister calls are used so it's possible to toggle addons and reload scripts while blender runs.
If the register calls were placed in the body of the script, registration would be called on import, meaning there would be no distinction between importing a module or loading its classes into blender.
This becomes problematic when a script imports classes from another module
making it difficult to manage which classes are being loaded and when.
This becomes problematic when a script imports classes from another module making it difficult to manage which classes are being loaded and when.
The last 2 lines are only for testing:
@@ -238,24 +199,19 @@ The last 2 lines are only for testing:
register()
This allows the script to be run directly in the text editor to test changes.
This ``register()`` call won't run when the script is imported as a module
since ``__main__`` is reserved for direct execution.
This ``register()`` call won't run when the script is imported as a module since ``__main__`` is reserved for direct execution.
Class Registration
------------------
Registering a class with Blender results in the class definition being loaded into Blender,
where it becomes available alongside existing functionality.
Registering a class with blender results in the class definition being loaded into blender, where it becomes available alongside existing functionality.
Once this class is loaded you can access it from :mod:`bpy.types`,
using the bl_idname rather than the classes original name.
Once this class is loaded you can access it from :mod:`bpy.types`, using the bl_idname rather than the classes original name.
When loading a class, Blender performs sanity checks making sure all required properties and functions are found,
that properties have the correct type, and that functions have the right number of arguments.
When loading a class, blender performs sanity checks making sure all required properties and functions are found, that properties have the correct type, and that functions have the right number of arguments.
Mostly you will not need concern yourself with this but if there is a problem
with the class definition it will be raised on registering:
Mostly you will not need concern yourself with this but if there is a problem with the class definition it will be raised on registering:
Using the function arguments ``def execute(self, context, spam)``, will raise an exception:
@@ -269,13 +225,9 @@ Using ``bl_idname = 1`` will raise.
Multiple-Classes
^^^^^^^^^^^^^^^^
Loading classes into Blender is described above,
for simple cases calling :mod:`bpy.utils.register_class` (SomeClass) is sufficient,
but when there are many classes or a packages submodule has its own
classes it can be tedious to list them all for registration.
Loading classes into blender is described above, for simple cases calling :mod:`bpy.utils.register_class` (SomeClass) is sufficient, but when there are many classes or a packages submodule has its own classes it can be tedious to list them all for registration.
For more convenient loading/unloading :mod:`bpy.utils.register_module` (module)
and :mod:`bpy.utils.unregister_module` (module) functions exist.
For more convenient loading/unloading :mod:`bpy.utils.register_module` (module) and :mod:`bpy.utils.unregister_module` (module) functions exist.
A script which defines many of its own operators, panels menus etc. you only need to write:
@@ -287,19 +239,13 @@ A script which defines many of its own operators, panels menus etc. you only nee
defunregister():
bpy.utils.unregister_module(__name__)
Internally Blender collects subclasses on registrable types, storing them by the module in which they are defined.
By passing the module name to :mod:`bpy.utils.register_module`
Blender can register all classes created by this module and its submodules.
Internally blender collects subclasses on registrable types, storing them by the module in which they are defined. By passing the module name to :mod:`bpy.utils.register_module` blender can register all classes created by this module and its submodules.
Inter Classes Dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^
When customizing Blender you may want to group your own settings together,
after all, they will likely have to co-exist with other scripts.
To group these properties classes need to be defined,
for groups within groups or collections within groups
you can find yourself having to deal with order of registration/unregistration.
When customizing blender you may want to group your own settings together, after all, they will likely have to co-exist with other scripts. To group these properties classes need to be defined, for groups within groups or collections within groups you can find yourself having to deal with order of registration/unregistration.
Custom properties groups are themselves classes which need to be registered.
@@ -365,9 +311,7 @@ Say you want to store material settings for a custom engine.
Manipulating Classes
^^^^^^^^^^^^^^^^^^^^
Properties can be added and removed as Blender runs,
normally happens on register or unregister but for some
special cases it may be useful to modify types as the script runs.
Properties can be added and removed as blender runs, normally happens on register or unregister but for some special cases it may be useful to modify types as the script runs.
For example:
@@ -397,8 +341,7 @@ This works just as well for PropertyGroup subclasses you define yourself.
Dynamic Defined-Classes (Advanced)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In some cases the specifier for data may not be in Blender,
renderman shader definitions for example and it may be useful to define types and remove them on the fly.
In some cases the specifier for data may not be in blender, renderman shader definitions for example and it may be useful to define types and remove them on the fly.
..code-block::python
@@ -417,8 +360,7 @@ renderman shader definitions for example and it may be useful to define types an
..note::
``type()`` is called to define the class.
This is an alternative syntax for class creation in Python, better suited to constructing classes dynamically.
Notice ``type()`` is called to define the class. This is an alternative syntax for class creation in python, better suited to constructing classes dynamically.
@@ -33,15 +32,13 @@ The Blender/Python API **can't** (yet)...
Before Starting
===============
This document isn't intended to fully cover each topic.
Rather, its purpose is to familiarize you with Blender Python API.
This document isn't intended to fully cover each topic. Rather, its purpose is to familiarize you with Blender Python API.
A quick list of helpful things to know before starting:
- Blender uses Python 3.x; some online documentation still assumes 2.x.
- The interactive console is great for testing one-liners.
It also has autocompletion so you can inspect the API quickly.
- The interactive console is great for testing one-liners, It also has autocompletion so you can inspect the API quickly.
- Button tool tips show Python attributes and operator names.
- Right clicking on buttons and menu items directly links to API documentation.
- For more examples, the text menu has a templates section where some example operators can be found.
@@ -54,19 +51,15 @@ A quick list of helpful things to know before starting:
Running Scripts
---------------
The two most common ways to execute Python scripts are using the built-in
text editor or entering commands in the Python console.
The two most common ways to execute Python scripts are using the built-in text editor or entering commands in the Python console.
Both the *Text Editor* and *Python Console* are space types you can select from the view header.
Both the **Text Editor** and **Python Console** are space types you can select from the view header.
Rather than manually configuring your spaces for Python development,
you may prefer to use the *Scripting* screen, included default with Blender,
accessible from the top headers screen selector.
Rather then manually configuring your spaces for Python development, you may prefer to use the **Scripting** screen, included default with Blender, accessible from the top headers screen selector.
From the text editor you can open ``.py`` files or paste then from the clipboard, then test using *Run Script*.
From the text editor you can open ``.py`` files or paste then from the clipboard, then test using **Run Script**.
The Python Console is typically used for typing in snippets and for testing to get immediate feedback,
but can also have entire scripts pasted into it.
The Python Console is typically used for typing in snippets and for testing to get immediate feedback, but can also have entire scripts pasted into it.
Scripts can also run from the command line with Blender but to learn Blender/Python this isn't essential.
@@ -80,11 +73,9 @@ Data Access
Accessing DataBlocks
^^^^^^^^^^^^^^^^^^^^
Python accesses Blender's data in the same way as the animation system and user interface;
this implies that any setting that can be changed via a button can also be changed from Python.
Python accesses Blender's data in the same way as the animation system and user interface; this implies that any setting that can be changed via a button can also be changed from Python.
Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`.
This gives access to library data. For example:
Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`. This gives access to library data. For example:
>>> bpy.data.objects
<bpy_collection[3], BlendDataObjects>
@@ -101,8 +92,7 @@ About Collections
You'll notice that an index as well as a string can be used to access members of the collection.
Unlike Python's dictionaries, both methods are acceptable;
however, the index of a member may change while running Blender.
Unlike Python's dictionaries, both methods are acceptable; however, the index of a member may change while running Blender.
@@ -117,10 +107,7 @@ however, the index of a member may change while running Blender.
Accessing Attributes
^^^^^^^^^^^^^^^^^^^^
Once you have a data block, such as a material, object, groups etc.,
its attributes can be accessed much like you would change a setting using the graphical interface.
In fact, the tooltip for each button also displays the Python attribute
which can help in finding what settings to change in a script.
Once you have a data block, such as a material, object, groups etc., its attributes can be accessed much like you would change a setting using the graphical interface. In fact, the tooltip for each button also displays the Python attribute which can help in finding what settings to change in a script.
>>> bpy.data.objects[0].name
'Camera'
@@ -132,8 +119,7 @@ which can help in finding what settings to change in a script.
bpy.data.materials['MyMaterial']
For testing what data to access it's useful to use the "Console", which is its own space type.
This supports auto-complete, giving you a fast way to dig into different data in your file.
For testing what data to access it's useful to use the "Console", which is its own space type. This supports auto-complete, giving you a fast way to dig into different data in your file.
Example of a data path that can be quickly found via the console:
@@ -146,8 +132,7 @@ Example of a data path that can be quickly found via the console:
Data Creation/Removal
^^^^^^^^^^^^^^^^^^^^^
Those of you familiar with other Python API's may be surprised that
new datablocks in the bpy API can't be created by calling the class:
Those of you familiar with other Python API's may be surprised that new datablocks in the bpy API can't be created by calling the class:
>>> bpy.types.Mesh()
Traceback (most recent call last):
@@ -156,8 +141,7 @@ new datablocks in the bpy API can't be created by calling the class:
This is an intentional part of the API design.
The Blender/Python API can't create Blender data that exists outside the main Blender database
(accessed through :mod:`bpy.data`), because this data is managed by Blender (save/load/undo/append... etc).
The Blender/Python API can't create Blender data that exists outside the main Blender database (accessed through :mod:`bpy.data`), because this data is managed by Blender (save/load/undo/append... etc).
Data is added and removed via methods on the collections in :mod:`bpy.data`, eg:
@@ -171,10 +155,8 @@ Data is added and removed via methods on the collections in :mod:`bpy.data`, eg:
Custom Properties
^^^^^^^^^^^^^^^^^
Python can access properties on any datablock that has an ID
(data that can be linked in and accessed from :mod:`bpy.data`.
When assigning a property, you can make up your own names,
these will be created when needed or overwritten if they exist.
Python can access properties on any datablock that has an ID (data that can be linked in and accessed from :mod:`bpy.data`.
When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.
This data is saved with the blend file and copied with objects.
@@ -210,10 +192,8 @@ These properties are valid outside of Python. They can be animated by curves or
Context
-------
While it's useful to be able to access data directly by name or as a list,
it's more common to operate on the user's selection.
The context is always available from ``bpy.context`` and can be used to get the active object, scene,
tool settings along with many other attributes.
While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection.
The context is always available from ``bpy.context`` and can be used to get the active object, scene, tool settings along with many other attributes.
Common-use cases:
@@ -221,9 +201,7 @@ Common-use cases:
>>> bpy.context.selected_objects
>>> bpy.context.visible_bones
Note that the context is read-only.
These values cannot be modified directly,
though they may be changed by running API functions or by using the data API.
Note that the context is read-only. These values cannot be modified directly, though they may be changed by running API functions or by using the data API.
So ``bpy.context.object = obj`` will raise an error.
@@ -231,8 +209,7 @@ But ``bpy.context.scene.objects.active = obj`` will work as expected.
The context attributes change depending on where they are accessed.
The 3D view has different context members than the console,
so take care when accessing context attributes that the user state is known.
The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known.
See :mod:`bpy.context` API reference.
@@ -240,9 +217,7 @@ See :mod:`bpy.context` API reference.
Operators (Tools)
-----------------
Operators are tools generally accessed by the user from buttons, menu items or key shortcuts.
From the user perspective they are a tool but Python can run these with its own settings
through the :mod:`bpy.ops` module.
Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspective they are a tool but Python can run these with its own settings through the :mod:`bpy.ops` module.
Examples:
@@ -255,16 +230,14 @@ Examples:
..note::
The menu item: :menuselection:`Help --> Operator Cheat Sheet`
gives a list of all operators and their default values in Python syntax, along with the generated docs.
The menu item: :menuselection:`Help --> Operator Cheat Sheet` gives a list of all operators and their default values in Python syntax, along with the generated docs.
This is a good way to get an overview of all Blender's operators.
Operator Poll()
^^^^^^^^^^^^^^^
Many operators have a "poll" function which may check that the cursor
is in a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc).
Many operators have a "poll" function which may check that the mouse is in a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc).
When an operator's poll function fails within Python, an exception is raised.
For example, calling ``bpy.ops.view3d.render_border()`` from the console raises the following error:
@@ -275,8 +248,7 @@ For example, calling ``bpy.ops.view3d.render_border()`` from the console raises
In this case the context must be the 3d view with an active camera.
To avoid using try/except clauses wherever operators are called you can call the operators
own ``poll()`` function to check if it can run in the current context.
To avoid using try/except clauses wherever operators are called you can call the operators own .poll() function to check if it can run in the current context.
@@ -367,8 +334,7 @@ Blender's Python API can be split up into 3 categories.
Native Types
------------
In simple cases returning a number or a string as a custom type would be cumbersome,
so these are accessed as normal Python types.
In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal Python types.
- Blender float/int/boolean -> float/int/boolean
- Blender enumerator -> string
@@ -393,8 +359,7 @@ Used for Blender datablocks and collections: :class:`bpy.types.bpy_struct`
For data that contains its own attributes groups/meshes/bones/scenes... etc.
There are 2 main types that wrap Blenders data, one for datablocks
(known internally as ``bpy_struct``), another for properties.
There are 2 main types that wrap Blenders data, one for datablocks (known internally as ``bpy_struct``), another for properties.
>>> bpy.context.object
bpy.data.objects['Cube']
@@ -410,9 +375,7 @@ Mathutils Types
Used for vectors, quaternion, eulers, matrix and color types, accessible from :mod:`mathutils`
Some attributes such as :class:`bpy.types.Object.location`,
:class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location`
can be accessed as special math types which can be used together and manipulated in various useful ways.
Some attributes such as :class:`bpy.types.Object.location`,:class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location` can be accessed as special math types which can be used together and manipulated in various useful ways.
Example of a matrix, vector multiplication:
@@ -447,9 +410,7 @@ Animation
There are 2 ways to add keyframes through Python.
The first is through key properties directly, which is similar to inserting a keyframe from the button as a user.
You can also manually create the curves and keyframe data, then set the path to the property.
Here are examples of both methods.
The first is through key properties directly, which is similar to inserting a keyframe from the button as a user. You can also manually create the curves and keyframe data, then set the path to the property. Here are examples of both methods.
Both examples insert a keyframe on the active object's Z axis.
Here are various suggestions that you might find useful when writing scripts.
Some of these are just Python features that scripters may not have thought to use with Blender,
others are Blender specific.
Some of these are just python features that scripters may not have thought to use with blender, others are blender specific.
.._use_the_terminal:
@@ -14,21 +12,18 @@ others are Blender specific.
Use The Terminal
================
When writing Python scripts, it's useful to have a terminal open,
this is not the built-in Python console but a terminal application which is used to start Blender.
When writing python scripts, it's useful to have a terminal open, this is not the built-in python console but a terminal application which is used to start blender.
There are 3 main uses for the terminal, these are:
- You can see the output of ``print()`` as your script runs, which is useful to view debug info.
- The error trace-back is printed in full to the terminal which won't always generate an error popup in
Blender's user interface (depending on how the script is executed).
- If the script runs for too long or you accidentally enter an infinite loop,
:kbd:`Ctrl-C` in the terminal (:kbd:`Ctrl-Break` on Windows) will quit the script early.
* You can see the output of ``print()`` as your script runs, which is useful to view debug info.
* The error trace-back is printed in full to the terminal which won't always generate an error popup in blender's user interface (depending on how the script is executed).
* If the script runs for too long or you accidentally enter an infinite loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early.
..note::
For Linux and OSX users this means starting the terminal first, then running Blender from within it.
On Windows the terminal can be enabled from the help menu.
For Linux and OSX users this means starting the terminal first, then running blender from within it. On Windows the terminal can be enabled from the help menu.
Interface Tricks
@@ -38,56 +33,43 @@ Interface Tricks
Access Operator Commands
------------------------
You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...])`` command
to run that button, a handy (hidden) feature is that you can press :kbd:`Ctrl-C` over
any menu item/button to copy this command into the clipboard.
You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops``... command to run that button, a handy (hidden) feature is that you can press Ctrl+C over any menu item/button to copy this command into the clipboard.
Access Data Path
----------------
To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away.
To get this quickly you can right click on the setting and select select **Copy Data Path**,
To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away. To get this quickly you can right click on the setting and select select **Copy Data Path**,
if this can't be generated, only the property name is copied.
..note::
This uses the same method for creating the animation path used by
This uses the same method for creating the animation path used by:class:`bpy.types.FCurve.data_path` and :class:`bpy.types.DriverTarget.data_path` drivers.
.._info_show_all_operators:
.._info_show_all_operators
Show All Operators
==================
While Blender logs operators in the Info space,
this only reports operators with the ``REGISTER`` option enabeld so as not to flood the *Info* view
with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``.
While blender logs operators in the Info space, this only reports operators with the ``REGISTER`` option enabeld so as not to flood the Info view with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``.
However, for testing it can be useful to see **every** operator called in a terminal,
do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting Blender
or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running.
However, for testing it can be useful to see **every** operator called in a terminal, do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting blender or by setting :mod:`bpy.app.debug_wm` to True while blender is running.
Use an External Editor
======================
Blenders text editor is fine for small changes and writing tests but its not full featured,
for larger projects you'll probably want to use a standalone editor or Python IDE.
Blenders text editor is fine for small changes and writing tests but its not full featured, for larger projects you'll probably want to use a standalone editor or python IDE.
Editing a text file externally and having the same text open in Blender does work but isn't that optimal
so here are 2 ways you can easily use an external file from Blender.
Using the following examples you'll still need textblock in Blender to execute,
but reference an external file rather than including it directly.
Editing a text file externally and having the same text open in blender does work but isn't that optimal so here are 2 ways you can easily use an external file from blender.
Using the following examples you'll still need textblock in blender to execute, but reference an external file rather then including it directly.
Executing External Scripts
--------------------------
This is the equivalent to running the script directly, referencing a scripts path from a 2 line text-block.
This is the equivalent to running the script directly, referencing a scripts path from a 2 line textblock.
..code-block::python
@@ -114,23 +96,18 @@ This example shows loading a script in as a module and executing a module functi
..code-block::python
importmyscript
importimportlib
importimp
importlib.reload(myscript)
imp.reload(myscript)
myscript.main()
Notice that the script is reloaded every time, this forces use of the modified version,
otherwise the cached one in ``sys.modules`` would be used until Blender was restarted.
Notice that the script is reloaded every time, this forces use of the modified version, otherwise the cached one in ``sys.modules`` would be used until blender was restarted.
The important difference between this and executing the script directly is it
has to call a function in the module, in this case ``main()`` but it can be any function,
an advantage with this is you can pass arguments to the function from this
small script which is often useful for testing different settings quickly.
The important difference between this and executing the script directly is it has to call a function in the module, in this case ``main()`` but it can be any function, an advantage with this is you can pass arguments to the function from this small script which is often useful for testing different settings quickly.
The other issue with this is the script has to be in Pythons module search path.
While this is not best practice - for testing you can extend the search path,
this example adds the current blend files directory to the search path, then loads the script as a module.
The other issue with this is the script has to be in pythons module search path.
While this is not best practice - for testing you can extend the search path, this example adds the current blend files directory to the search path, then loads the script as a module.
..code-block::python
@@ -143,94 +120,79 @@ this example adds the current blend files directory to the search path, then loa
sys.path.append(blend_dir)
importmyscript
importimportlib
importlib.reload(myscript)
importimp
imp.reload(myscript)
myscript.main()
Don't Use Blender!
==================
While developing your own scripts Blenders interface can get in the way,
manually reloading, running the scripts, opening file import etc. adds overhead.
While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc. adds overhead.
For scripts that are not interactive it can end up being more efficient not to use
Blenders interface at all and instead execute the script on the command line.
For scripts that are not interactive it can end up being more efficient not to use blenders interface at all and instead execute the script on the command line.
..code-block::sh
..code-block::python
blender--background--pythonmyscript.py
You might want to run this with a blend file so the script has some data to operate on.
Depending on your setup you might have to enter the full path to the Blender executable.
Depending on your setup you might have to enter the full path to the blender executable.
Once the script is running properly in background mode, you'll want to check the output of the script,
this depends completely on the task at hand however here are some suggestions.
Once the script is running properly in background mode, you'll want to check the output of the script, this depends completely on the task at hand however here are some suggestions.
- render the output to an image, use an image viewer and keep writing over the same image each time.
- save a new blend file, or export the file using one of Blenders exporters.
- if the results can be displayed as text - print them or write them to a file.
* render the output to an image, use an image viewer and keep writing over the same image each time.
* save a new blend file, or export the file using one of blenders exporters.
* if the results can be displayed as text - print them or write them to a file.
While this can take a little time to setup, it can be well worth the effort
to reduce the time it takes to test changes - you can even have
Blender running the script every few seconds with a viewer updating the results,
so no need to leave your text editor to see changes.
This can take a little time to setup, but it can be well worth the effort to reduce the time it takes to test changes - you can even have blender running the script ever few seconds with a viewer updating the results, so no need to leave your text editor to see changes.
Use External Tools
==================
When there are no readily available Python modules to perform specific tasks it's
worth keeping in mind you may be able to have Python execute an external command
on your data and read the result back in.
When there are no readily available python modules to perform specific tasks it's worth keeping in mind you may be able to have python execute an external command on your data and read the result back in.
Using external programs adds an extra dependency and may limit who can use the script
but to quickly setup your own custom pipeline or writing one-off scripts this can be handy.
Using external programs adds an extra dependency and may limit who can use the script but to quickly setup your own custom pipeline or writing one-off scripts this can be handy.
Examples include:
- Run The Gimp in batch mode to execute custom scripts for advanced image processing.
- Write out 3D models to use external mesh manipulation tools and read back in the results.
- Convert files into recognizable formats before reading.
* Run The Gimp in batch mode to execute custom scripts for advanced image processing.
* Write out 3D models to use external mesh manipulation tools and read back in the results.
* Convert files into recognizable formats before reading.
Bundled Python & Extensions
===========================
The Blender releases distributed from blender.org include a complete Python installation on all platforms,
this has the disadvantage that any extensions you have installed in your systems Python wont be found by Blender.
The Blender releases distributed from blender.org include a complete python installation on all platforms, this has the disadvantage that any extensions you have installed in your systems python wont be found by blender.
There are 2 ways around this:
- remove Blender Python sub-directory, Blender will then fallback on the systems Python and use that instead
..warning::
* remove blender python sub-directory, blender will then fallback on the systems python and use that instead**python version must match the one that blender comes with**.
The Python version must match the one that Blender comes with.
- copy the extensions into Blender's Python sub-directory so Blender can access them,
you could also copy the entire Python installation into Blenders sub-directory,
replacing the one Blender comes with.
This works as long as the Python versions match and the paths are created in the same relative locations.
Doing this has the advantage that you can redistribute this bundle to others with Blender and/or the game player,
including any extensions you rely on.
* copy the extensions into blender's python sub-directory so blender can access them, you could also copy the entire python installation into blenders sub-directory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on.
Drop Into a Python Interpreter in Your Script
=============================================
In the middle of a script you may want to inspect some variables,
run some function and generally dig about to see whats going on.
In the middle of a script you may want to inspect some variables, run some function and generally dig about to see whats going on.
..code-block::python
@@ -255,13 +217,10 @@ The next example is an equivalent single line version of the script above which
``code.interact`` can be added at any line in the script
and will pause the script an launch an interactive interpreter in the terminal,
when you're done you can quit the interpreter and the script will continue execution.
``code.interact`` can be added at any line in the script and will pause the script an launch an interactive interpreter in the terminal, when you're done you can quit the interpreter and the script will continue execution.
If you have **IPython** installed you can use its``embed()`` function which uses the current namespace.
The IPython prompt has auto-complete and some useful features that the standard Python eval-loop doesn't have.
If you have **IPython** installed you can use their``embed()`` function which will implicitly use the current namespace, this has autocomplete and some useful features that the standard python eval-loop doesn't have.
..code-block::python
@@ -269,7 +228,7 @@ The IPython prompt has auto-complete and some useful features that the standard
IPython.embed()
Admittedly this highlights the lack of any Python debugging support built into Blender, but its still handy to know.
Admittedly this highlights the lack of any python debugging support built into blender, but its still handy to know.
..note::
@@ -283,32 +242,27 @@ Advanced
Blender as a module
-------------------
From a Python perspective it's nicer to have everything as an extension
which lets the Python script combine many components.
From a python perspective it's nicer to have everything as an extension which lets the python script combine many components.
Advantages include:
- you can use external editors/IDE's with Blenders Python API and execute scripts within the IDE
(step over code, inspect variables as the script runs).
- editors/IDE's can auto complete Blender modules & variables.
- existing scripts can import Blender API's without having to run inside Blender.
* you can use external editors/IDE's with blenders python API and execute scripts within the IDE (step over code, inspect variables as the script runs).
* editors/IDE's can auto complete blender modules & variables.
* existing scripts can import blender API's without having to run inside blender.
This is marked advanced because to run Blender as a Python module requires a special build option.
This is marked advanced because to run blender as a python module requires a special build option.
For instructions on building see
`Building Blender as a Python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
For instructions on building see`Building blender as a python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
Python Safety (Build Option)
----------------------------
Since it's possible to access data which has been removed (see Gotcha's),
this can be hard to track down the cause of crashes.
Since it's possible to access data which has been removed (see Gotcha's), this can be hard to track down the cause of crashes.
To raise Python exceptions on accessing freed data (rather than crashing),
enable the CMake build option ``WITH_PYTHON_SAFETY``.
This enables data tracking which makes data access about 2x slower
which is why the option isn't enabled in release builds.
To raise python exceptions on accessing freed data (rather then crashing), enable the CMake build option WITH_PYTHON_SAFETY.
This enables data tracking which makes data access about 2x slower which is why the option is not enabled in release builds.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
