diff options
Diffstat (limited to 'doc/python_api/rst')
| -rw-r--r-- | doc/python_api/rst/bge.constraints.rst | 57 | ||||
| -rw-r--r-- | doc/python_api/rst/bge.render.rst | 127 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst | 31 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst | 22 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst | 36 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_Scene.rst | 22 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst | 79 | ||||
| -rw-r--r-- | doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst | 10 | ||||
| -rw-r--r-- | doc/python_api/rst/info_gotcha.rst | 8 |
9 files changed, 262 insertions, 130 deletions
diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst index 018be96fd14..14ebc61dbf5 100644 --- a/doc/python_api/rst/bge.constraints.rst +++ b/doc/python_api/rst/bge.constraints.rst @@ -11,51 +11,54 @@ Physics Constraints (bge.constraints) .. literalinclude:: ../examples/bge.constraints.py :lines: 6- -.. function:: createConstraint(physicsid, physicsid2, constrainttype, [pivotX, pivotY, pivotZ, [axisX, axisY, axisZ, [flag]]]]) +.. function:: createConstraint(physicsid_1, physicsid_2, constraint_type, pivot_X, pivot_y, pivot_z, axis_x, axis_y, axis_z, flag) Creates a constraint. - :arg physicsid: the physics id of the first object in constraint - :type physicsid: int + Constraints types: + - :class:`POINTTOPOINT_CONSTRAINT` + - :class:`LINEHINGE_CONSTRAINT` + - :class:`ANGULAR_CONSTRAINT` + - :class:`CONETWIST_CONSTRAINT` + - :class:`VEHICLE_CONSTRAINT` + - :class:`GENERIC_6DOF_CONSTRAINT` - :arg physicsid2: the physics id of the second object in constraint - :type physicsid2: int + :arg physicsid_1: the physics id of the first object in constraint. + :type physicsid_1: int - :arg constrainttype: the type of the constraint. The constraint types are: - - - :class:`POINTTOPOINT_CONSTRAINT` - - :class:`LINEHINGE_CONSTRAINT` - - :class:`ANGULAR_CONSTRAINT` - - :class:`CONETWIST_CONSTRAINT` - - :class:`VEHICLE_CONSTRAINT` - - :class:`GENERIC_6DOF_CONSTRAINT` + :arg physicsid_2: the physics id of the second object in constraint. + :type physicsid_2: int + :arg constrainttype: the type of the constraint. :type constrainttype: int - :arg pivotX: pivot X position - :type pivotX: float + :arg pivot_X: pivot X position (optional). + :type pivot_X: float - :arg pivotY: pivot Y position - :type pivotY: float + :arg pivot_Y: pivot Y position (optional). + :type pivot_Y: float - :arg pivotZ: pivot Z position - :type pivotZ: float + :arg pivot_Z: pivot Z position (optional). + :type pivot_Z: float - :arg axisX: X axis - :type axisX: float + :arg axis_X: X axis angle in degrees (optional). + :type axis_X: float - :arg axisY: Y axis - :type axisY: float + :arg axis_Y: Y axis angle in degrees (optional). + :type axis_Y: float - :arg axisZ: Z axis - :type axisZ: float + :arg axis_Z: Z axis angle in degrees (optional). + :type axis_Z: float - :arg flag: 128 to disable collision between linked bodies + :arg flag: 128 to disable collision between linked bodies (optional). :type flag: int + :return: a constraint wrapper. + :rtype: :class:`bge.types.KX_ConstraintWrapper` + .. attribute:: error - Simbolic constant string that indicates error. + Symbolic constant string that indicates error. .. function:: exportBulletFile(filename) diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst index 77d5bd71761..1748ae14fc8 100644 --- a/doc/python_api/rst/bge.render.rst +++ b/doc/python_api/rst/bge.render.rst @@ -66,7 +66,7 @@ Constants .. data:: KX_BLENDER_GLSL_MATERIAL Materials approximating blender materials with GLSL. - + .. DATA:: VSYNC_OFF Disables vsync @@ -87,6 +87,7 @@ Constants Right eye being used during stereoscopic rendering. + ********* Functions ********* @@ -94,47 +95,55 @@ Functions .. function:: getWindowWidth() Gets the width of the window (in pixels) - + :rtype: integer .. function:: getWindowHeight() Gets the height of the window (in pixels) - + :rtype: integer .. function:: setWindowSize(width, height) Set the width and height of the window (in pixels). This also works for fullscreen applications. - + :type width: integer :type height: integer .. function:: setFullScreen(enable) Set whether or not the window should be fullscreen. - + :type enable: bool .. function:: getFullScreen() Returns whether or not the window is fullscreen. - + :rtype: bool -.. function:: makeScreenshot(filename) +.. function:: getDisplayDimensions() - Writes a screenshot to the given filename. - - If filename starts with // the image will be saved relative to the current directory. - If the filename contains # it will be replaced with the frame number. - - The standalone player saves .png files. It does not support color space conversion - or gamma correction. - - When run from Blender, makeScreenshot supports all Blender image file formats like PNG, TGA, Jpeg and OpenEXR. - Gamma, Colorspace conversion and Jpeg compression are taken from the Render settings panels. + Get the actual display dimensions, in pixels, of the physical display (e.g., the monitor). + :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-#"). + + 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 @@ -146,65 +155,29 @@ Functions .. function:: showMouse(visible) Enables or disables the operating system mouse cursor. - + :type visible: boolean .. function:: setMousePosition(x, y) Sets the mouse cursor position. - + :type x: integer :type y: integer .. function:: setBackgroundColor(rgba) - Sets the window background color. - - :type rgba: list [r, g, b, a] - - -.. function:: setMistColor(rgb) - - Sets the mist color. - - :type rgb: list [r, g, b] - - -.. function:: setAmbientColor(rgb) - - Sets the color of ambient light. - - :type rgb: list [r, g, b] - - -.. function:: setMistStart(start) + Sets the window background color. (Deprecated: use KX_WorldInfo.background_color) - Sets the mist start value. Objects further away than start will have mist applied to them. - - :type start: float - - -.. function:: setMistEnd(end) - - Sets the mist end value. Objects further away from this will be colored solid with - the color set by setMistColor(). - - :type end: float - - -.. function:: disableMist() + :type rgba: list [r, g, b, a] - Disables mist. - - .. note:: Set any of the mist properties to enable mist. - .. function:: setEyeSeparation(eyesep) Sets the eye separation for stereo mode. Usually Focal Length/30 provides a confortable value. - + :arg eyesep: The distance between the left and right eye. :type eyesep: float @@ -212,21 +185,21 @@ Functions .. function:: getEyeSeparation() Gets the current eye separation for stereo mode. - + :rtype: float - + .. function:: setFocalLength(focallength) Sets the focal length for stereo mode. It uses the current camera focal length as initial value. - - :arg focallength: The focal length. + + :arg focallength: The focal length. :type focallength: float .. function:: getFocalLength() Gets the current focal length for stereo mode. - + :rtype: float .. function:: getStereoEye() @@ -241,7 +214,7 @@ Functions .. function:: setMaterialMode(mode) Set the material mode to use for OpenGL rendering. - + :type mode: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL .. note:: Changes will only affect newly created scenes. @@ -250,14 +223,14 @@ Functions .. function:: getMaterialMode(mode) Get the material mode to use for OpenGL rendering. - + :rtype: KX_TEXFACE_MATERIAL, KX_BLENDER_MULTITEX_MATERIAL, KX_BLENDER_GLSL_MATERIAL .. function:: setGLSLMaterialSetting(setting, enable) Enables or disables a GLSL material setting. - + :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures) :type enable: boolean @@ -265,43 +238,43 @@ Functions .. function:: getGLSLMaterialSetting(setting, enable) Get the state of a GLSL material setting. - + :type setting: string (lights, shaders, shadows, ramps, nodes, extra_textures) :rtype: boolean .. function:: setAnisotropicFiltering(level) Set the anisotropic filtering level for textures. - + :arg level: The new anisotropic filtering level to use :type level: integer (must be one of 1, 2, 4, 8, 16) - + .. note:: Changing this value can cause all textures to be recreated, which can be slow. - + .. function:: getAnisotropicFiltering() Get the anisotropic filtering level used for textures. - + :rtype: integer (one of 1, 2, 4, 8, 16) .. function:: setMipmapping(value) Change how to use mipmapping. - + :type value: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR - + .. note:: Changing this value can cause all textures to be recreated, which can be slow. .. function:: getMipmapping() Get the current mipmapping setting. - + :rtype: RAS_MIPMAP_NONE, RAS_MIPMAP_NEAREST, RAS_MIPMAP_LINEAR - + .. function:: drawLine(fromVec,toVec,color) Draw a line in the 3D scene. - + :arg fromVec: the origin of the line :type fromVec: list [x, y, z] :arg toVec: the end of the line @@ -313,7 +286,7 @@ Functions .. function:: enableMotionBlur(factor) Enable the motion blur effect. - + :arg factor: the ammount of motion blur to display. :type factor: float [0.0 - 1.0] diff --git a/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst index 53bef120f7a..59bd836d90e 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_ConstraintWrapper.rst @@ -23,15 +23,14 @@ base class --- :class:`PyObjectPlus` :arg axis: :type axis: integer - .. note:: - For each axis: - * Lowerlimit == Upperlimit -> axis is locked - * Lowerlimit > Upperlimit -> axis is free - * Lowerlimit < Upperlimit -> axis it limited in that range + .. note:: + * Lowerlimit == Upperlimit -> axis is locked + * Lowerlimit > Upperlimit -> axis is free + * Lowerlimit < Upperlimit -> axis it limited in that range - PHY_LINEHINGE_CONSTRAINT = 2 or PHY_ANGULAR_CONSTRAINT = 3: - axis = 3 is a constraint limit, with low/high limit value + For PHY_LINEHINGE_CONSTRAINT = 2 or PHY_ANGULAR_CONSTRAINT = 3: + axis = 3 is a constraint limit, with low/high limit value * 3: X axis angle :arg value0 (min): Set the minimum limit of the axis @@ -39,7 +38,8 @@ base class --- :class:`PyObjectPlus` :arg value1 (max): Set the maximum limit of the axis :type value1: float - PHY_CONE_TWIST_CONSTRAINT = 3: + For PHY_CONE_TWIST_CONSTRAINT = 4: + axis = 3..5 are constraint limits, high limit values * 3: X axis angle * 4: Y axis angle @@ -50,7 +50,8 @@ base class --- :class:`PyObjectPlus` :arg value1 (max): Set the maximum limit of the axis :type value1: float - PHY_GENERIC_6DOF_CONSTRAINT = 12: + For PHY_GENERIC_6DOF_CONSTRAINT = 12: + axis = 0..2 are constraint limits, with low/high limit value * 0: X axis position * 1: Y axis position @@ -132,10 +133,10 @@ base class --- :class:`PyObjectPlus` Returns the contraint type (read only) :type: integer + - 1 = :class:`~bge.constraints.POINTTOPOINT_CONSTRAINT` + - 2 = :class:`~bge.constraints.LINEHINGE_CONSTRAINT` + - 3 = :class:`~bge.constraints.ANGULAR_CONSTRAINT` + - 4 = :class:`~bge.constraints.CONETWIST_CONSTRAINT` + - 11 = :class:`~bge.constraints.VEHICLE_CONSTRAINT` + - 12 = :class:`~bge.constraints.GENERIC_6DOF_CONSTRAINT` - * 1 = POINTTOPOINT_CONSTRAINT - * 2 = LINEHINGE_CONSTRAINT - * 3 = ANGULAR_CONSTRAINT (aka LINEHINGE_CONSTRAINT) - * 4 = CONETWIST_CONSTRAINT - * 11 = VEHICLE_CONSTRAINT - * 12 = GENERIC_6DOF_CONSTRAINT diff --git a/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst b/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst index 1961f5e3e92..ca35ff49a08 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_FontObject.rst @@ -7,6 +7,26 @@ base class --- :class:`KX_GameObject` .. class:: KX_FontObject(KX_GameObject) - TODO. + A Font object. + .. code-block:: python + + # Display a message about the exit key using a Font object. + import bge + + co = bge.logic.getCurrentController() + font = co.owner + + exit_key = bge.events.EventToString(bge.logic.getExitKey()) + + if exit_key.endswith("KEY"): + exit_key = exit_key[:-3] + + font.text = "Press key '%s' to quit the game." % exit_key + + .. attribute:: text + + The text displayed by this Font object. + + :type: string diff --git a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst index ebde93f872f..672df3728a9 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_GameObject.rst @@ -78,6 +78,14 @@ base class --- :class:`SCA_IObject` The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0. + .. attribute:: isSuspendDynamics + + The object's dynamic state (read-only). + + :type: boolean + + .. seealso:: :py:meth:`suspendDynamics` and :py:meth:`restoreDynamics` allow you to change the state. + .. attribute:: linearDamping The object's linear damping, also known as translational damping. Can be set simultaneously with angular damping using the :py:meth:`setDamping` method. @@ -155,6 +163,18 @@ base class --- :class:`SCA_IObject` :type: :class:`KX_GameObject` or None + .. attribute:: collisionGroup + + The object's collision group. + + :type: bitfield + + .. attribute:: collisionMask + + The object's collision mask. + + :type: bitfield + .. attribute:: collisionCallbacks A list of functions to be called when a collision occurs. @@ -432,6 +452,12 @@ base class --- :class:`SCA_IObject` If true, the object's and children's debug properties will be displayed on screen. :type: boolean + + .. attribute:: currentLodLevel + + The index of the level of detail (LOD) currently used by this object (read-only). + + :type: int .. method:: endObject() @@ -647,13 +673,19 @@ base class --- :class:`SCA_IObject` :arg angular_damping: Angular ("rotational") damping factor. :type angular_damping: float ∈ [0, 1] - .. method:: suspendDynamics() + .. method:: suspendDynamics([ghost]) Suspends physics for this object. + :arg ghost: When set to `True`, collisions with the object will be ignored, similar to the "ghost" checkbox in + Blender. When `False` (the default), the object becomes static but still collide with other objects. + :type ghost: bool + + .. seealso:: :py:attr:`isSuspendDynamics` allows you to inspect whether the object is in a suspended state. + .. method:: restoreDynamics() - Resumes physics for this object. + Resumes physics for this object. Also reinstates collisions; the object will no longer be a ghost. .. note:: diff --git a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst index fc5ba357add..5bd8e3a77de 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst @@ -83,6 +83,12 @@ base class --- :class:`PyObjectPlus` This can be set directly from python to avoid using the :class:`KX_SceneActuator`. + .. attribute:: world + + The current active world, (read-only). + + :type: :class:`KX_WorldInfo` + .. attribute:: suspended True if the scene is suspended, (read-only). @@ -119,21 +125,27 @@ base class --- :class:`PyObjectPlus` :type: list + .. attribute:: pre_draw_setup + + A list of callables to be run before the drawing setup (i.e., before the model view and projection matrices are computed). + + :type: list + .. attribute:: gravity The scene gravity using the world x, y and z axis. :type: Vector((gx, gy, gz)) - .. method:: addObject(object, other, time=0) + .. method:: addObject(object, reference, time=0) Adds an object to the scene like the Add Object Actuator would. - :arg object: The object to add + :arg object: The (name of the) object to add. :type object: :class:`KX_GameObject` or string - :arg other: The object's center to use when adding the object - :type other: :class:`KX_GameObject` or string - :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever. + :arg reference: The (name of the) object which position, orientation, and scale to copy (optional), if the object to add is a light and there is not reference the light's layer will be the same that the active layer in the blender scene. + :type reference: :class:`KX_GameObject` or string + :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever (optional). :type time: integer :return: The newly added object. :rtype: :class:`KX_GameObject` diff --git a/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst b/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst new file mode 100644 index 00000000000..d0855c88d32 --- /dev/null +++ b/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst @@ -0,0 +1,79 @@ +KX_WordlInfo(PyObjectPlus) +============================= + +.. module:: bge.types + +base class --- :class:`PyObjectPlus` + +.. class:: KX_WorldInfo(PyObjectPlus) + + A wolrd object. + + .. code-block:: python + + # Set the mist color to red. + import bge + + sce = bge.logic.getCurrentScene() + + sce.world.mistColor = [1.0, 0.0, 0.0] + + .. data:: KX_MIST_QUADRATIC + + Type of quadratic attenuation used to fade mist. + + .. data:: KX_MIST_LINEAR + + Type of linear attenuation used to fade mist. + + .. data:: KX_MIST_INV_QUADRATIC + + Type of inverse quadratic attenuation used to fade mist. + + .. attribute:: mistEnable + + Return the state of the mist. + + :type: bool + + .. attribute:: mistStart + + The mist start point. + + :type: float + + .. attribute:: mistDistance + + The mist distance fom the start point to reach 100% mist. + + :type: float + + .. attribute:: mistIntensity + + The mist intensity. + + :type: float + + .. attribute:: mistType + + The type of mist - must be KX_MIST_QUADRATIC, KX_MIST_LINEAR or KX_MIST_INV_QUADRATIC + + .. attribute:: mistColor + + The color of the mist. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + Mist and background color sould always set to the same color. + + :type: :class:`mathutils.Vector` + + .. attribute:: backgroundColor + + The color of the background. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + Mist and background color sould always set to the same color. + + :type: :class:`mathutils.Vector` + + .. attribute:: ambientColor + + The color of the ambient light. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]. + + :type: :class:`mathutils.Vector` diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst index 9efd2e2d63a..af444fb9e65 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst @@ -23,8 +23,14 @@ base class --- :class:`SCA_ILogicBrick` .. attribute:: frequency - The frequency for pulse mode sensors. - + The frequency for pulse mode sensors. (Deprecated: use SCA_ISensor.skippedTicks) + + :type: integer + + .. attribute:: skippedTicks + + Number of logic ticks skipped between 2 active pulses + :type: integer .. attribute:: level diff --git a/doc/python_api/rst/info_gotcha.rst b/doc/python_api/rst/info_gotcha.rst index 35f9c1bda9f..aad23112b42 100644 --- a/doc/python_api/rst/info_gotcha.rst +++ b/doc/python_api/rst/info_gotcha.rst @@ -86,9 +86,15 @@ Consider the calculations that might go into working out the object's final tran 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: + +.. code-block:: python + + bpy.context.object.location = 1, 2, 3 + bpy.context.scene.update() -This can be done by calling :class:`bpy.types.Scene.update` after modifying values which recalculates all data that is tagged to be updated. +Now all dependent data (child objects, modifiers, drivers... etc) has been recalculated and is available to the script. Can I redraw during the script? ------------------------------- |