Dev:2.4/Source/Python/2.4x API rewrite/Meetings

IRC PyAPI Meeting 17 June 2007

• We will have a new python API (break compat with old one) - possibly for blender 2.5 but not necessarily.
• The existing API might stay in parallel with the new API, but this is not necessary since there is a 2.44 stable branch
• Existing API freezes (2.4x series)

Managing Pointers

• The Python API will keep a "map" of all Python Objects for each type one for (BPyText's, another for BPyScene's etc) - This dictionary will be either a GHash or a Python Dictionary. This cannot INCREF the PyTypes it stores.

This map will mainly be used so removing or reallocating data can make sure the PyObjects are updated or invalidated- so further use raises a "This data has been removed" error. Currently in the 2.4x API there is no way do this: Python Objects can have invalid pointers that will cause memory errors when written to.

• Pythons dealloc function will need to remove the references from Blender's pool of data, so the Python map never points to invalid PyObjects.

• Python will only allow one instance of each Blender object
  so with a=bpy.data.meshes['foo']; b=bpy.data.meshes['foo'] a and b will be the same PyObject (With the 2.4x API would be separate pyObjects pointing to the same data)

• Each mapped PyObject has a pointer to Blender's data, A NULL pointer shows that the data has been removed. Accessing this data will raise an error.
  

(Note, we already do this for scenes and groups but it is not safe because there can be multiple PyObjects with the 2.4x api)

• • When Python removes the data, it sets the pointer to Blender's data in the PyObject to NULL.
  • When Blender removes an object, it calls a new PythonAPI function with the ID as an argument, and looks for the PyObject in the 'map' and sets its pointer to NULL if there is a matching PyObject.
    (Note, Only allowing 1 Python Object per Blender data will give a speedup here since there will never be more then 1 pointer to set to NULL and once its found, the loop can exit, also has the advantate that there will be less data to search through in most cases)
• Data that wraps Blender's internal types like verts, faces, metaelems, object matrices will all have a pointer to the BPyMesh, BPyScene... etc.
  Before accessing the wrapped data it will check that the BPyObject's pointer to the Blender data is not NULL. So you can never write to a pointer once the data is removed.

• The map will only contain library data - (Data that has an ID pointer)

• To ensure verts/faces/etc... are pointing to a valid PyObject that is not deallocated, verts/faces/etc will INCREF the PyObject. So a BPyVert would INCREF the BPyMesh it comes from.
  A vert's UV or coordinates (Vector) will also INCREF and check the BPyMesh - so you can't write to a vertex location once mesh is removed.

• Reallocing Blender's internal data (say from entering and exiting editmesh) must invalidate mesh data for instance, same for other types. Editing an IPO must invalidate BezTriple points from the curve (because the data is wrapped)

Data Invalidation Implementation for Non Library Data

To do this we access data through the PyObject - so a BezTriple would be "The 5th point in BPyCurve".

That way each time it was accessed it would look up the data in the array, and it would not matter if the array was reallocated since last use. A vertex-Location would be self->bpymesh->mesh->verts[self->index] with checks for self->bpymesh->mesh being NULL and the index being less than self->bpymesh->mesh->totvert. This has the advantage that errors are only raised if the mesh is removed or enough verts are removed for the index to become out of range. Blender.Mesh already does this but each vert refers to the mesh rather than the BPy_Mesh.

Layers

the layer bitmask will be called layerMask. Rather then using a list to represent layer, a python set() is a better representation.

The set can be sub typed and have a PyObject pointer added to it. This will be a normal set that is kept in sync by wrapped subtype operations.

IRC PyAPI (Mini)Meeting 24 June 2007

Bitfields

All bitfields will be made into a number boolean attributes. face.flag mesh.mode etc.

So for example. ob.drawFlags would be ob.drawName, ob.drawAxis, ob.drawAxis etc.

The only bitfield that will be left is layerMask since the numbers have meaning when applied to it.

If this ends up making some importers run slow, flags of some data can be added back later.

Constants

Ken will impliment his proposal for constants http://wiki.blender.org/index.php/BlenderDev/Bitfields#Constant_.28including_Bitfield_Access.29_Through_the_BPython_API

IRC PyAPI Meeting 15 July 2007

Constants and Constructors

• bpy.types will store all PyTypes
• each type has tp_init so it can be used as a constructor.
  type(someVector) == bpy.types.Vector
  newVec = bpy.types.Vector()
• Each PyType will have constants in their tp_dict so bpy.types.Mesh.Modes.TWOSIDE would be how constants would be accessed.

C Docstings

Postpone decision

IRC PyAPI Meeting 22 July 2007

Loading .blend Files

The problem with python loading a blend file is that a lot of data that is assumed to exist throughout the lifetime of the script - is removed.

For example - The pointers to all scenes, materials, meshes etc become invalid.

This means accessing existing BPyObjects after loading a blend file will crash blender in most cases.

I suggest we stop the python interpreter before loading and start it up again after loading, If its important that the newly opened file continue to run a script, we could make a textblock an optional argument to the load command, this text would run after the file is loaded. --Ideasman42 18:37, 9 July 2007 (CEST)

(Agreed on at meeting but may need to research more)

Remove Mathutils Point Type

In the Existing Python API we have a type called point which is not used (anywhere?)

Agree'd we dont need a 3D point because 3D vectors can be used. Joseph Gilbert was not present and since he wrote in support for 'Points' he might want to contest this.

IRC PyAPI Meeting 5 August 2007

• Hold meetings once every 2 weeks, on a Saturday at the same time as the main Sunday #blendercoders meeting for approx 1.5 hours, no more then 2.
  Meetings are held in #blenderpython and will be announced on the blender-python mailing list.

Moving to the new API (meeting decisions)

• keep the blenders method of making // relative to the blend file.
  Replacing this with ./ or .\ is possible however it would require us to change the CWD (current working directory) for it to work which is messing with internals too much.
• remove Blender.sys, use pythons sys module instead, keep sys.expandpath() and move into bpy.utils.expandpath()
• Move Blender.Run() into bpy.utils.run()
• Move Blender.ShowHelp() into bpy.utils.showHelp()
• Move Blender.mode/bylink/link/event to bpy.state.*
• Blender.Geometry, Blender.Mathutils
  -->bpy.math.geometry, bpy.math.noise
• Move Blender.Get('filename'), Blender.Save/Load/Pack/Unpack
  --> bpy.data.filename, bpy.data.save(...).. etc.
• Move read only application settings to Blender.Get('version'), 'homedir', 'datadir'
  --> bpy.app.version, bpy.app.homedir, bpy.app.datadir, bpy.app.icondir

• Noise and Unpack are 2 exceptions to the rule, in that they need constants (NoiseTypes, UnpackModes) but have no type to be accessed from. (like bpy.types.Texture.Mode for instance).
  These types can be accessed from the functions that used them. eg. bpy.data.unpack.UnpackModes.*

IRC PyAPI Meeting 19 August 2007

Old API Migration

• Blender.BGL --> bpy.gl
• Registry has 2 parts, inter-script communication and saving settings. we need to propose how this would be done better before deciding whats done here.
• Window and Draw to be maintained until the event reactor when they can be properly written.

Extending Type Constructors

• Special functions to be made into keyword arguments eg - bpy.types.Mesh(type='CONE') was rejected.
  Instead we'll have special functions under each type eg. bpy.types.Mesh.Cone(...), bpy.types.Matrix.Rotation(...)

IRC PyAPI --Ideasman42 18:52, 8 September 2007 (CEST)

Object Hierarchy

• ob.getChildren() a shortcut function for [o for o in bpy.data.objects if o.parent = ob]
• ob.parent cannot be set because parenting is a complex operation instead have parent.makeParent([ob1, ob2], vertex=[v1, v2, v3], fast=True), or bone as a keyword for bone parents.
• have options for parent offset, default operation is that the object wont move its workdspace position.
• keep ob.parent, ob.parentType, ob.parentBoneName/parentBone, keep ob.clearParent()
• add ob.clearParentOffset(), ob.parentVerts (readonly)

keyable types

• current implementation accepted (grudgingly) since it allows types to become keyable as blender evolves and its advantages outweigh other solutions.
• other types can be keyable too - vector, colors etc with subtyping of their respective types.