Revision: 52804
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=52804
Author: campbellbarton
Date: 2012-12-07 05:27:09 +0000 (Fri, 07 Dec 2012)
Log Message:
-----------
Add 2 documents to the python api reference.
- Blender/Python Addon Tutorial: a step by step guide on how to write an addon
from scratch
- Blender/Python API Reference Usage: examples of how to use the API reference
docs
Thanks to John Nyquist for editing these docs and giving feedback.
Modified Paths:
--------------
trunk/blender/doc/python_api/rst/info_gotcha.rst
trunk/blender/doc/python_api/rst/info_overview.rst
trunk/blender/doc/python_api/rst/info_quickstart.rst
trunk/blender/doc/python_api/rst/info_tips_and_tricks.rst
trunk/blender/doc/python_api/sphinx_doc_gen.py
Added Paths:
-----------
trunk/blender/doc/python_api/rst/info_api_reference.rst
trunk/blender/doc/python_api/rst/info_tutorial_addon.rst
Added: trunk/blender/doc/python_api/rst/info_api_reference.rst
===================================================================
--- trunk/blender/doc/python_api/rst/info_api_reference.rst
(rev 0)
+++ trunk/blender/doc/python_api/rst/info_api_reference.rst 2012-12-07
05:27:09 UTC (rev 52804)
@@ -0,0 +1,305 @@
+
+*******************
+Reference API Usage
+*******************
+
+Blender has many interlinking data types which have an auto-generated
reference api which often has the information
+you need to write a script, but can be difficult to use.
+
+This document is designed to help you understand how to use the reference api.
+
+
+Reference API Scope
+===================
+
+The reference API covers :mod:`bpy.types`, which stores types accessed via
:mod:`bpy.context` - *The user context*
+or :mod:`bpy.data` - *Blend file data*.
+
+Other modules such as :mod:`bge`, :mod:`bmesh` and :mod:`aud` are not using
Blenders data API
+so this document doesn't apply to those modules.
+
+
+Data Access
+===========
+
+The most common case for using the reference API is to find out how to access
data in the blend file.
+
+Before going any further its best to be aware of ID Data-Blocks in Blender
since you will often find properties
+relative to them.
+
+
+ID Data
+-------
+
+ID Data-Blocks are used in Blender as top-level data containers.
+
+From the user interface this isn't so obvious, but when developing you need to
know about ID Data-Blocks.
+
+ID data types include Scene, Group, Object, Mesh, Screen, World, Armature,
Image and Texture.
+for a full list see the sub-classes of :class:`bpy.types.ID`
+
+Here are some characteristics ID Data-Blocks share.
+
+- ID's are blend file data, so loading a new blend file reloads an entire new
set of Data-Blocks.
+- ID's can be accessed in Python from ``bpy.data.*``
+- Each data-block has a unique ``.name`` attribute, displayed in the interface.
+- Animation data is stored in ID's ``.animation_data``.
+- ID's are the only data types that can be linked between blend files.
+- ID's can be added/copied and removed via Python.
+- ID's have their own garbage-collection system which frees unused ID's when
saving.
+- When a data-block has a reference to some external data, this is typically
an ID Data-Block.
+
+
+Simple Data Access
+------------------
+
+Lets start with a simple case, say you wan't a python script to adjust the
objects location.
+
+Start by finding this setting in the interface ``Properties Window -> Object
-> Transform -> Location``
+
+From the button you can right click and select **Online Python Reference**,
this will link you to:
+:class:`bpy.types.Object.location`
+
+Being an API reference, this link often gives little more information then the
tool-tip, though some of the pages
+include examples (normally at the top of the page).
+
+At this point you may say *Now what?* - you know that you have to use
``.location`` and that its an array of 3 floats
+but you're still left wondering how to access this in a script.
+
+So the next step is to find out where to access objects, go down to the bottom
of the page to the **References**
+section, for objects there are many references, but one of the most common
places to access objects is via the context.
+
+It's easy to be overwhelmed at this point since there ``Object`` get
referenced in so many places - modifiers,
+functions, textures and constraints.
+
+But if you want to access any data the user has selected
+you typically only need to check the :mod:`bpy.context` references.
+
+Even then, in this case there are quite a few though if you read over these -
most are mode specific.
+If you happen to be writing a tool that only runs in weight paint mode, then
using ``weight_paint_object``
+would be appropriate.
+However to access an item the user last selected, look for the ``active``
members,
+Having access to a single active member the user selects is a convention in
Blender: eg. ``active_bone``,
+``active_pose_bone``, ``active_node`` ... and in this case we can use -
``active_object``.
+
+
+So now we have enough information to find the location of the active object.
+
+.. code-block:: python
+
+ bpy.context.active_object.location
+
+You can type this into the python console to see the result.
+
+The other common place to access objects in the reference is
:class:`bpy.types.BlendData.objects`.
+
+.. note::
+
+ This is **not** listed as :mod:`bpy.data.objects`,
+ this is because :mod:`bpy.data` is an instance of the
:class:`bpy.types.BlendData` class,
+ so the documentation points there.
+
+
+With :mod:`bpy.data.objects`, this is a collection of objects so you need to
access one of its members.
+
+.. code-block:: python
+
+ bpy.data.objects["Cube"].location
+
+
+Nested Properties
+-----------------
+
+The previous example is quite straightforward because ``location`` is a
property of ``Object`` which can be accessed
+from the context directly.
+
+Here are some more complex examples:
+
+.. code-block:: python
+
+ # access a render layers samples
+ bpy.context.scene.render.layers["RenderLayer"].samples
+
+ # access to the current weight paint brush size
+ bpy.context.tool_settings.weight_paint.brush.size
+
+ # check if the window is fullscreen
+ bpy.context.window.screen.show_fullscreen
+
+
+As you can see there are times when you want to access data which is nested
+in a way that causes you to go through a few indirections.
+
+The properties are arranged to match how data is stored internally (in
blenders C code) which is often logical but
+not always quite what you would expect from using Blender.
+
+So this takes some time to learn, it helps you understand how data fits
together in Blender which is important
+to know when writing scripts.
+
+
+When starting out scripting you will often run into the problem where you're
not sure how to access the data you want.
+
+There are a few ways to do this.
+
+- Use the Python console's auto-complete to inspect properties. *This can be
hit-and-miss but has the advantage
+ that you can easily see the values of properties and assign them to
interactively see the results.*
+
+- Copy the Data-Path from the user interface. *Explained further in :ref:`Copy
Data Path <info_data_path_copy>`*
+
+- Using the documentation to follow references. *Explained further in
:ref:`Indirect Data Access <info_data_path_indirect>`*
+
+
+.. _info_data_path_copy
+
+Copy Data Path
+--------------
+
+Blender can compute the Python string to a property which is shown in the
tool-tip, on the line below ``Python: ...``,
+This saves having to use the API reference to click back up the references to
find where data is accessed from.
+
+There is a user-interface feature to copy the data-path which gives the path
from an :class:`bpy.types.ID` data-block,
+to its property.
+
+To see how this works we'll get the path to the Subdivision-Surface modifiers
subdivision setting.
+
+Start with the default scene and select the **Modifiers** tab, then add a
**Subdivision-Surface** modifier to the cube.
+
+Now hover your mouse over the button labeled **View**, The tool-tip includes
:class:`bpy.types.SubsurfModifier.levels`
+but we want the path from the object to this property.
+
+Note that the text copied won't include the ``bpy.data.collection["name"].``
component since its assumed that
+you won't be doing collection look-ups on every access and typically you'll
want to use the context rather
+then access each :class:`bpy.types.ID` instance by name.
+
+
+Type in the ID path into a Python console :mod:`bpy.context.active_object`.
Include the trailing dot and don't hit "enter", yet.
+
+Now right-click on the button and select **Copy Data Path**, then paste the
result into the console.
+
+So now you should have the answer:
+
+.. code-block:: python
+
+ bpy.context.active_object.modifiers["Subsurf"].levels
+
+Hit "enter" and you'll get the current value of 1. Now try changing the value
to 2:
+
+.. code-block:: python
+
+ bpy.context.active_object.modifiers["Subsurf"].levels = 2
+
+You can see the value update in the Subdivision-Surface modifier's UI as well
as the cube.
+
+
+.. _info_data_path_indirect
+
+Indirect Data Access
+--------------------
+
+For this example we'll go over something more involved, showing the steps to
access the active sculpt brushes texture.
+
+Lets say we want to access the texture of a brush via Python, to adjust its
``contrast`` for example.
+
+- Start in the default scene and enable 'Sculpt' mode from the 3D-View header.
+
+- From the toolbar expand the **Texture** panel and add a new texture.
+
+ *Notice the texture button its self doesn't have very useful links (you can
check the tool-tips).*
+
+- The contrast setting isn't exposed in the sculpt toolbar, so view the
texture in the properties panel...
+
+ - In the properties button select the Texture context.
+
+ - Select the Brush icon to show the brush texture.
+
+ - Expand the **Colors** panel to locate the **Contrast** button.
+
+- Right click on the contrast button and select **Online Python Reference**
This takes you to ``bpy.types.Texture.contrast``
+
+- Now we can see that ``contrast`` is a property of texture, so next we'll
check on how to access the texture from the brush.
+
+- Check on the **References** at the bottom of the page, sometimes there are
many references, and it may take
+ some guess work to find the right one, but in this case its obviously
``Brush.texture``.
+
+ *Now we know that the texture can be accessed from*
``bpy.data.brushes["BrushName"].texture``
+ *but normally you won't want to access the brush by name, so we'll see now
to access the active brush instead.*
+
+- So the next step is to check on where brushes are accessed from via the
**References**.
+ In this case there is simply ``bpy.context.brush`` which is all we need.
+
+
+Now you can use the Python console to form the nested properties needed to
access brush textures contrast,
+logically we now know.
+
+*Context -> Brush -> Texture -> Contrast*
+
+Since the attribute for each is given along the way we can compose the data
path in the python console:
+
+.. code-block:: python
+
+ bpy.context.brush.texture.contrast
+
+
+There can be multiple ways to access the same data, which you choose often
depends on the task.
+
+An alternate path to access the same setting is...
+
+.. code-block:: python
+
+ bpy.context.sculpt.brush.texture.contrast
+
+Or access the brush directly...
+
@@ Diff output truncated at 10240 characters. @@
_______________________________________________
Bf-blender-cvs mailing list
[email protected]
http://lists.blender.org/mailman/listinfo/bf-blender-cvs
