diff options
Diffstat (limited to 'doc/python_api')
| -rw-r--r-- | doc/python_api/rst/bge.logic.rst | 536 | ||||
| -rw-r--r-- | doc/python_api/rst/bge.types.rst | 580 | ||||
| -rw-r--r-- | doc/python_api/rst/bgl.rst | 253 | ||||
| -rw-r--r-- | doc/python_api/rst/gpu.rst | 8 | ||||
| -rw-r--r-- | doc/python_api/rst/info_gotcha.rst | 57 | ||||
| -rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 6 |
6 files changed, 980 insertions, 460 deletions
diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst index 616ee12bba0..76e28c6d04b 100644 --- a/doc/python_api/rst/bge.logic.rst +++ b/doc/python_api/rst/bge.logic.rst @@ -260,13 +260,6 @@ General functions :rtype: list [float], len(getSpectrum()) == 512 -.. function:: stopDSP() - - Stops the sound driver using DSP effects. - - Only the fmod sound driver supports this. - DSP can be computationally expensive. - .. function:: getMaxLogicFrame() Gets the maximum number of logic frames per render frame. @@ -337,6 +330,24 @@ General functions .. warning: Not implimented yet +.. function:: getExitKey() + + Gets the key used to exit the game engine + + :return: The key (defaults to :mod:`bge.events.ESCKEY`) + :rtype: int + +.. function:: setExitKey(key) + + Sets the key used to exit the game engine + + :arg key: A key constant from :mod:`bge.events` + :type key: int + +.. function:: NextFrame() + + Render next frame (if Python has control) + ***************** Utility functions ***************** @@ -379,6 +390,10 @@ Utility functions .. function:: PrintGLInfo() Prints GL Extension Info into the console + +.. function:: PrintMemInfo() + + Prints engine statistics into the console ********* Constants @@ -407,6 +422,45 @@ Sensor Status .. data:: KX_SENSOR_ACTIVE .. data:: KX_SENSOR_JUST_DEACTIVATED +------------- +Armature Sensor +------------- + +.. _armaturesensor-type: + +See :class:`bge.types.KX_ArmatureSensor.type` + +.. data:: KX_ARMSENSOR_STATE_CHANGED + + Detect that the constraint is changing state (active/inactive) + + :value: 0 + +.. data:: KX_ARMSENSOR_LIN_ERROR_BELOW + + Detect that the constraint linear error is above a threshold + + :value: 1 + +.. data:: KX_ARMSENSOR_LIN_ERROR_ABOVE + + Detect that the constraint linear error is below a threshold + + :value: 2 + +.. data:: KX_ARMSENSOR_ROT_ERROR_BELOW + + Detect that the constraint rotation error is above a threshold + + :value: 3 + +.. data:: KX_ARMSENSOR_ROT_ERROR_ABOVE + + Detect that the constraint rotation error is below a threshold + + :value: 4 + + .. _logic-property-sensor: --------------- @@ -489,6 +543,52 @@ See :class:`bge.types.BL_ActionActuator` .. data:: KX_ACTIONACT_LOOPEND .. data:: KX_ACTIONACT_PROPERTY +--------------- +Armature Actuator +--------------- + + .. _armatureactuator-constants-type: + +See :class:`bge.types.BL_ArmatureActuator.type` + +.. data:: KX_ACT_ARMATURE_RUN + + Just make sure the armature will be updated on the next graphic frame. + This is the only persistent mode of the actuator: + it executes automatically once per frame until stopped by a controller + + :value: 0 + +.. data:: KX_ACT_ARMATURE_ENABLE + + Enable the constraint. + + :value: 1 + +.. data:: KX_ACT_ARMATURE_DISABLE + + Disable the constraint (runtime constraint values are not updated). + + :value: 2 + +.. data:: KX_ACT_ARMATURE_SETTARGET + + Change target and subtarget of constraint. + + :value: 3 + +.. data:: KX_ACT_ARMATURE_SETWEIGHT + + Change weight of constraint (IK only). + + :value: 4 + +.. data:: KX_ACT_ARMATURE_SETINFLUENCE + + Change influence of constraint. + + :value: 5 + ------------------- Constraint Actuator ------------------- @@ -499,31 +599,31 @@ See :class:`bge.types.KX_ConstraintActuator.option` * Applicable to Distance constraint: - .. data:: KX_ACT_CONSTRAINT_NORMAL +.. data:: KX_CONSTRAINTACT_NORMAL Activate alignment to surface - .. data:: KX_ACT_CONSTRAINT_DISTANCE +.. data:: KX_CONSTRAINTACT_DISTANCE Activate distance control - .. data:: KX_ACT_CONSTRAINT_LOCAL +.. data:: KX_CONSTRAINTACT_LOCAL Direction of the ray is along the local axis * Applicable to Force field constraint: - .. data:: KX_ACT_CONSTRAINT_DOROTFH +.. data:: KX_CONSTRAINTACT_DOROTFH Force field act on rotation as well * Applicable to both: - .. data:: KX_ACT_CONSTRAINT_MATERIAL +.. data:: KX_CONSTRAINTACT_MATERIAL Detect material rather than property - .. data:: KX_ACT_CONSTRAINT_PERMANENT +.. data:: KX_CONSTRAINTACT_PERMANENT No deactivation if ray does not hit target @@ -591,27 +691,27 @@ See :class:`bge.types.KX_ConstraintActuator.limit` Set orientation of Z axis -.. data:: KX_ACT_CONSTRAINT_FHNX +.. data:: KX_CONSTRAINTACT_FHNX Set force field along negative X axis -.. data:: KX_ACT_CONSTRAINT_FHNY +.. data:: KX_CONSTRAINTACT_FHNY Set force field along negative Y axis -.. data:: KX_ACT_CONSTRAINT_FHNZ +.. data:: KX_CONSTRAINTACT_FHNZ Set force field along negative Z axis -.. data:: KX_ACT_CONSTRAINT_FHPX +.. data:: KX_CONSTRAINTACT_FHPX Set force field along positive X axis -.. data:: KX_ACT_CONSTRAINT_FHPY +.. data:: KX_CONSTRAINTACT_FHPY Set force field along positive Y axis -.. data:: KX_ACT_CONSTRAINT_FHPZ +.. data:: KX_CONSTRAINTACT_FHPZ Set force field along positive Z axis @@ -714,101 +814,31 @@ See :class:`bge.types.KX_SoundActuator` .. data:: KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP :value: 6 - - -======= -Various -======= - -.. _input-status: - ------------- -Input Status ------------- - -See :class:`bge.types.SCA_PythonKeyboard`, :class:`bge.types.SCA_PythonMouse`, :class:`bge.types.SCA_MouseSensor`, :class:`bge.types.SCA_KeyboardSensor` - -.. data:: KX_INPUT_NONE -.. data:: KX_INPUT_JUST_ACTIVATED -.. data:: KX_INPUT_ACTIVE -.. data:: KX_INPUT_JUST_RELEASED - -------------- -Mouse Buttons -------------- - -See :class:`bge.types.SCA_MouseSensor` -.. data:: KX_MOUSE_BUT_LEFT -.. data:: KX_MOUSE_BUT_MIDDLE -.. data:: KX_MOUSE_BUT_RIGHT - ------- -States ------- +-------------- +Steering Actuator +-------------- -See :class:`bge.types.KX_StateActuator` +.. _logic-steering-actuator: -.. data:: KX_STATE1 -.. data:: KX_STATE2 -.. data:: KX_STATE3 -.. data:: KX_STATE4 -.. data:: KX_STATE5 -.. data:: KX_STATE6 -.. data:: KX_STATE7 -.. data:: KX_STATE8 -.. data:: KX_STATE9 -.. data:: KX_STATE10 -.. data:: KX_STATE11 -.. data:: KX_STATE12 -.. data:: KX_STATE13 -.. data:: KX_STATE14 -.. data:: KX_STATE15 -.. data:: KX_STATE16 -.. data:: KX_STATE17 -.. data:: KX_STATE18 -.. data:: KX_STATE19 -.. data:: KX_STATE20 -.. data:: KX_STATE21 -.. data:: KX_STATE22 -.. data:: KX_STATE23 -.. data:: KX_STATE24 -.. data:: KX_STATE25 -.. data:: KX_STATE26 -.. data:: KX_STATE27 -.. data:: KX_STATE28 -.. data:: KX_STATE29 -.. data:: KX_STATE30 +See :class:`bge.types.KX_SteeringActuator.behavior` -.. _state-actuator-operation: +.. data:: KX_STEERING_SEEK -See :class:`bge.types.KX_StateActuator.operation` + :value: 1 -.. data:: KX_STATE_OP_CLR +.. data:: KX_STEERING_FLEE - Substract bits to state mask - - :value: 0 + :value: 2 -.. data:: KX_STATE_OP_CPY +.. data:: KX_STEERING_PATHFOLLOWING - Copy state mask - - :value: 1 - -.. data:: KX_STATE_OP_NEG + :value: 3 - Invert bits to state mask - - :value: 2 - -.. data:: KX_STATE_OP_SET - Add bits to state mask - - :value: 3 - -.. _Two-D-FilterActuator-mode: +======= +Various +======= --------- 2D Filter @@ -883,6 +913,227 @@ See :class:`bge.types.KX_StateActuator.operation` .. data:: RAS_2DFILTER_SOBEL :value: 7 + +---------------- +Armature Channel +---------------- +.. _armaturechannel-constants-rotation-mode: + +See :class:`bge.types.BL_ArmatureChannel.rotation_mode` + +.. note: + euler mode are named as in Blender UI but the actual axis order is reversed + +.. data:: ROT_MODE_QUAT + + Use quaternion in rotation attribute to update bone rotation. + + :value: 0 + +.. data:: ROT_MODE_XYZ + + Use euler_rotation and apply angles on bone's Z, Y, X axis successively. + + :value: 1 + +.. data:: ROT_MODE_XZY + + Use euler_rotation and apply angles on bone's Y, Z, X axis successively. + + :value: 2 + +.. data:: ROT_MODE_YXZ + + Use euler_rotation and apply angles on bone's Z, X, Y axis successively. + + :value: 3 + +.. data:: ROT_MODE_YZX + + Use euler_rotation and apply angles on bone's X, Z, Y axis successively. + + :value: 4 + +.. data:: ROT_MODE_ZXY + + Use euler_rotation and apply angles on bone's Y, X, Z axis successively. + + :value: 5 + +.. data:: ROT_MODE_ZYX + + Use euler_rotation and apply angles on bone's X, Y, Z axis successively. + + :value: 6 + + +---------------- +Armature Constraint +---------------- +.. _armatureconstraint-constants-type: + +See :class:`bge.types.BL_ArmatureConstraint.type` + +.. data:: CONSTRAINT_TYPE_TRACKTO +.. data:: CONSTRAINT_TYPE_KINEMATIC +.. data:: CONSTRAINT_TYPE_ROTLIKE +.. data:: CONSTRAINT_TYPE_LOCLIKE +.. data:: CONSTRAINT_TYPE_MINMAX +.. data:: CONSTRAINT_TYPE_SIZELIKE +.. data:: CONSTRAINT_TYPE_LOCKTRACK +.. data:: CONSTRAINT_TYPE_STRETCHTO +.. data:: CONSTRAINT_TYPE_CLAMPTO +.. data:: CONSTRAINT_TYPE_TRANSFORM +.. data:: CONSTRAINT_TYPE_DISTLIMIT + +.. _armatureconstraint-constants-ik-type: + +See :class:`bge.types.BL_ArmatureConstraint.ik_type` + +.. data:: CONSTRAINT_IK_COPYPOSE + + constraint is trying to match the position and eventually the rotation of the target. + + :value: 0 + +.. data:: CONSTRAINT_IK_DISTANCE + + Constraint is maintaining a certain distance to target subject to ik_mode + + :value: 1 + +.. _armatureconstraint-constants-ik-flag: + +See :class:`bge.types.BL_ArmatureConstraint.ik_flag` + +.. data:: CONSTRAINT_IK_FLAG_TIP + + Set when the constraint operates on the head of the bone and not the tail + + :value: 1 + +.. data:: CONSTRAINT_IK_FLAG_ROT + + Set when the constraint tries to match the orientation of the target + + :value: 2 + +.. data:: CONSTRAINT_IK_FLAG_STRETCH + + Set when the armature is allowed to stretch (only the bones with stretch factor > 0.0) + + :value: 16 + +.. data:: CONSTRAINT_IK_FLAG_POS + + Set when the constraint tries to match the position of the target. + + :value: 32 + +.. _armatureconstraint-constants-ik-mode: + +See :class:`bge.types.BL_ArmatureConstraint.ik_mode` + +.. data:: CONSTRAINT_IK_MODE_INSIDE + + The constraint tries to keep the bone within ik_dist of target + + :value: 0 + +.. data:: CONSTRAINT_IK_MODE_OUTSIDE + + The constraint tries to keep the bone outside ik_dist of the target + + :value: 1 + +.. data:: CONSTRAINT_IK_MODE_ONSURFACE + + The constraint tries to keep the bone exactly at ik_dist of the target. + + :value: 2 + +.. _input-status: + +---------------- +Blender Material +---------------- + +.. data:: BL_DST_ALPHA +.. data:: BL_DST_COLOR +.. data:: BL_ONE +.. data:: BL_ONE_MINUS_DST_ALPHA +.. data:: BL_ONE_MINUS_DST_COLOR +.. data:: BL_ONE_MINUS_SRC_ALPHA +.. data:: BL_ONE_MINUS_SRC_COLOR +.. data:: BL_SRC_ALPHA +.. data:: BL_SRC_ALPHA_SATURATE +.. data:: BL_SRC_COLOR +.. data:: BL_ZERO + +------------ +Input Status +------------ + +See :class:`bge.types.SCA_PythonKeyboard`, :class:`bge.types.SCA_PythonMouse`, :class:`bge.types.SCA_MouseSensor`, :class:`bge.types.SCA_KeyboardSensor` + +.. data:: KX_INPUT_NONE +.. data:: KX_INPUT_JUST_ACTIVATED +.. data:: KX_INPUT_ACTIVE +.. data:: KX_INPUT_JUST_RELEASED + +------------ +KX_GameObject +----------- +.. _gameobject-playaction-mode: + +See :class:`bge.types.KX_GameObject.playAction` + +.. data:: KX_ACTION_MODE_PLAY + + Play the action once. + + :value: 0 + +.. data:: KX_ACTION_MODE_LOOP + + Loop the action (repeat it). + + :value: 1 + +.. data:: KX_ACTION_MODE_PING_PONG + + Play the action one direct then back the other way when it has completed. + + :value: 2 + + +------------- +Mouse Buttons +------------- + +See :class:`bge.types.SCA_MouseSensor` + +.. data:: KX_MOUSE_BUT_LEFT +.. data:: KX_MOUSE_BUT_MIDDLE +.. data:: KX_MOUSE_BUT_RIGHT + +------------ +Navigation Mesh Draw Modes +------------ + +.. _navmesh-draw-mode: + +.. data:: RM_WALLS + + Draw only the walls. + +.. data:: RM_POLYS + + Draw only polygons. + +.. data:: RM_TRIS + + Draw triangle mesh. ------ Shader @@ -910,18 +1161,69 @@ Shader .. data:: SHD_TANGENT ----------------- -Blender Material ----------------- +------ +States +------ -.. data:: BL_DST_ALPHA -.. data:: BL_DST_COLOR -.. data:: BL_ONE -.. data:: BL_ONE_MINUS_DST_ALPHA -.. data:: BL_ONE_MINUS_DST_COLOR -.. data:: BL_ONE_MINUS_SRC_ALPHA -.. data:: BL_ONE_MINUS_SRC_COLOR -.. data:: BL_SRC_ALPHA -.. data:: BL_SRC_ALPHA_SATURATE -.. data:: BL_SRC_COLOR -.. data:: BL_ZERO +See :class:`bge.types.KX_StateActuator` + +.. data:: KX_STATE1 +.. data:: KX_STATE2 +.. data:: KX_STATE3 +.. data:: KX_STATE4 +.. data:: KX_STATE5 +.. data:: KX_STATE6 +.. data:: KX_STATE7 +.. data:: KX_STATE8 +.. data:: KX_STATE9 +.. data:: KX_STATE10 +.. data:: KX_STATE11 +.. data:: KX_STATE12 +.. data:: KX_STATE13 +.. data:: KX_STATE14 +.. data:: KX_STATE15 +.. data:: KX_STATE16 +.. data:: KX_STATE17 +.. data:: KX_STATE18 +.. data:: KX_STATE19 +.. data:: KX_STATE20 +.. data:: KX_STATE21 +.. data:: KX_STATE22 +.. data:: KX_STATE23 +.. data:: KX_STATE24 +.. data:: KX_STATE25 +.. data:: KX_STATE26 +.. data:: KX_STATE27 +.. data:: KX_STATE28 +.. data:: KX_STATE29 +.. data:: KX_STATE30 + +.. _state-actuator-operation: + +See :class:`bge.types.KX_StateActuator.operation` + +.. data:: KX_STATE_OP_CLR + + Substract bits to state mask + + :value: 0 + +.. data:: KX_STATE_OP_CPY + + Copy state mask + + :value: 1 + +.. data:: KX_STATE_OP_NEG + + Invert bits to state mask + + :value: 2 + +.. data:: KX_STATE_OP_SET + + Add bits to state mask + + :value: 3 + +.. _Two-D-FilterActuator-mode: diff --git a/doc/python_api/rst/bge.types.rst b/doc/python_api/rst/bge.types.rst index 94729dd7d4f..bfe1dc785ab 100644 --- a/doc/python_api/rst/bge.types.rst +++ b/doc/python_api/rst/bge.types.rst @@ -205,6 +205,18 @@ Types :type: boolean + .. attribute:: pos_ticks + + The number of ticks since the last positive pulse (read-only). + + :type: int + + .. attribute:: neg_ticks + + The number of ticks since the last negative pulse (read-only). + + :type: int + .. attribute:: status The status of the sensor (read-only): can be one of :ref:`these constants<sensor-status>`. @@ -621,6 +633,71 @@ Types :type: string + +.. class:: KX_SteeringActuator(SCA_IActuator) + + Steering Actuator for navigation. + + .. attribute:: behavior + + The steering behavior to use. + + :type: one of :ref:`these constants <logic-steering-actuator>` + + .. attribute:: velocity + + Velocity magnitude + + :type: float + + .. attribute:: acceleration + + Max acceleration + + :type: float + + .. attribute:: turnspeed + + Max turn speed + + :type: float + + .. attribute:: distance + + Relax distance + + :type: float + + .. attribute:: target + + Target object + + :type: :class:`KX_GameObject` + + .. attribute:: navmesh + + Navigation mesh + + :type: :class:`KX_GameObject` + + .. attribute:: selfterminated + + Terminate when target is reached + + :type: boolean + + .. attribute:: enableVisualization + + Enable debug visualization + + :type: boolean + + .. attribute:: pathUpdatePeriod + + Path update period + + :type: int + .. class:: CListValue(CPropValue) This is a list like object used in the game engine internally that behaves similar to a python list in most ways. @@ -686,6 +763,24 @@ Types KX_BlenderMaterial + .. attribute:: shader + + The materials shader. + + :type: :class:`BL_Shader` + + .. attribute:: blending + + Ints used for pixel blending, (src, dst), matching the setBlending method. + + :type: (integer, integer) + + .. attribute:: material_index + + The material's index. + + :type: integer + .. method:: getShader() Returns the material's shader. @@ -743,7 +838,13 @@ Types strength of of the camera following movement. :type: float - + + .. attribute:: axis + + The camera axis (0, 1, 2) for positive ``XYZ``, (3, 4, 5) for negative ``XYZ``. + + :type: int + .. attribute:: min minimum distance to the target object maintained by the actuator. @@ -762,12 +863,6 @@ Types :type: float - .. attribute:: useXY - - axis this actuator is tracking, True=X, False=Y. - - :type: boolean - .. attribute:: object the object this actuator tracks. @@ -988,14 +1083,14 @@ Types The object's parent object. (read-only). :type: :class:`KX_GameObject` or None - - .. attribute:: group_children + + .. attribute:: groupMembers Returns the list of group members if the object is a group object, otherwise None is returned. :type: :class:`CListValue` of :class:`KX_GameObject` or None - .. attribute:: group_parent + .. attribute:: groupObject Returns the group object that the object belongs to or None if the object is not part of a group. @@ -1100,30 +1195,30 @@ Types The object's world space transform matrix. 4x4 Matrix. :type: :class:`mathutils.Matrix` - + .. attribute:: localLinearVelocity - The object's local linear velocity. [x, y, z] - - :type: :class:`mathutils.Vector` - + The object's local linear velocity. [x, y, z] + + :type: :class:`mathutils.Vector` + .. attribute:: worldLinearVelocity The object's world linear velocity. [x, y, z] - - :type: :class:`mathutils.Vector` - + + :type: :class:`mathutils.Vector` + .. attribute:: localAngularVelocity The object's local angular velocity. [x, y, z] - - :type: :class:`mathutils.Vector` - + + :type: :class:`mathutils.Vector` + .. attribute:: worldAngularVelocity The object's world angular velocity. [x, y, z] - - :type: :class:`mathutils.Vector` + + :type: :class:`mathutils.Vector` .. attribute:: timeOffset @@ -1211,6 +1306,13 @@ Types :type: :class:`CListValue` of :class:`KX_GameObject`'s + .. attribute:: life + + The number of seconds until the object ends, assumes 50fps. + (when added with an add object actuator), (read-only). + + :type: float + .. method:: endObject() Delete this object, can be used in place of the EndObject Actuator. @@ -1653,7 +1755,7 @@ Types :arg blendin: the amount of blending between this animation and the previous one on this layer :type blendin: float :arg play_mode: the play mode - :type play_mode: KX_ACTION_MODE_PLAY, KX_ACTION_MODE_LOOP, or KX_ACTION_MODE_PING_PONG + :type play_mode: one of :ref:`these constants <gameobject-playaction-mode>` :arg layer_weight: how much of the previous layer to use for blending (0 = add) :type layer_weight: float :arg ipo_flags: flags for the old IPO behaviors (force, etc) @@ -1854,10 +1956,6 @@ Types :type: list [r, g, b] - .. attribute:: colour - - Synonym for color. - .. attribute:: lin_attenuation The linear component of this light's attenuation. (SPOT and NORMAL lights only). @@ -1942,11 +2040,6 @@ Types :type: integer - .. method:: getNumMaterials() - - :return: number of materials associated with this object - :rtype: integer - .. method:: getMaterialName(matid) Gets the name of the specified material. @@ -1987,11 +2080,6 @@ Types :return: a vertex object. :rtype: :class:`KX_VertexProxy` - .. method:: getNumPolygons() - - :return: The number of polygon in the mesh. - :rtype: integer - .. method:: getPolygon(index) Gets the specified polygon from the mesh. @@ -2010,7 +2098,7 @@ Types :arg matrix: transformation matrix. :type matrix: 4x4 matrix [[float]] - .. method:: transform_uv(matid, matrix, uv_index=-1, uv_index_from=-1) + .. method:: transformUV(matid, matrix, uv_index=-1, uv_index_from=-1) Transforms the vertices UV's of a mesh. @@ -2222,6 +2310,52 @@ Types :type: list of strings + +.. class:: KX_FontObject(KX_GameObject) + + TODO. + + +.. class:: KX_NavMeshObject(KX_GameObject) + + Python interface for using and controlling navigation meshes. + + .. method:: findPath(start, goal) + + Finds the path from start to goal points. + + :arg start: the start point + :arg start: 3D Vector + :arg goal: the goal point + :arg start: 3D Vector + :return: a path as a list of points + :rtype: list of points + + .. method:: raycast(start, goal) + + Raycast from start to goal points. + + :arg start: the start point + :arg start: 3D Vector + :arg goal: the goal point + :arg start: 3D Vector + :return: the hit factor + :rtype: float + + .. method:: draw(mode) + + Draws a debug mesh for the navigation mesh. + + :arg mode: the drawing mode (one of :ref:`these constants <navmesh-draw-mode>`) + :arg mode: integer + :return: None + + .. method:: rebuild() + + Rebuild the navigation mesh. + + :return: None + .. class:: KX_ObjectActuator(SCA_IActuator) The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement, @@ -2375,49 +2509,6 @@ Types :type: boolean -.. class:: KX_PhysicsObjectWrapper(PyObjectPlus) - - KX_PhysicsObjectWrapper - - .. method:: setActive(active) - - Set the object to be active. - - :arg active: set to True to be active - :type active: boolean - - .. method:: setAngularVelocity(x, y, z, local) - - Set the angular velocity of the object. - - :arg x: angular velocity for the x-axis - :type x: float - - :arg y: angular velocity for the y-axis - :type y: float - - :arg z: angular velocity for the z-axis - :type z: float - - :arg local: set to True for local axis - :type local: boolean - - .. method:: setLinearVelocity(x, y, z, local) - - Set the linear velocity of the object. - - :arg x: linear velocity for the x-axis - :type x: float - - :arg y: linear velocity for the y-axis - :type y: float - - :arg z: linear velocity for the z-axis - :type z: float - - :arg local: set to True for local axis - :type local: boolean - .. class:: KX_PolyProxy(SCA_IObject) A polygon holds the index of the vertex forming the poylgon. @@ -2426,7 +2517,7 @@ Types The polygon attributes are read-only, you need to retrieve the vertex proxy if you want to change the vertex settings. - .. attribute:: matname + .. attribute:: material_name The name of polygon material, empty if no material. @@ -2438,13 +2529,13 @@ Types :type: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial` - .. attribute:: texture + .. attribute:: texture_name The texture name of the polygon. :type: string - .. attribute:: matid + .. attribute:: material_id The material index of the polygon, use this to retrieve vertex proxy from mesh proxy. @@ -2675,18 +2766,6 @@ Types :type: boolean - .. attribute:: lightlayer - - Light layers this material affects. - - :type: bitfield. - - .. attribute:: triangle - - Mesh data with this material is triangles. It's probably not safe to change this. - - :type: boolean - .. attribute:: diffuse The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0]. @@ -2952,8 +3031,8 @@ Types .. method:: instantAddObject() adds the object without needing to calling SCA_PythonController.activate() - - .. note:: Use objectLastCreated to get the newly created object. + + .. note:: Use objectLastCreated to get the newly created object. .. class:: KX_SCA_DynamicActuator(SCA_IActuator) @@ -3226,6 +3305,10 @@ Types Return the value matching key, or the default value if its not found. :return: The key value or a default. + .. method:: drawObstacleSimulation() + + Draw debug visualization of obstacle simulation. + .. class:: KX_SceneActuator(SCA_IActuator) Scene Actuator logic brick. @@ -3272,17 +3355,17 @@ Types Sound Actuator. - The :data:`startSound`, :data:`pauseSound` and :data:`stopSound` do not requirethe actuator to be activated - they act instantly provided that the actuator has been activated once at least. + The :data:`startSound`, :data:`pauseSound` and :data:`stopSound` do not require the actuator to be activated - they act instantly provided that the actuator has been activated once at least. - .. attribute:: fileName + .. attribute:: volume - The filename of the sound this actuator plays. + The volume (gain) of the sound. - :type: string + :type: float - .. attribute:: volume + .. attribute:: time - The volume (gain) of the sound. + The current position in the audio stream (in seconds). :type: float @@ -3292,41 +3375,89 @@ Types :type: float - .. attribute:: rollOffFactor + .. attribute:: mode + + The operation mode of the actuator. Can be one of :ref:`these constants<logic-sound-actuator>` + + :type: integer - The roll off factor. Rolloff defines the rate of attenuation as the sound gets further away. + .. attribute:: sound + + The sound the actuator should play. + + :type: Audaspace factory + + .. attribute:: is3D + + Whether or not the actuator should be using 3D sound. (read-only) + + :type: boolean + + .. attribute:: volume_maximum + + The maximum gain of the sound, no matter how near it is. :type: float - .. attribute:: looping + .. attribute:: volume_minimum - The loop mode of the actuator. + The minimum gain of the sound, no matter how far it is away. - :type: integer + :type: float - .. attribute:: position + .. attribute:: distance_reference + + The distance where the sound has a gain of 1.0. - The position of the sound as a list: [x, y, z]. + :type: float - :type: float array + .. attribute:: distance_maximum - .. attribute:: velocity + The maximum distance at which you can hear the sound. - The velocity of the emitter as a list: [x, y, z]. The relative velocity to the observer determines the pitch. List of 3 floats: [x, y, z]. + :type: float - :type: float array + .. attribute:: attenuation - .. attribute:: orientation + The influence factor on volume depending on distance. - The orientation of the sound. When setting the orientation you can also use quaternion [float, float, float, float] or euler angles [float, float, float]. + :type: float - :type: 3x3 matrix [[float]] + .. attribute:: cone_angle_inner - .. attribute:: mode + The angle of the inner cone. - The operation mode of the actuator. Can be one of :ref:`these constants<logic-sound-actuator>` + :type: float - :type: integer + .. attribute:: cone_angle_outer + + The angle of the outer cone. + + :type: float + + .. attribute:: cone_volume_outer + + The gain outside the outer cone (the gain in the outer cone will be interpolated between this value and the normal gain in the inner cone). + + :type: float + + .. method:: startSound() + + Starts the sound. + + :return: None + + .. method:: pauseSound() + + Pauses the sound. + + :return: None + + .. method:: stopSound() + + Stops the sound. + + :return: None .. class:: KX_StateActuator(SCA_IActuator) @@ -3544,7 +3675,7 @@ Types Whether or not the character is on the ground. (read-only) - :type: boolean + :type: boolean .. attribute:: gravity @@ -3590,10 +3721,6 @@ Types Black = [0.0, 0.0, 0.0, 1.0], White = [1.0, 1.0, 1.0, 1.0] - .. attribute:: colour - - Synonym for color. - .. attribute:: x The x coordinate of the vertex. @@ -4320,24 +4447,6 @@ Types :type: integer - .. method:: setSeed(seed) - - Sets the seed of the random number generator. - - If the seed is 0, the generator will produce the same value on every call. - - :type seed: integer - - .. method:: getSeed() - - :return: The initial seed of the generator. Equal seeds produce equal random series. - :rtype: integer - - .. method:: getLastDraw() - - :return: The last random number generated. - :rtype: integer - .. class:: SCA_XNORController(SCA_IController) An XNOR controller activates when all linked sensors are the same (activated or inative). @@ -4405,7 +4514,7 @@ Types .. attribute:: projection_matrix This camera's 4x4 projection matrix. - + .. note:: This is the identity matrix prior to rendering the first frame (any Python done on frame 1). @@ -4658,48 +4767,6 @@ Types Armature Actuators change constraint condition on armatures. - .. _armatureactuator-constants-type: - - Constants related to :data:`~bge.types.BL_ArmatureActuator.type` - - .. data:: KX_ACT_ARMATURE_RUN - - Just make sure the armature will be updated on the next graphic frame. - This is the only persistent mode of the actuator: - it executes automatically once per frame until stopped by a controller - - :value: 0 - - .. data:: KX_ACT_ARMATURE_ENABLE - - Enable the constraint. - - :value: 1 - - .. data:: KX_ACT_ARMATURE_DISABLE - - Disable the constraint (runtime constraint values are not updated). - - :value: 2 - - .. data:: KX_ACT_ARMATURE_SETTARGET - - Change target and subtarget of constraint. - - :value: 3 - - .. data:: KX_ACT_ARMATURE_SETWEIGHT - - Change weight of constraint (IK only). - - :value: 4 - - .. data:: KX_ACT_ARMATURE_SETINFLUENCE - - Change influence of constraint. - - :value: 5 - .. attribute:: type The type of action that the actuator executes when it is active. @@ -4754,40 +4821,6 @@ Types Armature sensor detect conditions on armatures. - .. _armaturesensor-type: - - Constants related to :data:`type` - - .. data:: KX_ARMSENSOR_STATE_CHANGED - - Detect that the constraint is changing state (active/inactive) - - :value: 0 - - .. data:: KX_ARMSENSOR_LIN_ERROR_BELOW - - Detect that the constraint linear error is above a threshold - - :value: 1 - - .. data:: KX_ARMSENSOR_LIN_ERROR_ABOVE - - Detect that the constraint linear error is below a threshold - - :value: 2 - - .. data:: KX_ARMSENSOR_ROT_ERROR_BELOW - - Detect that the constraint rotation error is above a threshold - - :value: 3 - - .. data:: KX_ARMSENSOR_ROT_ERROR_ABOVE - - Detect that the constraint rotation error is below a threshold - - :value: 4 - .. attribute:: type The type of measurement that the sensor make when it is active. @@ -4822,87 +4855,6 @@ Types Not all armature constraints are supported in the GE. - .. _armatureconstraint-constants-type: - - Constants related to :data:`type` - - .. data:: CONSTRAINT_TYPE_TRACKTO - .. data:: CONSTRAINT_TYPE_KINEMATIC - .. data:: CONSTRAINT_TYPE_ROTLIKE - .. data:: CONSTRAINT_TYPE_LOCLIKE - .. data:: CONSTRAINT_TYPE_MINMAX - .. data:: CONSTRAINT_TYPE_SIZELIKE - .. data:: CONSTRAINT_TYPE_LOCKTRACK - .. data:: CONSTRAINT_TYPE_STRETCHTO - .. data:: CONSTRAINT_TYPE_CLAMPTO - .. data:: CONSTRAINT_TYPE_TRANSFORM - .. data:: CONSTRAINT_TYPE_DISTLIMIT - - .. _armatureconstraint-constants-ik-type: - - Constants related to :data:`ik_type` - - .. data:: CONSTRAINT_IK_COPYPOSE - - constraint is trying to match the position and eventually the rotation of the target. - - :value: 0 - - .. data:: CONSTRAINT_IK_DISTANCE - - Constraint is maintaining a certain distance to target subject to ik_mode - - :value: 1 - - .. _armatureconstraint-constants-ik-flag: - - Constants related to :data:`ik_flag` - - .. data:: CONSTRAINT_IK_FLAG_TIP - - Set when the constraint operates on the head of the bone and not the tail - - :value: 1 - - .. data:: CONSTRAINT_IK_FLAG_ROT - - Set when the constraint tries to match the orientation of the target - - :value: 2 - - .. data:: CONSTRAINT_IK_FLAG_STRETCH - - Set when the armature is allowed to stretch (only the bones with stretch factor > 0.0) - - :value: 16 - - .. data:: CONSTRAINT_IK_FLAG_POS - - Set when the constraint tries to match the position of the target. - - :value: 32 - - .. _armatureconstraint-constants-ik-mode: - - Constants related to :data:`ik_mode` - - .. data:: CONSTRAINT_IK_MODE_INSIDE - - The constraint tries to keep the bone within ik_dist of target - - :value: 0 - - .. data:: CONSTRAINT_IK_MODE_OUTSIDE - - The constraint tries to keep the bone outside ik_dist of the target - - :value: 1 - - .. data:: CONSTRAINT_IK_MODE_ONSURFACE - - The constraint tries to keep the bone exactly at ik_dist of the target. - - :value: 2 .. attribute:: type @@ -5021,16 +4973,6 @@ Types Proxy to armature pose channel. Allows to read and set armature pose. The attributes are identical to RNA attributes, but mostly in read-only mode. - See :data:`rotation_mode` - - .. data:: PCHAN_ROT_QUAT - .. data:: PCHAN_ROT_XYZ - .. data:: PCHAN_ROT_XZY - .. data:: PCHAN_ROT_YXZ - .. data:: PCHAN_ROT_YZX - .. data:: PCHAN_ROT_ZXY - .. data:: PCHAN_ROT_ZYX - .. attribute:: name channel name (=bone name), read-only. @@ -5164,17 +5106,7 @@ Types Method of updating the bone rotation, read-write. - :type: integer - - Use the following constants (euler mode are named as in Blender UI but the actual axis order is reversed). - - * PCHAN_ROT_QUAT(0) : use quaternioin in rotation attribute to update bone rotation - * PCHAN_ROT_XYZ(1) : use euler_rotation and apply angles on bone's Z, Y, X axis successively - * PCHAN_ROT_XZY(2) : use euler_rotation and apply angles on bone's Y, Z, X axis successively - * PCHAN_ROT_YXZ(3) : use euler_rotation and apply angles on bone's Z, X, Y axis successively - * PCHAN_ROT_YZX(4) : use euler_rotation and apply angles on bone's X, Z, Y axis successively - * PCHAN_ROT_ZXY(5) : use euler_rotation and apply angles on bone's Y, X, Z axis successively - * PCHAN_ROT_ZYX(6) : use euler_rotation and apply angles on bone's X, Y, Z axis successively + :type: integer (one of :ref:`these constants <armaturechannel-constants-rotation-mode>`) .. attribute:: channel_matrix diff --git a/doc/python_api/rst/bgl.rst b/doc/python_api/rst/bgl.rst index 9f7817c6fa2..fc4524b1213 100644 --- a/doc/python_api/rst/bgl.rst +++ b/doc/python_api/rst/bgl.rst @@ -689,7 +689,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return the specified pixel map - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetPixelMap.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetPixelMap.xml>`_ :type map: Enumerated constant :arg map: Specifies the name of the pixel map to return. @@ -701,7 +701,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return the polygon stipple pattern - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetPolygonStipple.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetPolygonStipple.xml>`_ :type mask: :class:`bgl.Buffer` object I{type GL_BYTE} :arg mask: Returns the stipple pattern. The initial value is all 1's. @@ -824,13 +824,25 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the current color index - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glIndex.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIndex.xml>`_ :type c: :class:`bgl.Buffer` object. Depends on function prototype. :arg c: Specifies a pointer to a one element array that contains the new value for the current color index. +.. function:: glIndexMask(mask): + + Control the writing of individual bits in the color index buffers + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIndexMask.xml>`_ + + :type mask: int + :arg mask: Specifies a bit mask to enable and disable the writing of individual bits + in the color index buffers. + Initially, the mask is all 1's. + + .. function:: glInitNames(): Initialize the name stack @@ -1510,7 +1522,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. :arg mode: Specifies a symbolic value representing a shading technique. -.. function:: glStencilFuc(func, ref, mask): +.. function:: glStencilFunc(func, ref, mask): Set function and reference value for stencil testing @@ -1835,7 +1847,238 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. :arg objx, objy, objz: Return the computed object coordinates. -class Buffer: +.. function:: glUseProgram(program): + + Installs a program object as part of current rendering state + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glUseProgram.xml>`_ + + :type program: int + :arg program: Specifies the handle of the program object whose executables are to be used as part of current rendering state. + + +.. function:: glValidateProgram(program): + + Validates a program object + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glValidateProgram.xml>`_ + + :type program: int + :arg program: Specifies the handle of the program object to be validated. + + +.. function:: glLinkProgram(program): + + Links a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glLinkProgram.xml>`_ + + :type program: int + :arg program: Specifies the handle of the program object to be linked. + + +.. function:: glActiveTexture(texture): + + Select active texture unit. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glActiveTexture.xml>`_ + + :type texture: int + :arg texture: Constant in ``GL_TEXTURE0`` 0 - 8 + + +.. function:: glAttachShader(program, shader): + + Attaches a shader object to a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glAttachShader.xml>`_ + + :type program: int + :arg program: Specifies the program object to which a shader object will be attached. + :type shader: int + :arg shader: Specifies the shader object that is to be attached. + + +.. function:: glCompileShader(shader): + + Compiles a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glCompileShader.xml>`_ + + :type shader: int + :arg shader: Specifies the shader object to be compiled. + + +.. function:: glCreateProgram(): + + Creates a program object + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glCreateProgram.xml>`_ + + :rtype: int + :return: The new program or zero if an error occurs. + + +.. function:: glCreateShader(shaderType): + + Creates a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glCreateShader.xml>`_ + + :type shaderType: Specifies the type of shader to be created. + Must be one of ``GL_VERTEX_SHADER``, + ``GL_TESS_CONTROL_SHADER``, + ``GL_TESS_EVALUATION_SHADER``, + ``GL_GEOMETRY_SHADER``, + or ``GL_FRAGMENT_SHADER``. + :arg shaderType: + :rtype: int + :return: 0 if an error occurs. + + +.. function:: glDeleteProgram(program): + + Deletes a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glDeleteProgram.xml>`_ + + :type program: int + :arg program: Specifies the program object to be deleted. + + +.. function:: glDeleteShader(shader): + + Deletes a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glDeleteShader.xml>`_ + + :type shader: int + :arg shader: Specifies the shader object to be deleted. + + +.. function:: glDetachShader(program, shader): + + Detaches a shader object from a program object to which it is attached. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glDetachShader.xml>`_ + + :type program: int + :arg program: Specifies the program object from which to detach the shader object. + :type shader: int + :arg shader: pecifies the program object from which to detach the shader object. + + +.. function:: glGetAttachedShaders(program, maxCount, count, shaders): + + Returns the handles of the shader objects attached to a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetAttachedShaders.xml>`_ + + :type program: int + :arg program: Specifies the program object to be queried. + :type maxCount: int + :arg maxCount: Specifies the size of the array for storing the returned object names. + :type count: :class:`bgl.Buffer` int buffer. + :arg count: Returns the number of names actually returned in objects. + :type shaders: :class:`bgl.Buffer` int buffer. + :arg shaders: Specifies an array that is used to return the names of attached shader objects. + + +.. function:: glGetProgramInfoLog(program, maxLength, length, infoLog): + + Returns the information log for a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetProgramInfoLog.xml>`_ + + :type program: int + :arg program: Specifies the program object whose information log is to be queried. + :type maxLength: int + :arg maxLength: Specifies the size of the character buffer for storing the returned information log. + :type length: :class:`bgl.Buffer` int buffer. + :arg length: Returns the length of the string returned in **infoLog** (excluding the null terminator). + :type infoLog: :class:`bgl.Buffer` char buffer. + :arg infoLog: Specifies an array of characters that is used to return the information log. + + +.. function:: glGetShaderInfoLog(program, maxLength, length, infoLog): + + Returns the information log for a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetShaderInfoLog.xml>`_ + + :type shader: int + :arg shader: Specifies the shader object whose information log is to be queried. + :type maxLength: int + :arg maxLength: Specifies the size of the character buffer for storing the returned information log. + :type length: :class:`bgl.Buffer` int buffer. + :arg length: Returns the length of the string returned in **infoLog** (excluding the null terminator). + :type infoLog: :class:`bgl.Buffer` char buffer. + :arg infoLog: Specifies an array of characters that is used to return the information log. + + +.. function:: glGetProgramiv(program, pname, params): + + Returns a parameter from a program object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetProgram.xml>`_ + + :type program: int + :arg program: Specifies the program object to be queried. + :type pname: int + :arg pname: Specifies the object parameter. + :type params: :class:`bgl.Buffer` int buffer. + :arg params: Returns the requested object parameter. + + +.. function:: glIsShader(shader): + + Determines if a name corresponds to a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glIsShader.xml>`_ + + :type shader: int + :arg shader: Specifies a potential shader object. + + +.. function:: glIsProgram(program): + + Determines if a name corresponds to a program object + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glIsProgram.xml>`_ + + :type program: int + :arg program: Specifies a potential program object. + + +.. function:: glGetShaderSource(shader, bufSize, length, source): + + Returns the source code string from a shader object + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glGetShaderSource.xml>`_ + + :type shader: int + :arg shader: Specifies the shader object to be queried. + :type bufSize: int + :arg bufSize: Specifies the size of the character buffer for storing the returned source code string. + :type length: :class:`bgl.Buffer` int buffer. + :arg length: Returns the length of the string returned in source (excluding the null terminator). + :type source: :class:`bgl.Buffer` char. + :arg source: Specifies an array of characters that is used to return the source code string. + + +.. function:: glShaderSource(shader, shader_string): + + Replaces the source code in a shader object. + + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/xhtml/glShaderSource.xml>`_ + + :type shader: int + :arg shader: Specifies the handle of the shader object whose source code is to be replaced. + :type shader_string: string + :arg shader_string: The shader string. + + +.. class:: Buffer The Buffer object is simply a block of memory that is delineated and initialized by the user. Many OpenGL functions return data to a C-style pointer, however, because this diff --git a/doc/python_api/rst/gpu.rst b/doc/python_api/rst/gpu.rst index 68dc30b6143..a225829b3e8 100644 --- a/doc/python_api/rst/gpu.rst +++ b/doc/python_api/rst/gpu.rst @@ -262,10 +262,16 @@ The calculation of some of the uniforms is based on matrices available in the sc .. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW + The uniform is an float representing the bumpmap scaling. + + :value: 14 + +.. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE + The uniform is an integer representing a shadow buffer corresponding to a lamp casting shadow. - :value: 14 + :value: 15 GLSL attribute type diff --git a/doc/python_api/rst/info_gotcha.rst b/doc/python_api/rst/info_gotcha.rst index 1d561216b52..e60f1e256cd 100644 --- a/doc/python_api/rst/info_gotcha.rst +++ b/doc/python_api/rst/info_gotcha.rst @@ -118,18 +118,19 @@ If you insist - yes its possible, but scripts that use this hack wont be conside bpy.ops.wm.redraw_timer(type='DRAW_WIN_SWAP', iterations=1) -I can't edit the mesh in edit-mode! -=================================== +Modes and Mesh Access +===================== -Blender's EditMesh is an internal data structure (not saved and not exposed to python), this gives the main annoyance that you need to exit edit-mode to edit the mesh from python. +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. -The reason we have not made much attempt to fix this yet is because we -will likely move to BMesh mesh API eventually, so any work on the API now will be wasted effort. +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. -With the BMesh API we may expose mesh data to python so we can -write useful tools in python which are also fast to execute while in edit-mode. +In this situation you can... -For the time being this limitation just has to be worked around but we're aware its frustrating needs to be addressed. +* 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: @@ -311,7 +312,7 @@ Naming Limitations A common mistake is to assume newly created data is given the requested name. -This can cause bugs when you add some data (normally imported) and then reference it later by name. +This can cause bugs when you add some data (normally imported) then reference it later by name. .. code-block:: python @@ -557,6 +558,21 @@ This example shows how you can tell undo changes the memory locations. 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. + +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. + +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. + + Edit Mode / Memory Access ------------------------- @@ -616,7 +632,28 @@ 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. -This is a problem in the API at the moment that we should eventually solve. +The ``remove()`` api calls will invalidate the data they free to prevent common mistakes. + +The following example shows how this precortion works. + +.. code-block:: python + + 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 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. + +.. code-block:: python + + mesh = bpy.data.meshes.new(name="MyMesh") + vertices = mesh.vertices + bpy.data.meshes.remove(mesh) + print(vertices) # <- this may crash sys.exit diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 6f7d4f3582a..410612fabd5 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -1251,7 +1251,7 @@ def pyrna2sphinx(basepath): bases = list(reversed(struct.get_bases())) # props - lines[:] = [] + del lines[:] if _BPY_STRUCT_FAKE: descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")] @@ -1282,7 +1282,7 @@ def pyrna2sphinx(basepath): fw("\n") # funcs - lines[:] = [] + del lines[:] if _BPY_STRUCT_FAKE: for key, descr in descr_items: @@ -1305,7 +1305,7 @@ def pyrna2sphinx(basepath): fw(line) fw("\n") - lines[:] = [] + del lines[:] if struct.references: # use this otherwise it gets in the index for a normal heading. |