diff options
Diffstat (limited to 'doc/python_api/rst/bge_types')
9 files changed, 282 insertions, 308 deletions
diff --git a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst index 0dfc7a10d13..80450526c9a 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_BlenderMaterial.rst @@ -7,11 +7,66 @@ base class --- :class:`PyObjectPlus` .. class:: KX_BlenderMaterial(PyObjectPlus) - KX_BlenderMaterial + This is the interface to materials in the game engine. + + Materials define the render state to be applied to mesh objects. + + The example below shows a simple GLSL shader setup allowing to dynamically mix two texture channels + in a material. All materials of the object executing this script should have two textures using + separate UV maps in the two first texture channels. + + The code works for both Multitexture and GLSL rendering modes. + + .. code-block:: python + + from bge import logic + + vertex_shader = """ + + void main(void) + { + // simple projection of the vertex position to view space + gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex; + // coordinate of the 1st texture channel + gl_TexCoord[0] = gl_MultiTexCoord0; + // coordinate of the 2nd texture channel + gl_TexCoord[1] = gl_MultiTexCoord1; + } + """ + + fragment_shader =""" + + uniform sampler2D texture_0; + uniform sampler2D texture_1; + uniform float factor; + + void main(void) + { + vec4 color_0 = texture2D(texture_0, gl_TexCoord[0].st); + vec4 color_1 = texture2D(texture_1, gl_TexCoord[1].st); + gl_FragColor = mix(color_0, color_1, factor); + } + """ + + object = logic.getCurrentController().owner + + for mesh in object.meshes: + for material in mesh.materials: + shader = material.getShader() + if shader is not None: + if not shader.isValid(): + shader.setSource(vertex_shader, fragment_shader, True) + + # get the first texture channel of the material + shader.setSampler('texture_0', 0) + # get the second texture channel of the material + shader.setSampler('texture_1', 1) + # pass another uniform to the shader + shader.setUniform1f('factor', 0.3) .. attribute:: shader - The materials shader. + The material's shader. :type: :class:`BL_Shader` @@ -38,35 +93,37 @@ base class --- :class:`PyObjectPlus` Set the pixel color arithmetic functions. - :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed. - :type src: Value in... - - * GL_ZERO, - * GL_ONE, - * GL_SRC_COLOR, - * GL_ONE_MINUS_SRC_COLOR, - * GL_DST_COLOR, - * GL_ONE_MINUS_DST_COLOR, - * GL_SRC_ALPHA, - * GL_ONE_MINUS_SRC_ALPHA, - * GL_DST_ALPHA, - * GL_ONE_MINUS_DST_ALPHA, - * GL_SRC_ALPHA_SATURATE - - :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed. - :type dest: Value in... - - * GL_ZERO - * GL_ONE - * GL_SRC_COLOR - * GL_ONE_MINUS_SRC_COLOR - * GL_DST_COLOR - * GL_ONE_MINUS_DST_COLOR - * GL_SRC_ALPHA - * GL_ONE_MINUS_SRC_ALPHA - * GL_DST_ALPHA - * GL_ONE_MINUS_DST_ALPHA - * GL_SRC_ALPHA_SATURATE + :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed, one of... + + * :data:`~bgl.GL_ZERO` + * :data:`~bgl.GL_ONE` + * :data:`~bgl.GL_SRC_COLOR` + * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR` + * :data:`~bgl.GL_DST_COLOR` + * :data:`~bgl.GL_ONE_MINUS_DST_COLOR` + * :data:`~bgl.GL_SRC_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA` + * :data:`~bgl.GL_DST_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA` + * :data:`~bgl.GL_SRC_ALPHA_SATURATE` + + :type src: int + + :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed, one of... + + * :data:`~bgl.GL_ZERO` + * :data:`~bgl.GL_ONE` + * :data:`~bgl.GL_SRC_COLOR` + * :data:`~bgl.GL_ONE_MINUS_SRC_COLOR` + * :data:`~bgl.GL_DST_COLOR` + * :data:`~bgl.GL_ONE_MINUS_DST_COLOR` + * :data:`~bgl.GL_SRC_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_SRC_ALPHA` + * :data:`~bgl.GL_DST_ALPHA` + * :data:`~bgl.GL_ONE_MINUS_DST_ALPHA` + * :data:`~bgl.GL_SRC_ALPHA_SATURATE` + + :type dest: int .. method:: getMaterialIndex() 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 8d6996dc401..a24aa546cb9 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. @@ -131,6 +139,29 @@ base class --- :class:`SCA_IObject` A value of 0.0 disables this option (rather then setting it stationary). + .. attribute:: angularVelocityMin + + Enforces the object keeps rotating at a minimum velocity. A value of 0.0 disables this. + + :type: non-negative float + + .. note:: + + Applies to dynamic and rigid body objects only. + While objects are stationary the minimum velocity will not be applied. + + + .. attribute:: angularVelocityMax + + Clamp the maximum angular velocity to prevent objects rotating beyond a set speed. + A value of 0.0 disables clamping; it does not stop rotation. + + :type: non-negative float + + .. note:: + + Applies to dynamic and rigid body objects only. + .. attribute:: localInertia the object's inertia vector in local coordinates. Read only. @@ -155,6 +186,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. @@ -653,13 +696,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_PolygonMaterial.rst b/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst deleted file mode 100644 index 3421e194d77..00000000000 --- a/doc/python_api/rst/bge_types/bge.types.KX_PolygonMaterial.rst +++ /dev/null @@ -1,250 +0,0 @@ -KX_PolygonMaterial(PyObjectPlus) -================================ - -.. module:: bge.types - -base class --- :class:`PyObjectPlus` - -.. class:: KX_PolygonMaterial(PyObjectPlus) - - This is the interface to materials in the game engine. - - Materials define the render state to be applied to mesh objects. - - .. warning:: - - Some of the methods/variables are CObjects. If you mix these up, you will crash blender. - - .. code-block:: python - - from bge import logic - - vertex_shader = """ - - void main(void) - { - // original vertex position, no changes - gl_Position = ftransform(); - // coordinate of the 1st texture channel - gl_TexCoord[0] = gl_MultiTexCoord0; - // coordinate of the 2nd texture channel - gl_TexCoord[1] = gl_MultiTexCoord1; - } - """ - - fragment_shader =""" - - uniform sampler2D color_0; - uniform sampler2D color_1; - uniform float factor; - - void main(void) - { - vec4 color_0 = texture2D(color_0, gl_TexCoord[0].st); - vec4 color_1 = texture2D(color_1, gl_TexCoord[1].st); - gl_FragColor = mix(color_0, color_1, factor); - } - """ - - object = logic.getCurrentController().owner - object = cont.owner - for mesh in object.meshes: - for material in mesh.materials: - shader = material.getShader() - if shader != None: - if not shader.isValid(): - shader.setSource(vertex_shader, fragment_shader, True) - - # get the first texture channel of the material - shader.setSampler('color_0', 0) - # get the second texture channel of the material - shader.setSampler('color_1', 1) - # pass another uniform to the shader - shader.setUniform1f('factor', 0.3) - - - .. attribute:: texture - - Texture name. - - :type: string (read-only) - - .. attribute:: gl_texture - - OpenGL texture handle (eg for glBindTexture(GL_TEXTURE_2D, gl_texture). - - :type: integer (read-only) - - .. attribute:: material - - Material name. - - :type: string (read-only) - - .. attribute:: tface - - Texture face properties. - - :type: CObject (read-only) - - .. attribute:: tile - - Texture is tiling. - - :type: boolean - - .. attribute:: tilexrep - - Number of tile repetitions in x direction. - - :type: integer - - .. attribute:: tileyrep - - Number of tile repetitions in y direction. - - :type: integer - - .. attribute:: drawingmode - - Drawing mode for the material. - - 2 (drawingmode & 4) Textured - - 4 (drawingmode & 16) Light - - 14 (drawingmode & 16384) 3d Polygon Text. - - :type: bitfield - - .. attribute:: transparent - - This material is transparent. All meshes with this - material will be rendered after non transparent meshes from back - to front. - - :type: boolean - - .. attribute:: zsort - - Transparent polygons in meshes with this material will be sorted back to - front before rendering. - Non-Transparent polygons will be sorted front to back before rendering. - - :type: boolean - - .. attribute:: diffuse - - The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0]. - - :type: list [r, g, b] - - .. attribute:: specular - - The specular color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0]. - - :type: list [r, g, b] - - .. attribute:: shininess - - The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0. - - :type: float - - .. attribute:: specularity - - The amount of specular of the material. 0.0 <= specularity <= 1.0. - - :type: float - - .. method:: updateTexture(tface, rasty) - - Updates a realtime animation. - - :arg tface: Texture face (eg mat.tface) - :type tface: CObject - :arg rasty: Rasterizer - :type rasty: CObject - - .. method:: setTexture(tface) - - Sets texture render state. - - :arg tface: Texture face - :type tface: CObject - - .. code-block:: python - - mat.setTexture(mat.tface) - - .. method:: activate(rasty, cachingInfo) - - Sets material parameters for this object for rendering. - - Material Parameters set: - - #. Texture - #. Backface culling - #. Line drawing - #. Specular Colour - #. Shininess - #. Diffuse Colour - #. Polygon Offset. - - :arg rasty: Rasterizer instance. - :type rasty: CObject - :arg cachingInfo: Material cache instance. - :type cachingInfo: CObject - - .. method:: setCustomMaterial(material) - - Sets the material state setup object. - - Using this method, you can extend or completely replace the gameengine material - to do your own advanced multipass effects. - - Use this method to register your material class. Instead of the normal material, - your class's activate method will be called just before rendering the mesh. - This should setup the texture, material, and any other state you would like. - It should return True to render the mesh, or False if you are finished. You should - clean up any state Blender does not set before returning False. - - Activate Method Definition: - - .. code-block:: python - - def activate(self, rasty, cachingInfo, material): - - :arg material: The material object. - :type material: instance - - .. code-block:: python - - class PyMaterial: - def __init__(self): - self.pass_no = -1 - - def activate(self, rasty, cachingInfo, material): - # Activate the material here. - # - # The activate method will be called until it returns False. - # Every time the activate method returns True the mesh will - # be rendered. - # - # rasty is a CObject for passing to material.updateTexture() - # and material.activate() - # cachingInfo is a CObject for passing to material.activate() - # material is the KX_PolygonMaterial instance this material - # was added to - - # default material properties: - self.pass_no += 1 - if self.pass_no == 0: - material.activate(rasty, cachingInfo) - # Return True to do this pass - return True - - # clean up and return False to finish. - self.pass_no = -1 - return False - - # Create a new Python Material and pass it to the renderer. - mat.setCustomMaterial(PyMaterial()) - 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_2DFilterActuator.rst b/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst index 291ee8426cf..0a6c5fc9025 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_2DFilterActuator.rst @@ -7,7 +7,7 @@ base class --- :class:`SCA_IActuator` .. class:: SCA_2DFilterActuator(SCA_IActuator) - Create, enable and disable 2D filters + Create, enable and disable 2D filters. The following properties don't have an immediate effect. You must active the actuator to get the result. @@ -29,7 +29,7 @@ base class --- :class:`SCA_IActuator` .. attribute:: mode - Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>` + Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>`. :type: integer 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 |