diff options
Diffstat (limited to 'doc/python_api/rst')
31 files changed, 2696 insertions, 1583 deletions
diff --git a/doc/python_api/rst/bge.app.rst b/doc/python_api/rst/bge.app.rst new file mode 100644 index 00000000000..a0c2cf36314 --- /dev/null +++ b/doc/python_api/rst/bge.app.rst @@ -0,0 +1,47 @@ + +Application Data (bge.app) +========================== + +Module to access application values that remain unchanged during runtime. + +.. module:: bge.app + +.. data:: version + + The Blender/BGE version as a tuple of 3 ints, eg. (2, 75, 1). + + .. note:: Version tuples can be compared simply with (in)equality symbols; + for example, ``(2, 74, 5) <= (2, 75, 0)`` returns True (lexical order). + + :type: tuple of three ints + +.. data:: version_string + + The Blender/BGE version formatted as a string, eg. "2.75 (sub 1)". + + :type: str + +.. data:: version_char + + The Blender/BGE version character (for minor releases). + + :type: str + +.. data:: has_texture_ffmpeg + + True if the BGE has been built with FFmpeg support, enabling use of :class:`~bge.texture.ImageFFmpeg` and :class:`~bge.texture.VideoFFmpeg`. + + :type: bool + +.. data:: has_joystick + + True if the BGE has been built with joystick support. + + :type: bool + +.. data:: has_physics + + True if the BGE has been built with physics support. + + :type: bool + diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst index 018be96fd14..bf015057dcb 100644 --- a/doc/python_api/rst/bge.constraints.rst +++ b/doc/python_api/rst/bge.constraints.rst @@ -4,72 +4,77 @@ Physics Constraints (bge.constraints) .. module:: bge.constraints -.. literalinclude:: ../examples/bge.constraints.py - :language: rest - :lines: 2-4 + +Examples +-------- + +.. include:: ../examples/bge.constraints.py + :start-line: 1 + :end-line: 4 .. literalinclude:: ../examples/bge.constraints.py :lines: 6- -.. function:: createConstraint(physicsid, physicsid2, constrainttype, [pivotX, pivotY, pivotZ, [axisX, axisY, axisZ, [flag]]]]) - Creates a constraint. +Functions +--------- - :arg physicsid: the physics id of the first object in constraint - :type physicsid: int +.. function:: createConstraint( \ + physicsid_1, physicsid_2, constraint_type, \ + pivot_x=0.0, pivot_y=0.0, pivot_z=0.0, \ + axis_x=0.0, axis_y=0.0, axis_z=0.0, flag=0) - :arg physicsid2: the physics id of the second object in constraint - :type physicsid2: int + Creates a constraint. - :arg constrainttype: the type of the constraint. The constraint types are: + :arg physicsid_1: The physics id of the first object in constraint. + :type physicsid_1: int - - :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 - :type constrainttype: int + :arg constraint_type: The type of the constraint, see `Create Constraint Constants`_. - :arg pivotX: pivot X position - :type pivotX: float + :type constraint_type: int - :arg pivotY: pivot Y position - :type pivotY: float + :arg pivot_x: Pivot X position. (optional) + :type pivot_x: float - :arg pivotZ: pivot Z position - :type pivotZ: float + :arg pivot_y: Pivot Y position. (optional) + :type pivot_y: float - :arg axisX: X axis - :type axisX: float + :arg pivot_z: Pivot Z position. (optional) + :type pivot_z: float - :arg axisY: Y axis - :type axisY: float + :arg axis_x: X axis angle in degrees. (optional) + :type axis_x: float - :arg axisZ: Z axis - :type axisZ: float + :arg axis_y: Y axis angle in degrees. (optional) + :type axis_y: float - :arg flag: 128 to disable collision between linked bodies - :type flag: int + :arg axis_z: Z axis angle in degrees. (optional) + :type axis_z: float -.. attribute:: error + :arg flag: 128 to disable collision between linked bodies. (optional) + :type flag: int - Simbolic constant string that indicates error. + :return: A constraint wrapper. + :rtype: :class:`~bge.types.KX_ConstraintWrapper` .. function:: exportBulletFile(filename) - export a .bullet file + Exports a file representing the dynamics world (usually using ``.bullet`` extension). + + See `Bullet binary serialization <http://bulletphysics.org/mediawiki-1.5.8/index.php/Bullet_binary_serialization>`__. - :arg filename: File name - :type filename: string + :arg filename: File path. + :type filename: str .. function:: getAppliedImpulse(constraintId) :arg constraintId: The id of the constraint. :type constraintId: int - :return: the most recent applied impulse. + :return: The most recent applied impulse. :rtype: float .. function:: getVehicleConstraint(constraintId) @@ -77,16 +82,16 @@ Physics Constraints (bge.constraints) :arg constraintId: The id of the vehicle constraint. :type constraintId: int - :return: a vehicle constraint object. - :rtype: :class:`bge.types.KX_VehicleWrapper` + :return: A vehicle constraint object. + :rtype: :class:`~bge.types.KX_VehicleWrapper` .. function:: getCharacter(gameobj) :arg gameobj: The game object with the character physics. - :type gameobj: :class:`bge.types.KX_GameObject` + :type gameobj: :class:`~bge.types.KX_GameObject` - :return: character wrapper - :rtype: :class:`bge.types.KX_CharacterWrapper` + :return: Character wrapper. + :rtype: :class:`~bge.types.KX_CharacterWrapper` .. function:: removeConstraint(constraintId) @@ -140,23 +145,8 @@ Physics Constraints (bge.constraints) Sets the debug mode. - Debug modes: - - :class:`DBG_NODEBUG` - - :class:`DBG_DRAWWIREFRAME` - - :class:`DBG_DRAWAABB` - - :class:`DBG_DRAWFREATURESTEXT` - - :class:`DBG_DRAWCONTACTPOINTS` - - :class:`DBG_NOHELPTEXT` - - :class:`DBG_DRAWTEXT` - - :class:`DBG_PROFILETIMINGS` - - :class:`DBG_ENABLESATCOMPARISION` - - :class:`DBG_DISABLEBULLETLCP` - - :class:`DBG_ENABLECCD` - - :class:`DBG_DRAWCONSTRAINTS` - - :class:`DBG_DRAWCONSTRAINTLIMITS` - - :class:`DBG_FASTWIREFRAME` - - :arg mode: The new debug mode. + :arg mode: The new debug mode, see `Debug Mode Constants`_. + :type mode: int .. function:: setGravity(x, y, z) @@ -175,7 +165,8 @@ Physics Constraints (bge.constraints) .. function:: setLinearAirDamping(damping) .. note:: - Not implemented. + + Not implemented Sets the linear air damping for rigidbodies. @@ -235,144 +226,111 @@ Physics Constraints (bge.constraints) .. function:: setUseEpa(epa) - Not implemented. + .. note:: -.. data:: DBG_NODEBUG + Not implemented - .. note:: - Debug mode to be used with function :class:`setDebugMode` + +Constants ++++++++++ + +.. attribute:: error + + Symbolic constant string that indicates error. + + :type: str + + +Debug Mode Constants +^^^^^^^^^^^^^^^^^^^^ + +Debug mode to be used with :func:`setDebugMode`. + + +.. data:: DBG_NODEBUG No debug. .. data:: DBG_DRAWWIREFRAME - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw wireframe in debug. .. data:: DBG_DRAWAABB - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw Axis Aligned Bounding Box in debug. .. data:: DBG_DRAWFREATURESTEXT - .. note:: - Debug mode to be used with function :class:`setDebugMode` - - Draw freatures text in debug. + Draw features text in debug. .. data:: DBG_DRAWCONTACTPOINTS - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw contact points in debug. .. data:: DBG_NOHELPTEXT - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Debug without help text. .. data:: DBG_DRAWTEXT - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw text in debug. .. data:: DBG_PROFILETIMINGS - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw profile timings in debug. .. data:: DBG_ENABLESATCOMPARISION - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Enable sat comparision in debug. .. data:: DBG_DISABLEBULLETLCP - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Disable Bullet LCP. .. data:: DBG_ENABLECCD - .. note:: - Debug mode to be used with function :class:`setDebugMode` - - Enable Continous Colision Detection in debug. + Enable Continous Collision Detection in debug. .. data:: DBG_DRAWCONSTRAINTS - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw constraints in debug. .. data:: DBG_DRAWCONSTRAINTLIMITS - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw constraint limits in debug. .. data:: DBG_FASTWIREFRAME - .. note:: - Debug mode to be used with function :class:`setDebugMode` - Draw a fast wireframe in debug. -.. data:: POINTTOPOINT_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` +Create Constraint Constants +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Constraint type to be used with :func:`createConstraint`. + + +.. data:: POINTTOPOINT_CONSTRAINT .. to do .. data:: LINEHINGE_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` - .. to do .. data:: ANGULAR_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` - .. to do .. data:: CONETWIST_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` - .. to do .. data:: VEHICLE_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` - .. to do .. data:: GENERIC_6DOF_CONSTRAINT - .. note:: - Constraint type to be used with function :class:`createConstraint` - .. to do + diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst index d901a4e4207..57d9f1ab5e5 100644 --- a/doc/python_api/rst/bge.logic.rst +++ b/doc/python_api/rst/bge.logic.rst @@ -337,6 +337,28 @@ General functions .. warning: Not implimented yet +.. function:: getAnimRecordFrame() + + Gets the current frame number used for recording animations. This + number is incremented automatically by Blender when the "Record + animation" feature is turned on. + + :rtype: int + +.. function:: setAnimRecordFrame(framenr) + + Sets the current frame number used for recording animations. This + number is automatically incremented by Blender when the "Record + animation" feature is turned on. + + The frame number Must be non-negative, unless Blender has + :attr:`bpy.types.UserPreferencesEdit.use_negative_frames` enabled + in its user preferences. Only use non-negative numbers to be on + the safe side, unless you know what you are doing. + + :arg framenr: The new frame number. + :type framenr: int + .. function:: getExitKey() Gets the key used to exit the game engine @@ -894,6 +916,8 @@ Various 2D Filter --------- +.. _Two-D-FilterActuator-mode: + .. data:: RAS_2DFILTER_BLUR :value: 2 @@ -1288,5 +1312,3 @@ See :class:`bge.types.KX_StateActuator.operation` Add bits to state mask :value: 3 - -.. _Two-D-FilterActuator-mode: diff --git a/doc/python_api/rst/bge.render.rst b/doc/python_api/rst/bge.render.rst index 9dd4057c82f..2afb2796249 100644 --- a/doc/python_api/rst/bge.render.rst +++ b/doc/python_api/rst/bge.render.rst @@ -8,9 +8,14 @@ Intro .. module:: bge.render +Example of using a :class:`bge.types.SCA_MouseSensor`, +and two :class:`bge.types.KX_ObjectActuator` to implement MouseLook: + +.. note:: + This can also be achieved with the :class:`bge.types.KX_MouseActuator`. + .. code-block:: python - # Example Uses an L{SCA_MouseSensor}, and two L{KX_ObjectActuator}s to implement MouseLook:: # To use a mouse movement sensor "Mouse" and a # motion actuator to mouse look: import bge @@ -62,7 +67,7 @@ Constants .. data:: KX_BLENDER_GLSL_MATERIAL Materials approximating blender materials with GLSL. - + .. DATA:: VSYNC_OFF Disables vsync @@ -73,7 +78,18 @@ Constants .. DATA:: VSYNC_ADAPTIVE - Enables adaptive vsync if supported. Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. Otherwise, vsync is diabled if the framerate is too low. + Enables adaptive vsync if supported. + Adaptive vsync enables vsync if the framerate is above the monitors refresh rate. + Otherwise, vsync is diabled if the framerate is too low. + +.. data:: LEFT_EYE + + Left eye being used during stereoscopic rendering. + +.. data:: RIGHT_EYE + + Right eye being used during stereoscopic rendering. + ********* Functions @@ -82,47 +98,64 @@ 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. - + + .. note:: Only works in the standalone player, not the Blender-embedded player. + :type width: integer :type height: integer .. function:: setFullScreen(enable) Set whether or not the window should be fullscreen. - + + .. note:: Only works in the standalone player, not the Blender-embedded player. + :type enable: bool .. function:: getFullScreen() Returns whether or not the window is fullscreen. - + + .. note:: Only works in the standalone player, not the Blender-embedded player; there it always returns False. + :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 @@ -134,65 +167,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 mist start value. Objects further away than start will have mist applied to them. - - :type start: float + Sets the window background color. (Deprecated: use KX_WorldInfo.background_color) + :type rgba: list [r, g, b, a] -.. 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() - - 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 @@ -200,27 +197,36 @@ 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() + + Gets the current stereoscopy eye being rendered. + This function is mainly used in a :class:`bge.types.KX_Scene.pre_draw` callback + function to customize the camera projection matrices for each + stereoscopic eye. + + :rtype: LEFT_EYE, RIGHT_EYE + .. 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. @@ -229,14 +235,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 @@ -244,43 +250,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 @@ -292,7 +298,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.texture.rst b/doc/python_api/rst/bge.texture.rst index 0c9e9da0661..4588a3e1800 100644 --- a/doc/python_api/rst/bge.texture.rst +++ b/doc/python_api/rst/bge.texture.rst @@ -2,9 +2,9 @@ Video Texture (bge.texture) =========================== -***** -Intro -***** +************ +Introduction +************ The bge.texture module allows you to manipulate textures during the game. @@ -14,7 +14,7 @@ The video and image files can be loaded from the internet using an URL instead o In addition, you can apply filters on the images before sending them to the GPU, allowing video effect: blue screen, color band, gray, normal map. -bge.texture uses FFmpeg to load images and videos. All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to:: +bge.texture uses FFmpeg to load images and videos. All the formats and codecs that FFmpeg supports are supported by this module, including but not limited to: * AVI * Ogg @@ -26,7 +26,7 @@ bge.texture uses FFmpeg to load images and videos. All the formats and codecs th * JPG The principle is simple: first you identify a texture on an existing object using -the :materialID: function, then you create a new texture with dynamic content +the :class:`~bge.texture.materialID` function, then you create a new texture with dynamic content and swap the two textures in the GPU. The GE is not aware of the substitution and continues to display the object as always, @@ -36,538 +36,998 @@ When the texture object is deleted, the new texture is deleted and the old textu .. module:: bge.texture +.. include:: ../examples/bge.texture.py + :start-line: 1 + :end-line: 5 + .. literalinclude:: ../examples/bge.texture.py - :language: rest - :lines: 2-4 - -.. literalinclude:: ../examples/bge.texture.py - :lines: 6- - -.. literalinclude:: ../examples/bge.texture.1.py - :language: rest - :lines: 2-6 + :lines: 7- +.. include:: ../examples/bge.texture.1.py + :start-line: 1 + :end-line: 6 + .. literalinclude:: ../examples/bge.texture.1.py :lines: 8- - -.. class:: VideoFFmpeg(file [, capture=-1, rate=25.0, width=0, height=0]) - - FFmpeg video source + + +************* +Video classes +************* + +.. class:: VideoFFmpeg(file, capture=-1, rate=25.0, width=0, height=0) + + FFmpeg video source. + + :arg file: Path to the video to load; if capture >= 0 on Windows, this parameter will not be used. + :type file: str + :arg capture: Capture device number; if >= 0, the corresponding webcam will be used. (optional) + :type capture: int + :arg rate: Capture rate. (optional, used only if capture >= 0) + :type rate: float + :arg width: Capture width. (optional, used only if capture >= 0) + :type width: int + :arg height: Capture height. (optional, used only if capture >= 0) + :type height: int .. attribute:: status - video status + Video status. (readonly) + + :type: int + :value: see `FFmpeg Video and Image Status`_. .. attribute:: range - replay range + Replay range. + + :type: sequence of two floats .. attribute:: repeat - repeat count, -1 for infinite repeat + Repeat count, -1 for infinite repeat. :type: int .. attribute:: framerate - frame rate + Frame rate. :type: float .. attribute:: valid - Tells if an image is available + Tells if an image is available. (readonly) :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None .. attribute:: size - image size + Image size. (readonly) + + :type: tuple of two ints .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: preseek - number of frames of preseek + Number of frames of preseek. :type: int .. attribute:: deinterlace - deinterlace image + Deinterlace image. :type: bool .. method:: play() - Play (restart) video + Play (restart) video. + + :return: Whether the video was ready or stopped. + :rtype: bool .. method:: pause() - pause video + Pause video. + + :return: Whether the video was playing. + :rtype: bool .. method:: stop() - stop video (play will replay it from start) + Stop video (play will replay it from start). + + :return: Whether the video was playing. + :rtype: bool .. method:: refresh() - Refresh video - get its status + Refresh video - get its status. + + :value: see `FFmpeg Video and Image Status`_. + + :rtype: int + +************* +Image classes +************* .. class:: ImageFFmpeg(file) - FFmpeg image source + FFmpeg image source. + + :arg file: Path to the image to load. + :type file: str .. attribute:: status - video status + Image status. (readonly) + + :type: int + :value: see `FFmpeg Video and Image Status`_. .. attribute:: valid - Tells if an image is available + Tells if an image is available. (readonly) :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None .. attribute:: size - image size + Image size. (readonly) + + :type: tuple of two ints .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. method:: refresh() - Refresh image, i.e. load it + Refresh image, i.e. load it. + + :value: see `FFmpeg Video and Image Status`_. + + :rtype: int - .. method:: reload([newname]) + .. method:: reload(newname=None) - Reload image, i.e. reopen it + Reload image, i.e. reopen it. + + :arg newname: Path to a new image. (optional) + :type newname: str -.. class:: ImageBuff() +.. class:: ImageBuff(width, height, color=0, scale=False) - Image source from image buffer + Image source from image buffer. + + :arg width: Width of the image. + :type width: int + :arg height: Height of the image. + :type height: int + :arg color: Value to initialize RGB channels with. The initialized buffer will have + all pixels set to (color, color, color, 255). (optional) + :type color: int in [0, 255] + :arg scale: Image uses scaling. (optional) + :type scale: bool .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None .. method:: load(imageBuffer, width, height) - Load image from buffer - - .. method:: plot(imageBuffer, width, height, positionX, positionY) - - update image buffer + Load image from buffer. + + :arg imageBuffer: Buffer to load the image from. + :type imageBuffer: :class:`~bgl.Buffer` or Python object implementing the buffer protocol (f.ex. bytes) + :arg width: Width of the image to load. + :type width: int + :arg height: Height of the image to load. + :type height: int + + .. method:: plot(imageBuffer, width, height, positionX, positionY, mode=IMB_BLEND_COPY) + + Update image buffer. + + :arg imageBuffer: Buffer to load the new data from. + :type imageBuffer: :class:`~bgl.Buffer`, :class:`ImageBuff` or Python object implementing the buffer protocol (f.ex. bytes) + :arg width: Width of the data to load. + :type width: int + :arg height: Height of the data to load. + :type height: int + :arg positionX: Left boundary of the region to be drawn on. + :type positionX: int + :arg positionY: Upper boundary of the region to be drawn on. + :type positionY: int + :arg mode: Drawing mode, see `Image Blending Modes`_. + :type mode: int + .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: size - image size + Image size. (readonly) + + :type: tuple of two ints .. attribute:: valid - bool to tell if an image is available + Tells if an image is available. (readonly) -.. class:: ImageMirror(scene) + :type: bool + +.. class:: ImageMirror(scene, observer, mirror, material=0) - Image source from mirror + Image source from mirror. + + :arg scene: Scene in which the image has to be taken. + :type scene: :class:`~bge.types.KX_Scene` + :arg observer: Reference object for the mirror (the object from which the mirror has to be looked at, for example a camera). + :type observer: :class:`~bge.types.KX_GameObject` + :arg mirror: Object holding the mirror. + :type mirror: :class:`~bge.types.KX_GameObject` + :arg material: ID of the mirror's material to be used for mirroring. (optional) + :type material: int .. attribute:: alpha - use alpha in texture + Use alpha in texture. + + :type: bool .. attribute:: background - background color + Background color. + + :type: int or float list [r, g, b, a] in [0.0, 255.0] .. attribute:: capsize - size of render area + Size of render area. + + :type: sequence of two ints .. attribute:: clip - clipping distance + Clipping distance. + + :type: float in [0.01, 5000.0] .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None - .. method:: refresh(imageMirror) + .. method:: refresh() - Refresh image - invalidate its current content + Refresh image - invalidate its current content. .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: size - image size + Image size (readonly). + + :type: tuple of two ints .. attribute:: valid - bool to tell if an image is available + Tells if an image is available. (readonly) + + :type: bool .. attribute:: whole - use whole viewport to render + Use whole viewport to render. + + :type: bool -.. class:: ImageMix() +.. class:: ImageMix - Image mixer + Image mixer. .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: flip - flip image vertically - - .. method:: getSource(imageMix) - - get image source - - .. method:: getWeight(imageMix) - - get image source weight + Flip image vertically. + + :type: bool + .. method:: getSource(id) + + Get image source. + + :arg id: Identifier of the source to get. + :type id: str + + :return: Image source. + :rtype: one of... + + * :class:`VideoFFmpeg` + * :class:`ImageFFmpeg` + * :class:`ImageBuff` + * :class:`ImageMirror` + * :class:`ImageMix` + * :class:`ImageRender` + * :class:`ImageViewport` + + .. method:: getWeight(id) + + Get image source weight. + + :arg id: Identifier of the source. + :type id: str + + :return: Weight of the source. + :rtype: int .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None - .. method:: refresh(imageMix) + .. method:: refresh() - Refresh image - invalidate its current content + Refresh image - invalidate its current content. .. attribute:: scale - fast scale of image (near neighbour) - - .. method:: setSource(imageMix) - - set image source - - .. method:: setWeight(imageMix) + Fast scale of image (near neighbour). + + :type: bool + + .. attribute:: size - set image source weight + Image size. (readonly) + + :type: tuple of two ints + + .. method:: setSource(id, image) + + Set image source - all sources must have the same size. + + :arg id: Identifier of the source to set. + :type id: str + :arg image: Image source of type... + + * :class:`VideoFFmpeg` + * :class:`ImageFFmpeg` + * :class:`ImageBuff` + * :class:`ImageMirror` + * :class:`ImageMix` + * :class:`ImageRender` + * :class:`ImageViewport` + + .. method:: setWeight(id, weight) + + Set image source weight - the sum of the weights should be 256 to get full color intensity in the output. + + :arg id: Identifier of the source. + :type id: str + :arg weight: Weight of the source. + :type weight: int .. attribute:: valid - bool to tell if an image is available + Tells if an image is available. (readonly) + + :type: bool .. class:: ImageRender(scene, camera) - Image source from render + Image source from render. + + :arg scene: Scene in which the image has to be taken. + :type scene: :class:`~bge.types.KX_Scene` + :arg camera: Camera from which the image has to be taken. + :type camera: :class:`~bge.types.KX_Camera` .. attribute:: alpha - use alpha in texture + Use alpha in texture. + + :type: bool .. attribute:: background - background color + Background color. + + :type: int or float list [r, g, b, a] in [0.0, 255.0] .. attribute:: capsize - size of render area + Size of render area. + + :type: sequence of two ints .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None - .. method:: refresh(imageRender) + .. method:: refresh() - Refresh image - invalidate its current content + Refresh image - invalidate its current content. .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: size - image size + Image size. (readonly) + + :type: tuple of two ints .. attribute:: valid - bool to tell if an image is available + Tells if an image is available. (readonly) + + :type: bool .. attribute:: whole - use whole viewport to render + Use whole viewport to render. + + :type: bool .. attribute:: depth - use depth component of render as array of float - not suitable for texture source, - should only be used with bge.texture.imageToArray(mode='F') + Use depth component of render as array of float - not suitable for texture source, + should only be used with bge.texture.imageToArray(mode='F'). + + :type: bool .. attribute:: zbuff - use depth component of render as grey scale color - suitable for texture source + Use depth component of render as grey scale color - suitable for texture source. + + :type: bool -.. class:: ImageViewport() +.. class:: ImageViewport - Image source from viewport + Image source from viewport. .. attribute:: alpha - use alpha in texture + Use alpha in texture. + + :type: bool .. attribute:: capsize - size of viewport area being captured + Size of viewport area being captured. + + :type: sequence of two ints .. attribute:: filter - pixel filter + Pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` .. attribute:: flip - flip image vertically + Flip image vertically. + + :type: bool .. attribute:: image - image data + Image data. (readonly) + + :type: :class:`~bgl.Buffer` or None .. attribute:: position - upper left corner of captured area + Upper left corner of the captured area. + + :type: sequence of two ints - .. method:: refresh(imageViewport) + .. method:: refresh() - Refresh image - invalidate its current content + Refresh image - invalidate its current content. .. attribute:: scale - fast scale of image (near neighbour) + Fast scale of image (near neighbour). + + :type: bool .. attribute:: size - image size + Image size. (readonly) + + :type: tuple of two ints .. attribute:: valid - bool to tell if an image is available + Tells if an image is available. (readonly) + + :type: bool .. attribute:: whole - use whole viewport to capture + Use whole viewport to capture. + + :type: bool .. attribute:: depth - use depth component of viewport as array of float - not suitable for texture source, - should only be used with bge.texture.imageToArray(mode='F') + Use depth component of viewport as array of float - not suitable for texture source, + should only be used with bge.texture.imageToArray(mode='F'). + + :type: bool .. attribute:: zbuff - use depth component of viewport as grey scale color - suitable for texture source + Use depth component of viewport as grey scale color - suitable for texture source. + + :type: bool + + +*************** +Texture classes +*************** -.. class:: Texture(gameObj) +.. class:: Texture(gameObj, materialID=0, textureID=0, textureObj=None) - Texture objects + Texture object. + + :arg gameObj: Game object to be created a video texture on. + :type gameObj: :class:`~bge.types.KX_GameObject` + :arg materialID: Material ID. (optional) + :type materialID: int + :arg textureID: Texture ID. (optional) + :type textureID: int + :arg textureObj: Texture object with shared bindId. (optional) + :type textureObj: :class:`Texture` .. attribute:: bindId - OpenGL Bind Name + OpenGL Bind Name. (readonly) + + :type: int - .. method:: close(texture) + .. method:: close() - Close dynamic texture and restore original + Close dynamic texture and restore original. .. attribute:: mipmap - mipmap texture + Mipmap texture. + + :type: bool - .. method:: refresh(texture) + .. method:: refresh(refresh_source=True, ts=-1.0) - Refresh texture from source + Refresh texture from source. + + :arg refresh_source: Whether to also refresh the image source of the texture. + :type refresh_source: bool + :arg ts: If the texture controls a VideoFFmpeg object: + timestamp (in seconds from the start of the movie) of the frame to be loaded; this can be + used for video-sound synchonization by passing :attr:`~bge.types.KX_SoundActuator.time` to it. (optional) + :type ts: float .. attribute:: source - source of texture + Source of texture. + + :type: one of... + + * :class:`VideoFFmpeg` + * :class:`ImageFFmpeg` + * :class:`ImageBuff` + * :class:`ImageMirror` + * :class:`ImageMix` + * :class:`ImageRender` + * :class:`ImageViewport` + + +************** +Filter classes +************** -.. class:: FilterBGR24() - Source filter BGR24 objects +.. class:: FilterBGR24 -.. class:: FilterBlueScreen() + Source filter BGR24. - Filter for Blue Screen objects +.. class:: FilterBlueScreen + + Filter for Blue Screen. The RGB channels of the color are left unchanged, while the output alpha is obtained as follows: + + * if the square of the euclidian distance between the RGB color and the filter's reference color is smaller than the filter's lower limit, + the output alpha is set to 0; + + * if that square is bigger than the filter's upper limit, the output alpha is set to 255; + + * otherwise the output alpha is linarly extrapoled between 0 and 255 in the interval of the limits. .. attribute:: color - blue screen color + Reference color. + + :type: sequence of three ints + :default: (0, 0, 255) .. attribute:: limits - blue screen color limits + Reference color limits. + + :type: sequence of two ints + :default: (64, 64) .. attribute:: previous - previous pixel filter + Previous pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` -.. class:: FilterColor() +.. class:: FilterColor - Filter for color calculations + Filter for color calculations. The output color is obtained by multiplying the reduced 4x4 matrix with the input color + and adding the remaining column to the result. .. attribute:: matrix - matrix [4][5] for color calculation + Matrix [4][5] for color calculation. + + :type: sequence of four sequences of five ints + :default: ((256, 0, 0, 0, 0), (0, 256, 0, 0, 0), (0, 0, 256, 0, 0), (0, 0, 0, 256, 0)) .. attribute:: previous - previous pixel filter + Previous pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` -.. class:: FilterGray() +.. class:: FilterGray - Filter for gray scale effect + Filter for gray scale effect. Proportions of R, G and B contributions in the output gray scale are 28:151:77. .. attribute:: previous - previous pixel filter - -.. class:: FilterLevel() - - Filter for levels calculations + Previous pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` + +.. class:: FilterLevel + + Filter for levels calculations. Each output color component is obtained as follows: + + * if it is smaller than its corresponding min value, it is set to 0; + + * if it is bigger than its corresponding max value, it is set to 255; + + * Otherwise it is linearly extrapoled between 0 and 255 in the (min, max) interval. .. attribute:: levels - levels matrix [4] (min, max) + Levels matrix [4] (min, max). + + :type: sequence of four sequences of two ints + :default: ((0, 255), (0, 255), (0, 255), (0, 255)) .. attribute:: previous - previous pixel filter + Previous pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` -.. class:: FilterNormal() +.. class:: FilterNormal - Filter for Blue Screen objects + Normal map filter. .. attribute:: colorIdx - index of color used to calculate normal (0 - red, 1 - green, 2 - blue) + Index of color used to calculate normal (0 - red, 1 - green, 2 - blue, 3 - alpha). + + :type: int in [0, 3] + :default: 0 .. attribute:: depth - depth of relief + Depth of relief. + + :type: float + :default: 4.0 .. attribute:: previous - previous pixel filter - -.. class:: FilterRGB24() + Previous pixel filter. + + :type: one of... + + * :class:`FilterBGR24` + * :class:`FilterBlueScreen` + * :class:`FilterColor` + * :class:`FilterGray` + * :class:`FilterLevel` + * :class:`FilterNormal` + * :class:`FilterRGB24` + * :class:`FilterRGBA32` + +.. class:: FilterRGB24 Returns a new input filter object to be used with :class:`ImageBuff` object when the image passed - to the ImageBuff.load() function has the 3-bytes pixel format BGR. - -.. class:: FilterRGBA32() + to the :meth:`ImageBuff.load` function has the 3-bytes pixel format BGR. - Source filter RGBA32 objects +.. class:: FilterRGBA32 -.. function:: getLastError() - - Last error that occurred in a bge.texture function. + Source filter RGBA32. - :return: the description of the last error occurred in a bge.texture function. - :rtype: string -.. function:: imageToArray(image,mode) +********* +Functions +********* - Returns a :class:`~bgl.buffer` corresponding to the current image stored in a texture source object. - - :arg image: Image source object. - :type image: object of type :class:`VideoFFmpeg`, :class:`ImageFFmpeg`, :class:`ImageBuff`, :class:`ImageMix`, :class:`ImageRender`, :class:`ImageMirror` or :class:`ImageViewport` - :arg mode: optional argument representing the pixel format. - You can use the characters R, G, B for the 3 color channels, A for the alpha channel, - 0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel. - Example: "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. - "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255. - A special mode "F" allows to return the image as an array of float. This mode should only be used to retrieve - the depth buffer of the ImageViewport and ImageRender object. - The default mode is "RGBA". - +.. function:: getLastError() - :type mode: string - :rtype: :class:`~bgl.buffer` - :return: A object representing the image as one dimensional array of bytes of size (pixel_size*width*height), - line by line starting from the bottom of the image. The pixel size and format is determined by the mode - parameter. For mode 'F', the array is a one dimensional array of float of size (width*height). + Last error that occurred in a bge.texture function. -.. function:: materialID(object,name) + :return: The description of the last error occurred in a bge.texture function. + :rtype: str + +.. function:: imageToArray(image, mode) + + Returns a :class:`~bgl.Buffer` corresponding to the current image stored in a texture source object. + + :arg image: Image source object of type ... + + * :class:`VideoFFmpeg` + * :class:`ImageFFmpeg` + * :class:`ImageBuff` + * :class:`ImageMirror` + * :class:`ImageMix` + * :class:`ImageRender` + * :class:`ImageViewport` + + :arg mode: Optional argument representing the pixel format. + + * You can use the characters R, G, B for the 3 color channels, A for the alpha channel, + 0 to force a fixed 0 color channel and 1 to force a fixed 255 color channel. + + Examples: + * "BGR" will return 3 bytes per pixel with the Blue, Green and Red channels in that order. + * "RGB1" will return 4 bytes per pixel with the Red, Green, Blue channels in that order and the alpha channel forced to 255. + + * A special mode "F" allows to return the image as an array of float. This mode should only be used to retrieve + the depth buffer of the class:`ImageViewport` and :class:`ImageRender` objects. + The default mode is "RGBA". + + :type mode: str + + :return: An object representing the image as one dimensional array of bytes of size (pixel_size*width*height), + line by line starting from the bottom of the image. The pixel size and format is determined by the mode + parameter. For mode 'F', the array is a one dimensional array of float of size (width*height). + :rtype: :class:`~bgl.Buffer` + +.. function:: materialID(object, name) Returns a numeric value that can be used in :class:`Texture` to create a dynamic texture. The value corresponds to an internal material number that uses the texture identified - by name. name is a string representing a texture name with IM prefix if you want to - identify the texture directly. This method works for basic tex face and for material, + by name. name is a string representing a texture name with ``IM`` prefix if you want to + identify the texture directly. This method works for basic tex face and for material, provided the material has a texture channel using that particular texture in first - position of the texture stack. name can also have MA prefix if you want to identify + position of the texture stack. name can also have ``MA`` prefix if you want to identify the texture by material. In that case the material must have a texture channel in first position. If the object has no material that matches name, it generates a runtime error. Use try/except to catch the exception. - Ex: bge.texture.materialID(obj, 'IMvideo.png') + Ex: ``bge.texture.materialID(obj, 'IMvideo.png')`` - :arg object: the game object that uses the texture you want to make dynamic - :type object: game object - :arg name: name of the texture/material you want to make dynamic. - :type name: string - :rtype: integer + :arg object: The game object that uses the texture you want to make dynamic. + :type object: :class:`~bge.types.KX_GameObject` + :arg name: Name of the texture/material you want to make dynamic. + :type name: str + + :return: The internal material number. + :rtype: int .. function:: setLogFile(filename) @@ -575,6 +1035,88 @@ When the texture object is deleted, the new texture is deleted and the old textu of the messages on the Python console. Only the runtime errors specific to the VideoTexture module are written in that file, ordinary runtime time errors are not written. - :arg filename: name of error log file - :type filename: string - :rtype: integer + :arg filename: Name of the error log file. + :type filename: str + + :return: -1 if the parameter name is invalid (not of type string), else 0. + :rtype: int + + +********* +Constants +********* + +FFmpeg Video and Image Status ++++++++++++++++++++++++++++++ + + +.. data:: SOURCE_ERROR + +.. data:: SOURCE_EMPTY + +.. data:: SOURCE_READY + +.. data:: SOURCE_PLAYING + +.. data:: SOURCE_STOPPED + + +Image Blending Modes +++++++++++++++++++++ + +See Wikipedia's `Blend Modes <https://en.wikipedia.org/wiki/Blend_modes>`_ for reference. + +.. data:: IMB_BLEND_MIX + +.. data:: IMB_BLEND_ADD + +.. data:: IMB_BLEND_SUB + +.. data:: IMB_BLEND_MUL + +.. data:: IMB_BLEND_LIGHTEN + +.. data:: IMB_BLEND_DARKEN + +.. data:: IMB_BLEND_ERASE_ALPHA + +.. data:: IMB_BLEND_ADD_ALPHA + +.. data:: IMB_BLEND_OVERLAY + +.. data:: IMB_BLEND_HARDLIGHT + +.. data:: IMB_BLEND_COLORBURN + +.. data:: IMB_BLEND_LINEARBURN + +.. data:: IMB_BLEND_COLORDODGE + +.. data:: IMB_BLEND_SCREEN + +.. data:: IMB_BLEND_SOFTLIGHT + +.. data:: IMB_BLEND_PINLIGHT + +.. data:: IMB_BLEND_VIVIDLIGHT + +.. data:: IMB_BLEND_LINEARLIGHT + +.. data:: IMB_BLEND_DIFFERENCE + +.. data:: IMB_BLEND_EXCLUSION + +.. data:: IMB_BLEND_HUE + +.. data:: IMB_BLEND_SATURATION + +.. data:: IMB_BLEND_LUMINOSITY + +.. data:: IMB_BLEND_COLOR + +.. data:: IMB_BLEND_COPY + +.. data:: IMB_BLEND_COPY_RGB + +.. data:: IMB_BLEND_COPY_ALPHA + 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..17f54031ec3 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` @@ -34,39 +89,83 @@ base class --- :class:`PyObjectPlus` :return: the material's shader :rtype: :class:`BL_Shader` + .. attribute:: alpha + + The material's alpha transparency. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: hardness + + How hard (sharp) the material's specular reflection is. + + :type: integer between 1 and 511 inclusive + + .. attribute:: emit + + Amount of light to emit. + + :type: float between 0.0 and 2.0 inclusive + + .. attribute:: specularIntensity + + How intense (bright) the material's specular reflection is. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: diffuseIntensity + + The material's amount of diffuse reflection. + + :type: float between 0.0 and 1.0 inclusive + + .. attribute:: specularColor + + The material's specular color. + + :type: :class:`mathutils.Color` + + .. attribute:: diffuseColor + + The material's diffuse color. + + :type: :class:`mathutils.Color` + .. method:: setBlending(src, dest) 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_Camera.rst b/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst index 0baba5c3359..ac5ab4b5fe5 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_Camera.rst @@ -51,6 +51,18 @@ base class --- :class:`KX_GameObject` :type: float + .. attribute:: shift_x + + The camera's horizontal shift. + + :type: float + + .. attribute:: shift_y + + The camera's vertical shift. + + :type: float + .. attribute:: perspective True if this camera has a perspective transform, False for an orthographic projection. diff --git a/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst index 4d9dd5b5c34..e326892a824 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_CharacterWrapper.rst @@ -37,7 +37,7 @@ base class --- :class:`PyObjectPlus` The speed and direction the character is traveling in using world coordinates. This should be used instead of applyMovement() to properly move the character. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. method:: jump() 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..d9f03395c34 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 @@ -133,9 +134,10 @@ base class --- :class:`PyObjectPlus` :type: integer - * 1 = POINTTOPOINT_CONSTRAINT - * 2 = LINEHINGE_CONSTRAINT - * 3 = ANGULAR_CONSTRAINT (aka LINEHINGE_CONSTRAINT) - * 4 = CONETWIST_CONSTRAINT - * 11 = VEHICLE_CONSTRAINT - * 12 = GENERIC_6DOF_CONSTRAINT + - :class:`~bge.constraints.POINTTOPOINT_CONSTRAINT` + - :class:`~bge.constraints.LINEHINGE_CONSTRAINT` + - :class:`~bge.constraints.ANGULAR_CONSTRAINT` + - :class:`~bge.constraints.CONETWIST_CONSTRAINT` + - :class:`~bge.constraints.VEHICLE_CONSTRAINT` + - :class:`~bge.constraints.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 a6d03dee1a1..74df50ddb58 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,35 @@ 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. + + :type: float between 0 and 1 inclusive. + + .. note:: + + The object must have a physics controller for the linear damping to be applied, otherwise the value will be returned as 0.0. + + .. attribute:: angularDamping + + The object's angular damping, also known as rotationation damping. Can be set simultaneously with linear damping using the :py:meth:`setDamping` method. + + :type: float between 0 and 1 inclusive. + + .. note:: + + The object must have a physics controller for the angular damping to be applied, otherwise the value will be returned as 0.0. + + .. attribute:: linVelocityMin Enforces the object keeps moving at a minimum velocity. @@ -108,13 +137,36 @@ base class --- :class:`SCA_IObject` .. note:: - A value of 0.0 disables this option (rather then setting it stationary). + A value of 0.0 disables this option (rather than 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. - :type: list [ix, iy, iz] + :type: Vector((ix, iy, iz)) .. attribute:: parent @@ -124,21 +176,70 @@ base class --- :class:`SCA_IObject` .. attribute:: groupMembers - Returns the list of group members if the object is a group object, otherwise None is returned. + Returns the list of group members if the object is a group object (dupli group instance), otherwise None is returned. :type: :class:`CListValue` of :class:`KX_GameObject` or None .. attribute:: groupObject - Returns the group object that the object belongs to or None if the object is not part of a group. + Returns the group object (dupli group instance) that the object belongs to or None if the object is not part of a group. :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 callables to be run when a collision occurs. + A list of functions to be called when a collision occurs. - :type: list + :type: list of functions and/or methods + + Callbacks should either accept one argument `(object)`, or three + arguments `(object, point, normal)`. For simplicity, per + colliding object only the first collision point is reported. + + .. code-block:: python + + # Function form + def callback_three(object, point, normal): + print('Hit by %r at %s with normal %s' % (object.name, point, normal)) + + def callback_one(object): + print('Hit by %r' % object.name) + + def register_callback(controller): + controller.owner.collisionCallbacks.append(callback_three) + controller.owner.collisionCallbacks.append(callback_one) + + + # Method form + class YourGameEntity(bge.types.KX_GameObject): + def __init__(self, old_owner): + self.collisionCallbacks.append(self.on_collision_three) + self.collisionCallbacks.append(self.on_collision_one) + + def on_collision_three(self, object, point, normal): + print('Hit by %r at %s with normal %s' % (object.name, point, normal)) + + def on_collision_one(self, object): + print('Hit by %r' % object.name) + + .. note:: + For backward compatibility, a callback with variable number of + arguments (using `*args`) will be passed only the `object` + argument. Only when there is more than one fixed argument (not + counting `self` for methods) will the three-argument form be + used. .. attribute:: scene @@ -374,6 +475,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() @@ -496,7 +603,7 @@ base class --- :class:`SCA_IObject` * True: you get the "local" velocity ie: relative to object orientation. :type local: boolean :return: the object's linear velocity. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: setLinearVelocity(velocity, local=False) @@ -523,7 +630,7 @@ base class --- :class:`SCA_IObject` * True: you get the "local" velocity ie: relative to object orientation. :type local: boolean :return: the object's angular velocity. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: setAngularVelocity(velocity, local=False) @@ -547,7 +654,7 @@ base class --- :class:`SCA_IObject` :arg point: optional point to return the velocity for, in local coordinates. :type point: 3D Vector :return: the velocity at the specified point. - :rtype: list [vx, vy, vz] + :rtype: Vector((vx, vy, vz)) .. method:: getReactionForce() @@ -557,7 +664,7 @@ base class --- :class:`SCA_IObject` This also includes impulses, eg from collisions. :return: the reaction force of this object. - :rtype: list [fx, fy, fz] + :rtype: Vector((fx, fy, fz)) .. note:: @@ -580,13 +687,28 @@ base class --- :class:`SCA_IObject` * True: you get the "local" impulse ie: relative to local coordinates with object orientation. :type local: boolean - .. method:: suspendDynamics() + .. method:: setDamping(linear_damping, angular_damping) + + Sets both the :py:attr:`linearDamping` and :py:attr:`angularDamping` simultaneously. This is more efficient than setting both properties individually. + + :arg linear_damping: Linear ("translational") damping factor. + :type linear_damping: float ∈ [0, 1] + :arg angular_damping: Angular ("rotational") damping factor. + :type angular_damping: float ∈ [0, 1] + + .. 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:: @@ -850,6 +972,16 @@ base class --- :class:`SCA_IObject` :return: The current frame of the action :rtype: float + .. method:: getActionName(layer=0) + + Gets the name of the current action playing in the supplied layer. + + :arg layer: The layer that you want to get the action name from. + :type layer: integer + + :return: The name of the current action + :rtype: string + .. method:: setActionFrame(frame, layer=0) Set the current frame of the action playing in the supplied layer. @@ -876,4 +1008,4 @@ base class --- :class:`SCA_IObject` :arg name: name of the property that added to the debug list. :type name: string :arg debug: the debug state. - :type debug: boolean
\ No newline at end of file + :type debug: boolean diff --git a/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst index 9ef8d6b2026..13fb3263a59 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_MeshProxy.rst @@ -51,7 +51,7 @@ base class --- :class:`SCA_IObject` .. attribute:: materials - :type: list of :class:`KX_BlenderMaterial` or :class:`KX_PolygonMaterial` types + :type: list of :class:`KX_BlenderMaterial` type .. attribute:: numPolygons diff --git a/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst b/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst index f10f101a4cc..347b000be3d 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_ObjectActuator.rst @@ -15,7 +15,7 @@ base class --- :class:`SCA_IActuator` The force applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalForce @@ -27,7 +27,7 @@ base class --- :class:`SCA_IActuator` The torque applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalTorque @@ -39,7 +39,7 @@ base class --- :class:`SCA_IActuator` The displacement vector applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalDLoc @@ -51,7 +51,7 @@ base class --- :class:`SCA_IActuator` The angular displacement vector applied by the actuator - :type: list [x, y, z] + :type: Vector((x, y, z)) .. note:: @@ -67,7 +67,7 @@ base class --- :class:`SCA_IActuator` The linear velocity applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalLinV @@ -83,7 +83,7 @@ base class --- :class:`SCA_IActuator` The angular velocity applied by the actuator. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: useLocalAngV diff --git a/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst index 534f6deedc0..f43cf62eec1 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_PolyProxy.rst @@ -23,7 +23,7 @@ base class --- :class:`SCA_IObject` The material of the polygon. - :type: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial` + :type: :class:`KX_BlenderMaterial` .. attribute:: texture_name @@ -84,7 +84,7 @@ base class --- :class:`SCA_IObject` .. method:: getMaterial() :return: The polygon material - :rtype: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial` + :rtype: :class:`KX_BlenderMaterial` .. method:: getTextureName() 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 f2dad58731c..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: list [fx, fy, fz] + :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_VehicleWrapper.rst b/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst index 9340d33f8a9..631075363ca 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_VehicleWrapper.rst @@ -11,22 +11,25 @@ base class --- :class:`PyObjectPlus` TODO - description - .. method:: addWheel(wheel, attachPos, attachDir, axleDir, suspensionRestLength, wheelRadius, hasSteering) + .. method:: addWheel(wheel, attachPos, downDir, axleDir, suspensionRestLength, wheelRadius, hasSteering) Add a wheel to the vehicle :arg wheel: The object to use as a wheel. - :type wheel: :class:`KX_GameObject` or a KX_GameObject name - :arg attachPos: The position that this wheel will attach to. + :type wheel: :class:`KX_GameObject` or a :class:`KX_GameObject` name + :arg attachPos: The position to attach the wheel, relative to the chassis object center. :type attachPos: vector of 3 floats - :arg attachDir: The direction this wheel points. - :type attachDir: vector of 3 floats - :arg axleDir: The direction of this wheels axle. + :arg downDir: The direction vector pointing down to where the vehicle should collide with the floor. + :type downDir: vector of 3 floats + :arg axleDir: The axis the wheel rotates around, relative to the chassis. :type axleDir: vector of 3 floats - :arg suspensionRestLength: TODO - Description + :arg suspensionRestLength: The length of the suspension when no forces are being applied. :type suspensionRestLength: float - :arg wheelRadius: The size of the wheel. + :arg wheelRadius: The radius of the wheel (half the diameter). :type wheelRadius: float + :arg hasSteering: True if the wheel should turn with steering, typically used in front wheels. + :type hasSteering: boolean + .. method:: applyBraking(force, wheelIndex) @@ -38,6 +41,7 @@ base class --- :class:`PyObjectPlus` :arg wheelIndex: index of the wheel where the force needs to be applied :type wheelIndex: integer + .. method:: applyEngineForce(force, wheelIndex) Apply an engine force to the specified wheel @@ -48,6 +52,7 @@ base class --- :class:`PyObjectPlus` :arg wheelIndex: index of the wheel where the force needs to be applied :type wheelIndex: integer + .. method:: getConstraintId() Get the constraint ID diff --git a/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst b/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst index 9c0d1169d49..73d692770d6 100644 --- a/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst +++ b/doc/python_api/rst/bge_types/bge.types.KX_VertexProxy.rst @@ -17,25 +17,25 @@ base class --- :class:`SCA_IObject` The position of the vertex. - :type: list [x, y, z] + :type: Vector((x, y, z)) .. attribute:: UV The texture coordinates of the vertex. - :type: list [u, v] + :type: Vector((u, v)) .. attribute:: normal The normal of the vertex. - :type: list [nx, ny, nz] + :type: Vector((nx, ny, nz)) .. attribute:: color The color of the vertex. - :type: list [r, g, b, a] + :type: Vector((r, g, b, a)) Black = [0.0, 0.0, 0.0, 1.0], White = [1.0, 1.0, 1.0, 1.0] @@ -110,13 +110,13 @@ base class --- :class:`SCA_IObject` Gets the position of this vertex. :return: this vertexes position in local coordinates. - :rtype: list [x, y, z] + :rtype: Vector((x, y, z)) .. method:: setXYZ(pos) Sets the position of this vertex. - :type: list [x, y, z] + :type: Vector((x, y, z)) :arg pos: the new position for this vertex in local coordinates. @@ -125,26 +125,26 @@ base class --- :class:`SCA_IObject` Gets the UV (texture) coordinates of this vertex. :return: this vertexes UV (texture) coordinates. - :rtype: list [u, v] + :rtype: Vector((u, v)) .. method:: setUV(uv) Sets the UV (texture) coordinates of this vertex. - :type: list [u, v] + :type: Vector((u, v)) .. method:: getUV2() Gets the 2nd UV (texture) coordinates of this vertex. :return: this vertexes UV (texture) coordinates. - :rtype: list [u, v] + :rtype: Vector((u, v)) .. method:: setUV2(uv, unit) Sets the 2nd UV (texture) coordinates of this vertex. - :type: list [u, v] + :type: Vector((u, v)) :arg unit: optional argument, FLAT==1, SECOND_UV==2, defaults to SECOND_UV :arg unit: integer @@ -197,7 +197,7 @@ base class --- :class:`SCA_IObject` Gets the normal vector of this vertex. :return: normalized normal vector. - :rtype: list [nx, ny, nz] + :rtype: Vector((nx, ny, nz)) .. method:: setNormal(normal) 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..a636af4f083 --- /dev/null +++ b/doc/python_api/rst/bge_types/bge.types.KX_WorldInfo.rst @@ -0,0 +1,79 @@ +KX_WorldInfo(PyObjectPlus) +============================= + +.. module:: bge.types + +base class --- :class:`PyObjectPlus` + +.. class:: KX_WorldInfo(PyObjectPlus) + + A world 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 diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst b/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst index b1c6e5d1487..5dfa78d3942 100644 --- a/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst +++ b/doc/python_api/rst/bge_types/bge.types.SCA_PythonMouse.rst @@ -25,7 +25,7 @@ base class --- :class:`PyObjectPlus` The normalized x and y position of the mouse cursor. - :type: list [x, y] + :type: tuple (x, y) .. attribute:: visible diff --git a/doc/python_api/rst/bgl.rst b/doc/python_api/rst/bgl.rst index dfdb4a17998..8b0ad63abb4 100644 --- a/doc/python_api/rst/bgl.rst +++ b/doc/python_api/rst/bgl.rst @@ -8,26 +8,28 @@ This module wraps OpenGL constants and functions, making them available from within Blender Python. The complete list can be retrieved from the module itself, by listing its -contents: dir(bgl). A simple search on the net can point to more +contents: dir(bgl). A simple search on the web can point to more than enough material to teach OpenGL programming, from books to many collections of tutorials. -The "red book": "I{OpenGL Programming Guide: The Official Guide to Learning -OpenGL}" and the online NeHe tutorials are two of the best resources. +Here is a comprehensive `list of books <http://www.opengl.org/documentation/books/>`__ (non free). +The `arcsynthesis tutorials <http://www.arcsynthesis.org/gltut/>`__ +is one of the best resources to learn modern OpenGL and +`g-truc <http://www.g-truc.net/post-tech-content-sample.html>`__ +offers a set of extensive examples, including advanced features. + .. note:: You can use the :class:`Image` type to load and set textures. See :class:`Image.gl_load` and :class:`Image.gl_load`, for example. - `OpenGL.org <http://www.opengl.org>`_ - `NeHe GameDev <http://nehe.gamedev.net>`_ .. function:: glAccum(op, value): Operate on the accumulation buffer. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAccum.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAccum.xml>`__ :type op: Enumerated constant :arg op: The accumulation buffer operation. @@ -39,7 +41,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the alpha test function. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAlphaFunc.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAlphaFunc.xml>`__ :type func: Enumerated constant :arg func: Specifies the alpha comparison function. @@ -52,7 +54,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Determine if textures are loaded in texture memory - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAreTexturesResident.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAreTexturesResident.xml>`__ :type n: int :arg n: Specifies the number of textures to be queried. @@ -68,7 +70,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Delimit the vertices of a primitive or a group of like primatives - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBegin.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBegin.xml>`__ :type mode: Enumerated constant :arg mode: Specifies the primitive that will be create from vertices between @@ -79,7 +81,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Bind a named texture to a texturing target - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBindTexture.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBindTexture.xml>`__ :type target: Enumerated constant :arg target: Specifies the target to which the texture is bound. @@ -91,7 +93,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Draw a bitmap - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBitmap.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBitmap.xml>`__ :type width, height: int :arg width, height: Specify the pixel width and height of the bitmap image. @@ -109,7 +111,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify pixel arithmetic - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBlendFunc.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBlendFunc.xml>`__ :type sfactor: Enumerated constant :arg sfactor: Specifies how the red, green, blue, and alpha source blending factors are @@ -123,7 +125,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Execute a display list - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCallList.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCallList.xml>`__ :type list: unsigned int :arg list: Specifies the integer name of the display list to be executed. @@ -133,7 +135,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Execute a list of display lists - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCallLists.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCallLists.xml>`__ :type n: int :arg n: Specifies the number of display lists to be executed. @@ -149,7 +151,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Clear buffers to preset values - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClear.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClear.xml>`__ :type mask: Enumerated constant(s) :arg mask: Bitwise OR of masks that indicate the buffers to be cleared. @@ -159,7 +161,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify clear values for the accumulation buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearAccum.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearAccum.xml>`__ :type red, green, blue, alpha: float :arg red, green, blue, alpha: Specify the red, green, blue, and alpha values used when the @@ -170,7 +172,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify clear values for the color buffers - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearColor.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearColor.xml>`__ :type red, green, blue, alpha: float :arg red, green, blue, alpha: Specify the red, green, blue, and alpha values used when the @@ -181,7 +183,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the clear value for the depth buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearDepth.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearDepth.xml>`__ :type depth: int :arg depth: Specifies the depth value used when the depth buffer is cleared. @@ -192,7 +194,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the clear value for the color index buffers - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearIndex.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearIndex.xml>`__ :type c: float :arg c: Specifies the index used when the color index buffers are cleared. @@ -203,7 +205,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the clear value for the stencil buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearStencil.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClearStencil.xml>`__ :type s: int :arg s: Specifies the index used when the stencil buffer is cleared. The initial value is 0. @@ -213,7 +215,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify a plane against which all geometry is clipped - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClipPlane.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glClipPlane.xml>`__ :type plane: Enumerated constant :arg plane: Specifies which clipping plane is being positioned. @@ -232,7 +234,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set a new color. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColor.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColor.xml>`__ :type red, green, blue, alpha: Depends on function prototype. :arg red, green, blue: Specify new red, green, and blue values for the current color. @@ -244,7 +246,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Enable and disable writing of frame buffer color components - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColorMask.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColorMask.xml>`__ :type red, green, blue, alpha: int (boolean) :arg red, green, blue, alpha: Specify whether red, green, blue, and alpha can or cannot be @@ -256,7 +258,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Cause a material color to track the current color - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColorMaterial.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glColorMaterial.xml>`__ :type face: Enumerated constant :arg face: Specifies whether front, back, or both front and back material parameters should @@ -269,7 +271,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Copy pixels in the frame buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCopyPixels.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCopyPixels.xml>`__ :type x, y: int :arg x, y: Specify the window coordinates of the lower left corner of the rectangular @@ -285,7 +287,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Copy pixels into a 2D texture image - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCopyTexImage2D.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCopyTexImage2D.xml>`__ :type target: Enumerated constant :arg target: Specifies the target texture. @@ -314,7 +316,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify whether front- or back-facing facets can be culled - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCullFace.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCullFace.xml>`__ :type mode: Enumerated constant :arg mode: Specifies whether front- or back-facing facets are candidates for culling. @@ -324,7 +326,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Delete a contiguous group of display lists - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteLists.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteLists.xml>`__ :type list: unsigned int :arg list: Specifies the integer name of the first display list to delete @@ -336,7 +338,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Delete named textures - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteTextures.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteTextures.xml>`__ :type n: int :arg n: Specifies the number of textures to be deleted @@ -348,7 +350,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the value used for depth buffer comparisons - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthFunc.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthFunc.xml>`__ :type func: Enumerated constant :arg func: Specifies the depth comparison function. @@ -358,7 +360,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Enable or disable writing into the depth buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthMask.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthMask.xml>`__ :type flag: int (boolean) :arg flag: Specifies whether the depth buffer is enabled for writing. If flag is GL_FALSE, @@ -370,7 +372,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify mapping of depth values from normalized device coordinates to window coordinates - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthRange.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDepthRange.xml>`__ :type zNear: int :arg zNear: Specifies the mapping of the near clipping plane to window coordinates. @@ -384,7 +386,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Disable server-side GL capabilities - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEnable.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEnable.xml>`__ :type cap: Enumerated constant :arg cap: Specifies a symbolic constant indicating a GL capability. @@ -394,7 +396,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify which color buffers are to be drawn into - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDrawBuffer.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDrawBuffer.xml>`__ :type mode: Enumerated constant :arg mode: Specifies up to four color buffers to be drawn into. @@ -404,7 +406,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Write a block of pixels to the frame buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDrawPixels.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDrawPixels.xml>`__ :type width, height: int :arg width, height: Specify the dimensions of the pixel rectangle to be @@ -423,7 +425,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Flag edges as either boundary or non-boundary - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEdgeFlag.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEdgeFlag.xml>`__ :type flag: Depends of function prototype :arg flag: Specifies the current edge flag value.The initial value is GL_TRUE. @@ -433,7 +435,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Enable server-side GL capabilities - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEnable.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEnable.xml>`__ :type cap: Enumerated constant :arg cap: Specifies a symbolic constant indicating a GL capability. @@ -443,14 +445,14 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Delimit the vertices of a primitive or group of like primitives - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBegin.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glBegin.xml>`__ .. function:: glEndList(): Create or replace a display list - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNewList.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNewList.xml>`__ .. function:: glEvalCoord (u,v): @@ -460,7 +462,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Evaluate enabled one- and two-dimensional maps - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalCoord.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalCoord.xml>`__ :type u: Depends on function prototype. :arg u: Specifies a value that is the domain coordinate u to the basis function defined @@ -478,7 +480,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Compute a one- or two-dimensional grid of points or lines - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalMesh.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalMesh.xml>`__ :type mode: Enumerated constant :arg mode: In glEvalMesh1, specifies whether to compute a one-dimensional @@ -493,7 +495,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Generate and evaluate a single point in a mesh - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalPoint.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glEvalPoint.xml>`__ :type i: int :arg i: Specifies the integer value for grid domain variable i. @@ -505,7 +507,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Controls feedback mode - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFeedbackBuffer.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFeedbackBuffer.xml>`__ :type size: int :arg size: Specifies the maximum number of values that can be written into buffer. @@ -520,14 +522,14 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Block until all GL execution is complete - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFinish.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFinish.xml>`__ .. function:: glFlush(): Force Execution of GL commands in finite time - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFlush.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFlush.xml>`__ .. function:: glFog (pname, param): @@ -536,7 +538,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify fog parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFog.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFog.xml>`__ :type pname: Enumerated constant :arg pname: Specifies a single-valued fog parameter. If the function prototype @@ -551,7 +553,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Define front- and back-facing polygons - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFrontFace.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFrontFace.xml>`__ :type mode: Enumerated constant :arg mode: Specifies the orientation of front-facing polygons. @@ -561,7 +563,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix by a perspective matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glFrustum.xml>`__ :type left, right: double (float) :arg left, right: Specify the coordinates for the left and right vertical @@ -578,7 +580,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Generate a contiguous set of empty display lists - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGenLists.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGenLists.xml>`__ :type range: int :arg range: Specifies the number of contiguous empty display lists to be generated. @@ -588,7 +590,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Generate texture names - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGenTextures.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGenTextures.xml>`__ :type n: int :arg n: Specifies the number of textures name to be generated. @@ -602,7 +604,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return the value or values of a selected parameter - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGet.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGet.xml>`__ :type pname: Enumerated constant :arg pname: Specifies the parameter value to be returned. @@ -614,7 +616,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return the coefficients of the specified clipping plane - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetClipPlane.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetClipPlane.xml>`__ :type plane: Enumerated constant :arg plane: Specifies a clipping plane. The number of clipping planes depends on the @@ -629,7 +631,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return error information - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetError.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetError.xml>`__ .. function:: glGetLight (light, pname, params): @@ -638,7 +640,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return light source parameter values - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetLight.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetLight.xml>`__ :type light: Enumerated constant :arg light: Specifies a light source. The number of possible lights depends on the @@ -672,7 +674,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return material parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetMaterial.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetMaterial.xml>`__ :type face: Enumerated constant :arg face: Specifies which of the two materials is being queried. @@ -689,7 +691,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/man2/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 +703,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/man2/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. @@ -711,7 +713,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return a string describing the current GL connection - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetString.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetString.xml>`__ :type name: Enumerated constant :arg name: Specifies a symbolic constant. @@ -724,7 +726,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return texture environment parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexEnv.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexEnv.xml>`__ :type target: Enumerated constant :arg target: Specifies a texture environment. Must be GL_TEXTURE_ENV. @@ -740,7 +742,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return texture coordinate generation parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexGen.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexGen.xml>`__ :type coord: Enumerated constant :arg coord: Specifies a texture coordinate. @@ -754,7 +756,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return a texture image - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexImage.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexImage.xml>`__ :type target: Enumerated constant :arg target: Specifies which texture is to be obtained. @@ -776,7 +778,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. return texture parameter values for a specific level of detail - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexLevelParameter.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexLevelParameter.xml>`__ :type target: Enumerated constant :arg target: Specifies the symbolic name of the target texture. @@ -795,7 +797,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Return texture parameter values - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexParameter.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetTexParameter.xml>`__ :type target: Enumerated constant :arg target: Specifies the symbolic name of the target texture. @@ -809,7 +811,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify implementation-specific hints - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glHint.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glHint.xml>`__ :type target: Enumerated constant :arg target: Specifies a symbolic constant indicating the behavior to be @@ -824,7 +826,7 @@ 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/man2/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 @@ -835,7 +837,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Control the writing of individual bits in the color index buffers - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIndexMask.xml>`_ + .. 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 @@ -847,14 +849,14 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Initialize the name stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glInitNames.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glInitNames.xml>`__ .. function:: glIsEnabled(cap): Test whether a capability is enabled - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsEnabled.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsEnabled.xml>`__ :type cap: Enumerated constant :arg cap: Specifies a constant representing a GL capability. @@ -864,7 +866,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Determine if a name corresponds to a display-list - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsList.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsList.xml>`__ :type list: unsigned int :arg list: Specifies a potential display-list name. @@ -874,7 +876,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Determine if a name corresponds to a texture - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsTexture.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsTexture.xml>`__ :type texture: unsigned int :arg texture: Specifies a value that may be the name of a texture. @@ -886,7 +888,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the light source parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLight.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLight.xml>`__ :type light: Enumerated constant :arg light: Specifies a light. The number of lights depends on the implementation, @@ -906,7 +908,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the lighting model parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLightModel.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLightModel.xml>`__ :type pname: Enumerated constant :arg pname: Specifies a single-value light model parameter. @@ -919,7 +921,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the line stipple pattern - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLineStipple.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLineStipple.xml>`__ :type factor: int :arg factor: Specifies a multiplier for each bit in the line stipple pattern. @@ -936,7 +938,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the width of rasterized lines. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLineWidth.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLineWidth.xml>`__ :type width: float :arg width: Specifies the width of rasterized lines. The initial value is 1. @@ -946,7 +948,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the display-list base for glCallLists - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glListBase.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glListBase.xml>`__ :type base: unsigned int :arg base: Specifies an integer offset that will be added to glCallLists @@ -957,7 +959,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Replace the current matrix with the identity matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadIdentity.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadIdentity.xml>`__ .. function:: glLoadMatrix (m): @@ -966,7 +968,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Replace the current matrix with the specified matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadMatrix.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadMatrix.xml>`__ :type m: :class:`bgl.Buffer` object. Depends on function prototype. :arg m: Specifies a pointer to 16 consecutive values, which are used as the elements @@ -977,7 +979,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Load a name onto the name stack. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadName.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLoadName.xml>`__ :type name: unsigned int :arg name: Specifies a name that will replace the top value on the name stack. @@ -987,7 +989,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify a logical pixel operation for color index rendering - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLogicOp.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLogicOp.xml>`__ :type opcode: Enumerated constant :arg opcode: Specifies a symbolic constant that selects a logical operation. @@ -999,7 +1001,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Define a one-dimensional evaluator - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMap1.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMap1.xml>`__ :type target: Enumerated constant :arg target: Specifies the kind of values that are generated by the evaluator. @@ -1024,7 +1026,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Define a two-dimensional evaluator - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMap2.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMap2.xml>`__ :type target: Enumerated constant :arg target: Specifies the kind of values that are generated by the evaluator. @@ -1065,7 +1067,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Define a one- or two-dimensional mesh - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMapGrid.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMapGrid.xml>`__ :type un: int :arg un: Specifies the number of partitions in the grid range interval @@ -1084,7 +1086,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify material parameters for the lighting model. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMaterial.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMaterial.xml>`__ :type face: Enumerated constant :arg face: Specifies which face or faces are being updated. Must be one of: @@ -1101,7 +1103,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify which matrix is the current matrix. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMatrixMode.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMatrixMode.xml>`__ :type mode: Enumerated constant :arg mode: Specifies which matrix stack is the target for subsequent matrix operations. @@ -1113,7 +1115,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix with the specified matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMultMatrix.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glMultMatrix.xml>`__ :type m: :class:`bgl.Buffer` object. Depends on function prototype. :arg m: Points to 16 consecutive values that are used as the elements of a 4x4 column @@ -1124,7 +1126,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Create or replace a display list - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNewList.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNewList.xml>`__ :type list: unsigned int :arg list: Specifies the display list name @@ -1139,7 +1141,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the current normal vector - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNormal.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glNormal.xml>`__ :type nx, ny, nz: Depends on function prototype. (non - 'v' prototypes only) :arg nx, ny, nz: Specify the x, y, and z coordinates of the new current normal. @@ -1153,7 +1155,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix with an orthographic matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glOrtho.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glOrtho.xml>`__ :type left, right: double (float) :arg left, right: Specify the coordinates for the left and @@ -1170,7 +1172,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Place a marker in the feedback buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPassThrough.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPassThrough.xml>`__ :type token: float :arg token: Specifies a marker value to be placed in the feedback @@ -1183,7 +1185,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set up pixel transfer maps - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelMap.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelMap.xml>`__ :type map: Enumerated constant :arg map: Specifies a symbolic map name. @@ -1199,7 +1201,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set pixel storage modes - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelStore.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelStore.xml>`__ :type pname: Enumerated constant :arg pname: Specifies the symbolic name of the parameter to be set. @@ -1215,7 +1217,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set pixel transfer modes - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelTransfer.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelTransfer.xml>`__ :type pname: Enumerated constant :arg pname: Specifies the symbolic name of the pixel transfer parameter to be set. @@ -1227,7 +1229,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the pixel zoom factors - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelZoom.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPixelZoom.xml>`__ :type xfactor, yfactor: float :arg xfactor, yfactor: Specify the x and y zoom factors for pixel write operations. @@ -1237,7 +1239,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the diameter of rasterized points - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPointSize.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPointSize.xml>`__ :type size: float :arg size: Specifies the diameter of rasterized points. The initial value is 1. @@ -1247,7 +1249,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Select a polygon rasterization mode - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonMode.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonMode.xml>`__ :type face: Enumerated constant :arg face: Specifies the polygons that mode applies to. @@ -1262,7 +1264,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the scale and units used to calculate depth values - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonOffset.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonOffset.xml>`__ :type factor: float :arg factor: Specifies a scale factor that is used to create a variable depth @@ -1276,7 +1278,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the polygon stippling pattern - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonStipple.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPolygonStipple.xml>`__ :type mask: :class:`bgl.Buffer` object I{type GL_BYTE} :arg mask: Specifies a pointer to a 32x32 stipple pattern that will be unpacked @@ -1287,35 +1289,35 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Pop the server attribute stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopAttrib.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopAttrib.xml>`__ .. function:: glPopClientAttrib(): Pop the client attribute stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopClientAttrib.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopClientAttrib.xml>`__ .. function:: glPopMatrix(): Pop the current matrix stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopMatrix.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopMatrix.xml>`__ .. function:: glPopName(): Pop the name stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopName.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPopName.xml>`__ .. function:: glPrioritizeTextures(n, textures, priorities): Set texture residence priority - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPrioritizeTextures.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPrioritizeTextures.xml>`__ :type n: int :arg n: Specifies the number of textures to be prioritized. @@ -1331,7 +1333,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Push the server attribute stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushAttrib.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushAttrib.xml>`__ :type mask: Enumerated constant(s) :arg mask: Specifies a mask that indicates which attributes to save. @@ -1341,7 +1343,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Push the client attribute stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushClientAttrib.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushClientAttrib.xml>`__ :type mask: Enumerated constant(s) :arg mask: Specifies a mask that indicates which attributes to save. @@ -1351,14 +1353,14 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Push the current matrix stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushMatrix.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushMatrix.xml>`__ .. function:: glPushName(name): Push the name stack - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushName.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glPushName.xml>`__ :type name: unsigned int :arg name: Specifies a name that will be pushed onto the name stack. @@ -1374,7 +1376,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify the raster position for pixel operations - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRasterPos.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRasterPos.xml>`__ :type x, y, z, w: Depends on function prototype. (z and w for '3' and '4' prototypes only) :arg x, y, z, w: Specify the x,y,z, and w object coordinates (if present) for the @@ -1406,7 +1408,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Select a color buffer source for pixels. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glReadBuffer.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glReadBuffer.xml>`__ :type mode: Enumerated constant :arg mode: Specifies a color buffer. @@ -1416,7 +1418,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Read a block of pixels from the frame buffer - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glReadPixels.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glReadPixels.xml>`__ :type x, y: int :arg x, y: Specify the window coordinates of the first pixel that is read @@ -1439,7 +1441,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Draw a rectangle - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRect.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRect.xml>`__ :type x1, y1: Depends on function prototype. (for non 'v' prototypes only) :arg x1, y1: Specify one vertex of a rectangle @@ -1454,7 +1456,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set rasterization mode - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRenderMode.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRenderMode.xml>`__ :type mode: Enumerated constant :arg mode: Specifies the rasterization mode. @@ -1466,7 +1468,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix by a rotation matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRotate.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glRotate.xml>`__ :type angle: Depends on function prototype. :arg angle: Specifies the angle of rotation in degrees. @@ -1480,7 +1482,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix by a general scaling matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glScale.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glScale.xml>`__ :type x, y, z: Depends on function prototype. :arg x, y, z: Specify scale factors along the x, y, and z axes, respectively. @@ -1490,7 +1492,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Define the scissor box - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glScissor.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glScissor.xml>`__ :type x, y: int :arg x, y: Specify the lower left corner of the scissor box. Initially (0, 0). @@ -1504,7 +1506,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Establish a buffer for selection mode values - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glSelectBuffer.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glSelectBuffer.xml>`__ :type size: int :arg size: Specifies the size of buffer @@ -1516,7 +1518,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Select flat or smooth shading - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glShadeModel.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glShadeModel.xml>`__ :type mode: Enumerated constant :arg mode: Specifies a symbolic value representing a shading technique. @@ -1526,7 +1528,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set function and reference value for stencil testing - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilFuc.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilFuc.xml>`__ :type func: Enumerated constant :arg func: Specifies the test function. @@ -1543,7 +1545,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Control the writing of individual bits in the stencil planes - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilMask.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilMask.xml>`__ :type mask: unsigned int :arg mask: Specifies a bit mask to enable and disable writing of individual bits @@ -1554,7 +1556,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set stencil test actions - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilOp.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glStencilOp.xml>`__ :type fail: Enumerated constant :arg fail: Specifies the action to take when the stencil test fails. @@ -1582,7 +1584,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the current texture coordinates - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexCoord.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexCoord.xml>`__ :type s, t, r, q: Depends on function prototype. (r and q for '3' and '4' prototypes only) :arg s, t, r, q: Specify s, t, r, and q texture coordinates. Not all parameters are @@ -1598,7 +1600,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set texture environment parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexEnv.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexEnv.xml>`__ :type target: Enumerated constant :arg target: Specifies a texture environment. Must be GL_TEXTURE_ENV. @@ -1617,7 +1619,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Control the generation of texture coordinates - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexGen.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexGen.xml>`__ :type coord: Enumerated constant :arg coord: Specifies a texture coordinate. @@ -1635,7 +1637,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify a one-dimensional texture image - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexImage1D.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexImage1D.xml>`__ :type target: Enumerated constant :arg target: Specifies the target texture. @@ -1662,7 +1664,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify a two-dimensional texture image - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexImage2D.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexImage2D.xml>`__ :type target: Enumerated constant :arg target: Specifies the target texture. @@ -1695,7 +1697,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set texture parameters - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexParameter.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTexParameter.xml>`__ :type target: Enumerated constant :arg target: Specifies the target texture. @@ -1712,7 +1714,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Multiply the current matrix by a translation matrix - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTranslate.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glTranslate.xml>`__ :type x, y, z: Depends on function prototype. :arg x, y, z: Specify the x, y, and z coordinates of a translation vector. @@ -1727,7 +1729,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Specify a vertex - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glVertex.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glVertex.xml>`__ :type x, y, z, w: Depends on function prototype (z and w for '3' and '4' prototypes only) :arg x, y, z, w: Specify x, y, z, and w coordinates of a vertex. Not all parameters @@ -1743,7 +1745,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Set the viewport - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glViewport.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glViewport.xml>`__ :type x, y: int :arg x, y: Specify the lower left corner of the viewport rectangle, @@ -1851,7 +1853,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Installs a program object as part of current rendering state - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glUseProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/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. @@ -1861,7 +1863,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Validates a program object - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glValidateProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glValidateProgram.xml>`__ :type program: int :arg program: Specifies the handle of the program object to be validated. @@ -1871,7 +1873,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Links a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLinkProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glLinkProgram.xml>`__ :type program: int :arg program: Specifies the handle of the program object to be linked. @@ -1881,7 +1883,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Select active texture unit. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glActiveTexture.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glActiveTexture.xml>`__ :type texture: int :arg texture: Constant in ``GL_TEXTURE0`` 0 - 8 @@ -1891,7 +1893,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Attaches a shader object to a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAttachShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glAttachShader.xml>`__ :type program: int :arg program: Specifies the program object to which a shader object will be attached. @@ -1903,7 +1905,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Compiles a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCompileShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCompileShader.xml>`__ :type shader: int :arg shader: Specifies the shader object to be compiled. @@ -1913,7 +1915,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Creates a program object - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCreateProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCreateProgram.xml>`__ :rtype: int :return: The new program or zero if an error occurs. @@ -1923,7 +1925,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Creates a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCreateShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glCreateShader.xml>`__ :type shaderType: Specifies the type of shader to be created. Must be one of ``GL_VERTEX_SHADER``, @@ -1940,7 +1942,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Deletes a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteProgram.xml>`__ :type program: int :arg program: Specifies the program object to be deleted. @@ -1950,7 +1952,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Deletes a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDeleteShader.xml>`__ :type shader: int :arg shader: Specifies the shader object to be deleted. @@ -1960,7 +1962,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Detaches a shader object from a program object to which it is attached. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDetachShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glDetachShader.xml>`__ :type program: int :arg program: Specifies the program object from which to detach the shader object. @@ -1972,7 +1974,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Returns the handles of the shader objects attached to a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetAttachedShaders.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetAttachedShaders.xml>`__ :type program: int :arg program: Specifies the program object to be queried. @@ -1988,7 +1990,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Returns the information log for a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetProgramInfoLog.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetProgramInfoLog.xml>`__ :type program: int :arg program: Specifies the program object whose information log is to be queried. @@ -2004,7 +2006,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Returns the information log for a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetShaderInfoLog.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetShaderInfoLog.xml>`__ :type shader: int :arg shader: Specifies the shader object whose information log is to be queried. @@ -2020,7 +2022,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Returns a parameter from a program object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetProgram.xml>`__ :type program: int :arg program: Specifies the program object to be queried. @@ -2034,7 +2036,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Determines if a name corresponds to a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsShader.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsShader.xml>`__ :type shader: int :arg shader: Specifies a potential shader object. @@ -2044,7 +2046,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Determines if a name corresponds to a program object - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsProgram.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glIsProgram.xml>`__ :type program: int :arg program: Specifies a potential program object. @@ -2054,7 +2056,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Returns the source code string from a shader object - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetShaderSource.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glGetShaderSource.xml>`__ :type shader: int :arg shader: Specifies the shader object to be queried. @@ -2070,7 +2072,7 @@ OpenGL}" and the online NeHe tutorials are two of the best resources. Replaces the source code in a shader object. - .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man2/xhtml/glShaderSource.xml>`_ + .. seealso:: `OpenGL Docs <http://www.opengl.org/sdk/docs/man/html/glShaderSource.xhtml>`__ :type shader: int :arg shader: Specifies the handle of the shader object whose source code is to be replaced. diff --git a/doc/python_api/rst/gpu.rst b/doc/python_api/rst/gpu.rst index aaceb3ce32e..b56523c2206 100644 --- a/doc/python_api/rst/gpu.rst +++ b/doc/python_api/rst/gpu.rst @@ -16,24 +16,24 @@ and in the game engine. .. warning:: - The API provided by this module should be consider unstable. The data exposed by the API - are are closely related to Blender's internal GLSL code and may change if the GLSL code - is modified (e.g. new uniform type). + The API provided by this module is subject to change. + The data exposed by the API are are closely related to Blender's internal GLSL code + and may change if the GLSL code is modified (e.g. new uniform type). Constants ========= -GLSL data type +GLSL Data Type -------------- .. _data-type: Type of GLSL data. -For shader uniforms, the data type determines which glUniform function +For shader uniforms, the data type determines which ``glUniform`` function variant to use to send the uniform value to the GPU. -For vertex attributes, the data type determines which glVertexAttrib function +For vertex attributes, the data type determines which ``glVertexAttrib`` function variant to use to send the vertex attribute to the GPU. See export_shader_ @@ -42,53 +42,37 @@ See export_shader_ one integer - :value: 1 - .. data:: GPU_DATA_1F one float - :value: 2 - .. data:: GPU_DATA_2F two floats - :value: 3 - .. data:: GPU_DATA_3F three floats - :value: 4 - .. data:: GPU_DATA_4F four floats - :value: 5 - .. data:: GPU_DATA_9F matrix 3x3 in column-major order - :value: 6 - .. data:: GPU_DATA_16F matrix 4x4 in column-major order - :value: 7 - .. data:: GPU_DATA_4UB four unsigned byte - :value: 8 - -GLSL uniform type ------------------ +GLSL Uniform Types +------------------ .. _uniform-type: @@ -101,7 +85,7 @@ The calculation of some of the uniforms is based on matrices available in the sc .. _mat4_cam_to_world: .. _mat4_world_to_cam: - *mat4_cam_to_world* + ``mat4_cam_to_world`` Model matrix of the camera. OpenGL 4x4 matrix that converts camera local coordinates to world coordinates. In blender this is obtained from the 'matrix_world' attribute of the camera object. @@ -112,7 +96,7 @@ The calculation of some of the uniforms is based on matrices available in the sc .. _mat4_object_to_world: .. _mat4_world_to_object: - *mat4_object_to_world* + ``mat4_object_to_world`` Model matrix of the object that is being rendered. OpenGL 4x4 matric that converts object local coordinates to world coordinates. In blender this is obtained from the 'matrix_world' attribute of the object. @@ -122,7 +106,7 @@ The calculation of some of the uniforms is based on matrices available in the sc .. _mat4_lamp_to_world: .. _mat4_world_to_lamp: - *mat4_lamp_to_world* + ``mat4_lamp_to_world`` Model matrix of the lamp lighting the object. OpenGL 4x4 matrix that converts lamp local coordinates to world coordinates. In blender this is obtained from the 'matrix_world' attribute of the lamp object. @@ -130,151 +114,299 @@ The calculation of some of the uniforms is based on matrices available in the sc Some uniform will need the *mat4_world_to_lamp* matrix computed as the inverse of this matrix. + +.. note:: + + Any uniforms used for view projections or transformations (object, lamp matrices for eg), + can only be set once per frame. + + +GLSL Object Uniforms +^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + - Object transformations and color must be set before drawing the object. + - There is at most one uniform of these types per shader. + .. data:: GPU_DYNAMIC_OBJECT_VIEWMAT - The uniform is a 4x4 GL matrix that converts world coordinates to - camera coordinates (see mat4_world_to_cam_). Can be set once per frame. - There is at most one uniform of that type per shader. + A matrix that converts world coordinates to camera coordinates (see mat4_world_to_cam_). - :value: 1 + :type: matrix4x4 .. data:: GPU_DYNAMIC_OBJECT_MAT - The uniform is a 4x4 GL matrix that converts object coordinates - to world coordinates (see mat4_object_to_world_). Must be set before drawing the object. - There is at most one uniform of that type per shader. + A matrix that converts object coordinates to world coordinates (see mat4_object_to_world_). - :value: 2 + :type: matrix4x4 .. data:: GPU_DYNAMIC_OBJECT_VIEWIMAT The uniform is a 4x4 GL matrix that converts coordinates in camera space to world coordinates (see mat4_cam_to_world_). - Can be set once per frame. - There is at most one uniform of that type per shader. - :value: 3 + :type: matrix4x4 .. data:: GPU_DYNAMIC_OBJECT_IMAT The uniform is a 4x4 GL matrix that converts world coodinates to object coordinates (see mat4_world_to_object_). - Must be set before drawing the object. - There is at most one uniform of that type per shader. - :value: 4 + :type: matrix4x4 .. data:: GPU_DYNAMIC_OBJECT_COLOR - The uniform is a vector of 4 float representing a RGB color + alpha defined at object level. - Each values between 0.0 and 1.0. In blender it corresponds to the 'color' attribute of the object. - Must be set before drawing the object. - There is at most one uniform of that type per shader. + An RGB color + alpha defined at object level. + Each values between 0.0 and 1.0. - :value: 5 + See :class:`bpy.types.Object.color`. + + :type: float4 + +.. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE + + Multiplier for bump-map scaling. + + :type: float -.. data:: GPU_DYNAMIC_LAMP_DYNVEC - The uniform is a vector of 3 float representing the direction of light in camera space. - In Blender, this is computed by +GLSL Lamp Uniforms +^^^^^^^^^^^^^^^^^^ - mat4_world_to_cam_ * (-vec3_lamp_Z_axis) +.. note:: - as the lamp Z axis points to the opposite direction of light. - The norm of the vector should be unity. Can be set once per frame. There is one uniform of that type per lamp lighting the material. - :value: 6 +.. data:: GPU_DYNAMIC_LAMP_DYNVEC -.. data:: GPU_DYNAMIC_LAMP_DYNCO + Represents the direction of light in camera space. - The uniform is a vector of 3 float representing the position of the light in camera space. - Computed as + Computed as: + mat4_world_to_cam_ * (-vec3_lamp_Z_axis) - mat4_world_to_cam_ * vec3_lamp_pos + .. note:: + - The lamp Z axis points to the opposite direction of light. + - The norm of the vector should be unit length. - Can be set once per frame. - There is one uniform of that type per lamp lighting the material. + :type: float3 - :value: 7 +.. data:: GPU_DYNAMIC_LAMP_DYNCO -.. data:: GPU_DYNAMIC_LAMP_DYNIMAT + Represents the position of the light in camera space. - The uniform is a 4x4 GL matrix that converts vector in camera space to lamp space. - Computed as + Computed as: + mat4_world_to_cam_ * vec3_lamp_pos - mat4_world_to_lamp_ * mat4_cam_to_world_ + :type: float3 - Can be set once per frame. - There is one uniform of that type per lamp lighting the material. +.. data:: GPU_DYNAMIC_LAMP_DYNIMAT - :value: 8 + Matrix that converts vector in camera space to lamp space. + + Computed as: + mat4_world_to_lamp_ * mat4_cam_to_world_ + + :type: matrix4x4 .. data:: GPU_DYNAMIC_LAMP_DYNPERSMAT - The uniform is a 4x4 GL matrix that converts a vector in camera space to shadow buffer depth space. - Computed as + Matrix that converts a vector in camera space to shadow buffer depth space. - mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_. + Computed as: + mat4_perspective_to_depth_ * mat4_lamp_to_perspective_ * mat4_world_to_lamp_ * mat4_cam_to_world_. .. _mat4_perspective_to_depth: - *mat4_perspective_to_depth* is a fixed matrix defined as follow:: + ``mat4_perspective_to_depth`` is a fixed matrix defined as follow:: 0.5 0.0 0.0 0.5 0.0 0.5 0.0 0.5 0.0 0.0 0.5 0.5 0.0 0.0 0.0 1.0 - This uniform can be set once per frame. There is one uniform of that type per lamp casting shadow in the scene. + .. note:: - :value: 9 + - There is one uniform of that type per lamp casting shadow in the scene. + + :type: matrix4x4 .. data:: GPU_DYNAMIC_LAMP_DYNENERGY - The uniform is a single float representing the lamp energy. In blender it corresponds - to the 'energy' attribute of the lamp data block. - There is one uniform of that type per lamp lighting the material. + See :class:`bpy.types.Lamp.energy`. - :value: 10 + :type: float .. data:: GPU_DYNAMIC_LAMP_DYNCOL - The uniform is a vector of 3 float representing the lamp color. - Color elements are between 0.0 and 1.0. In blender it corresponds - to the 'color' attribute of the lamp data block. - There is one uniform of that type per lamp lighting the material. + See :class:`bpy.types.Lamp.color`. + + :type: float3 + +.. data:: GPU_DYNAMIC_LAMP_DISTANCE + + See :class:`bpy.types.Lamp.distance`. + + :type: float + +.. data:: GPU_DYNAMIC_LAMP_ATT1 + + See + :class:`bpy.types.PointLamp.linear_attenuation`, + :class:`bpy.types.SpotLamp.linear_attenuation`. + + :type: float + +.. data:: GPU_DYNAMIC_LAMP_ATT2 + + See + :class:`bpy.types.PointLamp.quadratic_attenuation`, + :class:`bpy.types.SpotLamp.quadratic_attenuation`. - :value: 11 + :type: float + +.. data:: GPU_DYNAMIC_LAMP_SPOTSIZE + + See :class:`bpy.types.SpotLamp.spot_size`. + + :type: float + +.. data:: GPU_DYNAMIC_LAMP_SPOTBLEND + + See :class:`bpy.types.SpotLamp.spot_blend`. + + :type: float + + +GLSL Sampler Uniforms +^^^^^^^^^^^^^^^^^^^^^ .. data:: GPU_DYNAMIC_SAMPLER_2DBUFFER - The uniform is an integer representing an internal texture used for certain effect + Represents an internal texture used for certain effect (color band, etc). - :value: 12 + :type: integer .. data:: GPU_DYNAMIC_SAMPLER_2DIMAGE - The uniform is an integer representing a texture loaded from an image file. + Represents a texture loaded from an image file. - :value: 13 + :type: integer .. data:: GPU_DYNAMIC_SAMPLER_2DSHADOW - The uniform is an float representing the bumpmap scaling. + Represents a texture loaded from a shadow buffer file. - :value: 14 + :type: integer -.. data:: GPU_DYNAMIC_OBJECT_AUTOBUMPSCALE - The uniform is an integer representing a shadow buffer corresponding to a lamp - casting shadow. +GLSL Mist Uniforms +^^^^^^^^^^^^^^^^^^ + +.. data:: GPU_DYNAMIC_MIST_ENABLE: + + See :class:`bpy.types.WorldMistSettings.use_mist`. + + :type: float (0 or 1) + +.. data:: GPU_DYNAMIC_MIST_START - :value: 15 + See :class:`bpy.types.WorldMistSettings.start`. + :type: float -GLSL attribute type + See :class:`bpy.types.WorldMistSettings.depth`. + +.. data:: GPU_DYNAMIC_MIST_DISTANCE + + :type: float + + See :class:`bpy.types.WorldMistSettings.intensity`. + +.. data:: GPU_DYNAMIC_MIST_INTENSITY + + :type: float + +.. data:: GPU_DYNAMIC_MIST_TYPE + + See :class:`bpy.types.WorldMistSettings.falloff`. + + :type: float (used as an index into the type) + +.. data:: GPU_DYNAMIC_MIST_COLOR + + +GLSL World Uniforms +^^^^^^^^^^^^^^^^^^^ + +.. data:: GPU_DYNAMIC_HORIZON_COLOR + + See :class:`bpy.types.World.horizon_color`. + + :type: float3 + +.. data:: GPU_DYNAMIC_AMBIENT_COLOR + + See :class:`bpy.types.World.ambient_color`. + + :type: float3 + + +GLSL Material Uniforms +^^^^^^^^^^^^^^^^^^^^^^ + +.. data:: GPU_DYNAMIC_MAT_DIFFRGB + + See :class:`bpy.types.Material.diffuse_color`. + + :type: float3 + +.. data:: GPU_DYNAMIC_MAT_REF + + See :class:`bpy.types.Material.diffuse_intensity`. + + :type: float + +.. data:: GPU_DYNAMIC_MAT_SPECRGB + + See :class:`bpy.types.Material.specular_color`. + + :type: float3 + +.. data:: GPU_DYNAMIC_MAT_SPEC + + See :class:`bpy.types.Material.specular_intensity`. + + :type: float + +.. data:: GPU_DYNAMIC_MAT_HARD + + See :class:`bpy.types.Material.specular_hardness`. + + :type: float + +.. data:: GPU_DYNAMIC_MAT_EMIT + + See :class:`bpy.types.Material.emit`. + + :type: float + +.. data:: GPU_DYNAMIC_MAT_AMB + + See :class:`bpy.types.Material.ambient`. + + :type: float + +.. data:: GPU_DYNAMIC_MAT_ALPHA + + See :class:`bpy.types.Material.alpha`. + + :type: float + + + +GLSL Attribute Type ------------------- .. _attribute-type: @@ -291,9 +423,7 @@ layer that contains the vertex attribute. .. code-block:: python - mesh.uv_textures[attribute["name"]] - - :value: 5 + mesh.uv_layers[attribute["name"]] .. data:: CD_MCOL @@ -306,8 +436,6 @@ layer that contains the vertex attribute. mesh.vertex_colors[attribute["name"]] - :value: 6 - .. data:: CD_ORCO Vertex attribute is original coordinates. Data type is vector 3 float. @@ -319,8 +447,6 @@ layer that contains the vertex attribute. mesh.vertices - :value: 14 - .. data:: CD_TANGENT Vertex attribute is the tangent vector. Data type is vector 4 float. @@ -330,8 +456,6 @@ layer that contains the vertex attribute. C function to compute the tangent layer from the other layers can be obtained from blender.org. - :value: 18 - Functions ========= @@ -341,8 +465,12 @@ Functions .. function:: export_shader(scene,material) Extracts the GLSL shader producing the visual effect of material in scene for the purpose of - reusing the shader in an external engine. This function is meant to be used in material exporter - so that the GLSL shader can be exported entirely. The return value is a dictionary containing the + reusing the shader in an external engine. + + This function is meant to be used in material exporter + so that the GLSL shader can be exported entirely. + + The return value is a dictionary containing the shader source code and all associated data. :arg scene: the scene in which the material in rendered. @@ -354,76 +482,91 @@ Functions The dictionary contains the following elements: - * ["fragment"] : string + - ``["fragment"]``: string fragment shader source code. - * ["vertex"] : string + - ``["vertex"]``: string vertex shader source code. - * ["uniforms"] : sequence + - ``["uniforms"]``: sequence list of uniforms used in fragment shader, can be empty list. Each element of the sequence is a dictionary with the following elements: - * ["varname"] : string + - ``["varname"]``: string name of the uniform in the fragment shader. Always of the form 'unf<number>'. - * ["datatype"] : integer + - ``["datatype"]``: integer data type of the uniform variable. Can be one of the following: - * :data:`gpu.GPU_DATA_1I` : use glUniform1i - * :data:`gpu.GPU_DATA_1F` : use glUniform1fv - * :data:`gpu.GPU_DATA_2F` : use glUniform2fv - * :data:`gpu.GPU_DATA_3F` : use glUniform3fv - * :data:`gpu.GPU_DATA_4F` : use glUniform4fv - * :data:`gpu.GPU_DATA_9F` : use glUniformMatrix3fv - * :data:`gpu.GPU_DATA_16F` : use glUniformMatrix4fv + .. hlist:: + :columns: 2 + + - :data:`gpu.GPU_DATA_1I` : use ``glUniform1i`` + - :data:`gpu.GPU_DATA_1F` : use ``glUniform1fv`` + - :data:`gpu.GPU_DATA_2F` : use ``glUniform2fv`` + - :data:`gpu.GPU_DATA_3F` : use ``glUniform3fv`` + - :data:`gpu.GPU_DATA_4F` : use ``glUniform4fv`` + - :data:`gpu.GPU_DATA_9F` : use ``glUniformMatrix3fv`` + - :data:`gpu.GPU_DATA_16F` : use ``glUniformMatrix4fv`` - * ["type"] : integer + - ``["type"]``: integer type of uniform, determines the origin and method of calculation. See uniform-type_. Depending on the type, more elements will be be present. - * ["lamp"] : :class:`bpy.types.Object` - Reference to the lamp object from which the uniforms value are extracted. Set for the following uniforms types: + - ``["lamp"]``: :class:`bpy.types.Object` + Reference to the lamp object from which the uniforms value are extracted. + Set for the following uniforms types: .. hlist:: - :columns: 3 + :columns: 2 - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC` - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO` - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` - * :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` - * :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` + - :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` + - :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW` Notes: - * The uniforms :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`, :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` - refer to the lamp object position and orientation, both of can be derived from the object world matrix: + - The uniforms + :data:`gpu.GPU_DYNAMIC_LAMP_DYNVEC`, + :data:`gpu.GPU_DYNAMIC_LAMP_DYNCO`, + :data:`gpu.GPU_DYNAMIC_LAMP_DYNIMAT` and + :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` + refer to the lamp object position and orientation, + both of can be derived from the object world matrix: .. code-block:: python obmat = uniform["lamp"].matrix_world where obmat is the mat4_lamp_to_world_ matrix of the lamp as a 2 dimensional array, - the lamp world location location is in obmat[3]. + the lamp world location location is in ``obmat[3]``. - * The uniform types :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` refer to the lamp data bloc that you get from: + - The uniform types + :data:`gpu.GPU_DYNAMIC_LAMP_DYNENERGY` and + :data:`gpu.GPU_DYNAMIC_LAMP_DYNCOL` + refer to the lamp data bloc that you get from: .. code-block:: python la = uniform["lamp"].data - from which you get la.energy and la.color + from which you get ``lamp.energy`` and ``lamp.color`` - * Lamp duplication is not supported: if you have duplicated lamps in your scene + - Lamp duplication is not supported: if you have duplicated lamps in your scene (i.e. lamp that are instantiated by dupligroup, etc), this element will only give you a reference to the orignal lamp and you will not know which instance of the lamp it is refering too. You can still handle that case in the exporter by distributing the uniforms amongst the duplicated lamps. - * ["image"] : :class:`bpy.types.Image` - Reference to the image databloc. Set for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. You can get the image data from: + - ``["image"]``: :class:`bpy.types.Image` + Reference to the image databloc. + Set for uniform type + :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE`. + You can get the image data from: .. code-block:: python @@ -432,60 +575,63 @@ Functions # image size as a 2-dimensional array of int uniform["image"].size - * ["texnumber"] : integer + - ``["texnumber"]``: integer Channel number to which the texture is bound when drawing the object. - Set for uniform types :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`. + Set for uniform types + :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`, + :data:`gpu.GPU_DYNAMIC_SAMPLER_2DIMAGE` and + :data:`gpu.GPU_DYNAMIC_SAMPLER_2DSHADOW`. This is provided for information only: when reusing the shader outside blencer, you are free to assign the textures to the channel of your choice and to pass that number channel to the GPU in the uniform. - * ["texpixels"] : byte array - texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. Although - the corresponding uniform is a 2D sampler, the texture is always a 1D texture - of n x 1 pixel. The texture size n is provided in ["texsize"] element. + - ``["texpixels"]``: byte array + texture data for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. + Although the corresponding uniform is a 2D sampler, + the texture is always a 1D texture of n x 1 pixel. + The texture size n is provided in ["texsize"] element. These texture are only used for computer generated texture (colorband, etc). - The texture data is provided so that you can make a real image out of it in the - exporter. + The texture data is provided so that you can make a real image out of it in the exporter. - * ["texsize"] : integer + - ``["texsize"]``: integer horizontal size of texture for uniform type :data:`gpu.GPU_DYNAMIC_SAMPLER_2DBUFFER`. The texture data is in ["texpixels"]. - * ["attributes"] : sequence + - ``["attributes"]``: sequence list of attributes used in vertex shader, can be empty. Blender doesn't use standard attributes except for vertex position and normal. All other vertex - attributes must be passed using the generic glVertexAttrib functions. + attributes must be passed using the generic ``glVertexAttrib`` functions. The attribute data can be found in the derived mesh custom data using RNA. Each element of the sequence is a dictionary containing the following elements: - * ["varname"] : string + - ``["varname"]``: string name of the uniform in the vertex shader. Always of the form 'att<number>'. - * ["datatype"] : integer + - ``["datatype"]``: integer data type of vertex attribute, can be one of the following: - * :data:`gpu.GPU_DATA_2F` : use glVertexAttrib2fv - * :data:`gpu.GPU_DATA_3F` : use glVertexAttrib3fv - * :data:`gpu.GPU_DATA_4F` : use glVertexAttrib4fv - * :data:`gpu.GPU_DATA_4UB` : use glVertexAttrib4ubv + - :data:`gpu.GPU_DATA_2F`: use ``glVertexAttrib2fv`` + - :data:`gpu.GPU_DATA_3F`: use ``glVertexAttrib3fv`` + - :data:`gpu.GPU_DATA_4F`: use ``glVertexAttrib4fv`` + - :data:`gpu.GPU_DATA_4UB`: use ``glVertexAttrib4ubv`` - * ["number"] : integer - generic attribute number. This is provided for information only. Blender - doesn't use glBindAttribLocation to place generic attributes at specific location, + - ``["number"]``: integer + Generic attribute number. This is provided for information only. + Blender doesn't use ``glBindAttribLocation`` to place generic attributes at specific location, it lets the shader compiler place the attributes automatically and query the - placement with glGetAttribLocation. The result of this placement is returned in - this element. + placement with ``glGetAttribLocation``. + The result of this placement is returned in this element. When using this shader in a render engine, you should either use - glBindAttribLocation to force the attribute at this location or use - glGetAttribLocation to get the placement chosen by the compiler of your GPU. + ``glBindAttribLocation`` to force the attribute at this location or use + ``glGetAttribLocation`` to get the placement chosen by the compiler of your GPU. - * ["type"] : integer + - ``["type"]``: integer type of the mesh custom data from which the vertex attribute is loaded. See attribute-type_. - * ["name"] : string or integer + - ``["name"]``: string or integer custom data layer name, used for attribute type :data:`gpu.CD_MTFACE` and :data:`gpu.CD_MCOL`. Example: @@ -512,14 +658,14 @@ Notes .. _mat4_lamp_to_perspective: -1. Calculation of the *mat4_lamp_to_perspective* matrix for a spot lamp. +#. Calculation of the ``mat4_lamp_to_perspective`` matrix for a spot lamp. - The following pseudo code shows how the *mat4_lamp_to_perspective* matrix is computed + The following pseudo code shows how the ``mat4_lamp_to_perspective`` matrix is computed in blender for uniforms of :data:`gpu.GPU_DYNAMIC_LAMP_DYNPERSMAT` type: .. code-block:: python - #Get the lamp datablock with: + # Get the lamp datablock with: lamp = bpy.data.objects[uniform["lamp"]].data # Compute the projection matrix: @@ -531,11 +677,11 @@ Notes # The size of the projection plane is computed with the usual formula: wsize = lamp.clista * tan(lamp.spotsize/2) - #And the projection matrix: + # And the projection matrix: mat4_lamp_to_perspective = glFrustum(-wsize, wsize, -wsize, wsize, lamp.clista, lamp.clipend) -2. Creation of the shadow map for a spot lamp. +#. Creation of the shadow map for a spot lamp. The shadow map is the depth buffer of a render performed by placing the camera at the - spot light position. The size of the shadow map is given by the attribute lamp.bufsize : + spot light position. The size of the shadow map is given by the attribute ``lamp.bufsize``: shadow map size in pixel, same size in both dimensions. diff --git a/doc/python_api/rst/info_api_reference.rst b/doc/python_api/rst/info_api_reference.rst index ddee46dce11..43469fc0cb7 100644 --- a/doc/python_api/rst/info_api_reference.rst +++ b/doc/python_api/rst/info_api_reference.rst @@ -121,7 +121,7 @@ Here are some more complex examples: bpy.context.scene.render.layers["RenderLayer"].samples # access to the current weight paint brush size - bpy.context.tool_settings.weight_paint.brush.size + bpy.context.tool_settings.weight_paint.brush.size # check if the window is fullscreen bpy.context.window.screen.show_fullscreen @@ -141,15 +141,16 @@ When starting out scripting you will often run into the problem where you're not There are a few ways to do this. -- Use the Python console's auto-complete to inspect properties. *This can be hit-and-miss but has the advantage +- Use the Python console's auto-complete to inspect properties. + *This can be hit-and-miss but has the advantage that you can easily see the values of properties and assign them to interactively see the results.* +- Copy the Data-Path from the user interface. + *Explained further in :ref:`Copy Data Path <info_data_path_copy>`* +- Using the documentation to follow references. + *Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`* -- Copy the Data-Path from the user interface. *Explained further in :ref:`Copy Data Path <info_data_path_copy>`* -- Using the documentation to follow references. *Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`* - - -.. _info_data_path_copy +.. _info_data_path_copy: Copy Data Path -------------- @@ -172,7 +173,8 @@ you won't be doing collection look-ups on every access and typically you'll want then access each :class:`bpy.types.ID` instance by name. -Type in the ID path into a Python console :mod:`bpy.context.active_object`. Include the trailing dot and don't hit "enter", yet. +Type in the ID path into a Python console :mod:`bpy.context.active_object`. +Include the trailing dot and don't hit "enter", yet. Now right-click on the button and select **Copy Data Path**, then paste the result into the console. @@ -191,7 +193,7 @@ Hit "enter" and you'll get the current value of 1. Now try changing the value to You can see the value update in the Subdivision-Surface modifier's UI as well as the cube. -.. _info_data_path_indirect +.. _info_data_path_indirect: Indirect Data Access -------------------- @@ -201,32 +203,24 @@ For this example we'll go over something more involved, showing the steps to acc Lets say we want to access the texture of a brush via Python, to adjust its ``contrast`` for example. - Start in the default scene and enable 'Sculpt' mode from the 3D-View header. - - From the toolbar expand the **Texture** panel and add a new texture. - *Notice the texture button its self doesn't have very useful links (you can check the tool-tips).* - - The contrast setting isn't exposed in the sculpt toolbar, so view the texture in the properties panel... - In the properties button select the Texture context. - - Select the Brush icon to show the brush texture. - - - Expand the **Colors** panel to locate the **Contrast** button. - -- Right click on the contrast button and select **Online Python Reference** This takes you to ``bpy.types.Texture.contrast`` - -- Now we can see that ``contrast`` is a property of texture, so next we'll check on how to access the texture from the brush. - + - Expand the *Colors* panel to locate the *Contrast* button. +- Right click on the contrast button and select **Online Python Reference** + This takes you to ``bpy.types.Texture.contrast`` +- Now we can see that ``contrast`` is a property of texture, + so next we'll check on how to access the texture from the brush. - Check on the **References** at the bottom of the page, sometimes there are many references, and it may take some guess work to find the right one, but in this case its obviously ``Brush.texture``. *Now we know that the texture can be accessed from* ``bpy.data.brushes["BrushName"].texture`` *but normally you won't want to access the brush by name, so we'll see now to access the active brush instead.* - - So the next step is to check on where brushes are accessed from via the **References**. In this case there is simply ``bpy.context.brush`` which is all we need. - Now you can use the Python console to form the nested properties needed to access brush textures contrast, logically we now know. @@ -282,7 +276,8 @@ are interested to check on the source code. .. note:: - Not all operators can be called usefully from Python, for more on this see :ref:`using operators <using_operators>`. + Not all operators can be called usefully from Python, + for more on this see :ref:`using operators <using_operators>`. Info View @@ -294,7 +289,8 @@ This is located above the file-menu which can be dragged down to display its con Select the **Script** screen that comes default with Blender to see its output. You can perform some actions and see them show up - delete a vertex for example. -Each entry can be selected (Right-Mouse-Button), then copied :kbd:`Control-C`, usually to paste in the text editor or python console. +Each entry can be selected (Right-Mouse-Button), +then copied :kbd:`Control-C`, usually to paste in the text editor or python console. .. note:: diff --git a/doc/python_api/rst/info_best_practice.rst b/doc/python_api/rst/info_best_practice.rst index 1e12daba893..8c5ae3398bc 100644 --- a/doc/python_api/rst/info_best_practice.rst +++ b/doc/python_api/rst/info_best_practice.rst @@ -1,16 +1,20 @@ + ************* Best Practice ************* -When writing your own scripts python is great for new developers to pick up and become productive, but you can also pick up odd habits or at least write scripts that are not easy for others to understand. +When writing your own scripts python is great for new developers to pick up and become productive, +but you can also pick up odd habits or at least write scripts that are not easy for others to understand. -For your own work this is of course fine, but if you want to collaborate with others or have your work included with blender there are practices we encourage. +For your own work this is of course fine, +but if you want to collaborate with others or have your work included with blender there are practices we encourage. Style Conventions ================= -For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles amongst our own scripts and make it easier to use python scripts from other projects. +For Blender/Python development we have chosen to follow python suggested style guide to avoid mixing styles +amongst our own scripts and make it easier to use python scripts from other projects. Using our style guide for your own scripts makes it easier if you eventually want to contribute them to blender. @@ -18,22 +22,17 @@ This style guide is known as pep8 and can be found `here <http://www.python.org/ A brief listing of pep8 criteria. -* camel caps for class names: MyClass - -* all lower case underscore separated module names: my_module - -* indentation of 4 spaces (no tabs) - -* spaces around operators. ``1 + 1``, not ``1+1`` - -* only use explicit imports, (no importing '*') - -* don't use single line: ``if val: body``, separate onto 2 lines instead. +- camel caps for class names: MyClass +- all lower case underscore separated module names: my_module +- indentation of 4 spaces (no tabs) +- spaces around operators. ``1 + 1``, not ``1+1`` +- only use explicit imports, (no importing ``*``) +- don't use single line: ``if val: body``, separate onto 2 lines instead. As well as pep8 we have other conventions used for blender python scripts. -* Use single quotes for enums, and double quotes for strings. +- Use single quotes for enums, and double quotes for strings. Both are of course strings but in our internal API enums are unique items from a limited set. eg. @@ -42,9 +41,11 @@ As well as pep8 we have other conventions used for blender python scripts. bpy.context.scene.render.image_settings.file_format = 'PNG' bpy.context.scene.render.filepath = "//render_out" -* pep8 also defines that lines should not exceed 79 characters, we felt this is too restrictive so this is optional per script. +- pep8 also defines that lines should not exceed 79 characters, + we felt this is too restrictive so this is optional per script. -Periodically we run checks for pep8 compliance on blender scripts, for scripts to be included in this check add this line as a comment at the top of the script. +Periodically we run checks for pep8 compliance on blender scripts, +for scripts to be included in this check add this line as a comment at the top of the script. ``# <pep8 compliant>`` @@ -58,72 +59,75 @@ User Interface Layout Some notes to keep in mind when writing UI layouts: -* UI code is quite simple. Layout declarations are there to easily create a decent layout. +- UI code is quite simple. Layout declarations are there to easily create a decent layout. + + General rule here: If you need more code for the layout declaration, + then for the actual properties, you do it wrong. - General rule here: If you need more code for the layout declaration, then for the actual properties, you do it wrong. - Example layouts: -* layout() +- layout() + + The basic layout is a simple Top -> Bottom layout. - The basic layout is a simple Top -> Bottom layout. - .. code-block:: python - layout.prop() - layout.prop() + layout.prop() + layout.prop() + +- layout.row() -* layout.row() + Use row(), when you want more than 1 property in one line. - Use row(), when you want more than 1 property in one line. - .. code-block:: python - - row = layout.row() - row.prop() - row.prop() -* layout.column() + row = layout.row() + row.prop() + row.prop() + +- layout.column() Use column(), when you want your properties in a column. - + .. code-block:: python - - col = layout.column() - col.prop() - col.prop() -* layout.split() + col = layout.column() + col.prop() + col.prop() - This can be used to create more complex layouts. For example you can split the layout and create two column() layouts next to each other. +- layout.split() + + This can be used to create more complex layouts. + For example you can split the layout and create two column() layouts next to each other. Don't use split, when you simply want two properties in a row. Use row() for that. - + .. code-block:: python - - split = layout.split() - - col = split.column() - col.prop() - col.prop() - - col = split.column() - col.prop() - col.prop() - + + split = layout.split() + + col = split.column() + col.prop() + col.prop() + + col = split.column() + col.prop() + col.prop() + Declaration names: Try to only use these variable names for layout declarations: -* row for a row() layout -* col for a column() layout -* split for a split() layout -* flow for a column_flow() layout -* sub for a sub layout (a column inside a column for example) +- row for a row() layout +- col for a column() layout +- split for a split() layout +- flow for a column_flow() layout +- sub for a sub layout (a column inside a column for example) Script Efficiency ================= + List Manipulation (General Python Tips) --------------------------------------- @@ -133,7 +137,8 @@ Searching for list items In Python there are some handy list functions that save you having to search through the list. -Even though you're not looping on the list data **python is**, so you need to be aware of functions that will slow down your script by searching the whole list. +Even though you're not looping on the list data **python is**, +so you need to be aware of functions that will slow down your script by searching the whole list. .. code-block:: python @@ -145,11 +150,16 @@ Even though you're not looping on the list data **python is**, so you need to be Modifying Lists ^^^^^^^^^^^^^^^ -In python we can add and remove from a list, this is slower when the list length is modified, especially at the start of the list, since all the data after the index of modification needs to be moved up or down 1 place. +In python we can add and remove from a list, this is slower when the list length is modified, +especially at the start of the list, since all the data after the index of +modification needs to be moved up or down 1 place. -The most simple way to add onto the end of the list is to use ``my_list.append(list_item)`` or ``my_list.extend(some_list)`` and the fastest way to remove an item is ``my_list.pop()`` or ``del my_list[-1]``. +The most simple way to add onto the end of the list is to use +``my_list.append(list_item)`` or ``my_list.extend(some_list)`` and the fastest way to +remove an item is ``my_list.pop()`` or ``del my_list[-1]``. -To use an index you can use ``my_list.insert(index, list_item)`` or ``list.pop(index)`` for list removal, but these are slower. +To use an index you can use ``my_list.insert(index, list_item)`` or ``list.pop(index)`` +for list removal, but these are slower. Sometimes its faster (but more memory hungry) to just rebuild the list. @@ -193,7 +203,8 @@ Use... my_list.extend([a, b, c...]) -Note that insert can be used when needed, but it is slower than append especially when inserting at the start of a long list. +Note that insert can be used when needed, +but it is slower than append especially when inserting at the start of a long list. This example shows a very sub-optimal way of making a reversed list. @@ -205,7 +216,8 @@ This example shows a very sub-optimal way of making a reversed list. reverse_list.insert(0, list_item) -Python provides more convenient ways to reverse a list using the slice method, but you may want to time this before relying on it too much: +Python provides more convenient ways to reverse a list using the slice method, +but you may want to time this before relying on it too much: .. code-block:: python @@ -220,7 +232,8 @@ Use ``my_list.pop(index)`` rather than ``my_list.remove(list_item)`` This requires you to have the index of the list item but is faster since ``remove()`` will search the list. -Here is an example of how to remove items in 1 loop, removing the last items first, which is faster (as explained above). +Here is an example of how to remove items in 1 loop, +removing the last items first, which is faster (as explained above). .. code-block:: python @@ -232,7 +245,9 @@ Here is an example of how to remove items in 1 loop, removing the last items fir my_list.pop(list_index) -This example shows a fast way of removing items, for use in cases where you can alter the list order without breaking the scripts functionality. This works by swapping 2 list items, so the item you remove is always last. +This example shows a fast way of removing items, +for use in cases where you can alter the list order without breaking the scripts functionality. +This works by swapping 2 list items, so the item you remove is always last. .. code-block:: python @@ -251,7 +266,9 @@ When removing many items in a large list this can provide a good speedup. Avoid Copying Lists ^^^^^^^^^^^^^^^^^^^ -When passing a list/dictionary to a function, it is faster to have the function modify the list rather than returning a new list so python doesn't have to duplicate the list in memory. +When passing a list/dictionary to a function, +it is faster to have the function modify the list rather than returning +a new list so python doesn't have to duplicate the list in memory. Functions that modify a list in-place are more efficient than functions that create new lists. @@ -296,20 +313,26 @@ Python’s string joining function. To join a list of strings >>> file.write(" ".join([str1, str2, str3, "\n"])) -join is fastest on many strings, `string formatting <http://docs.python.org/py3k/library/string.html#string-formatting>`_ is quite fast too (better for converting data types). String arithmetic is slowest. +join is fastest on many strings, +`string formatting <http://docs.python.org/py3k/library/string.html#string-formatting>`__ +is quite fast too (better for converting data types). String arithmetic is slowest. Parsing Strings (Import/Exporting) ---------------------------------- -Since many file formats are ASCII, the way you parse/export strings can make a large difference in how fast your script runs. +Since many file formats are ASCII, +the way you parse/export strings can make a large difference in how fast your script runs. There are a few ways to parse strings when importing them into Blender. + Parsing Numbers ^^^^^^^^^^^^^^^ -Use ``float(string)`` rather than ``eval(string)``, if you know the value will be an int then ``int(string)``, float() will work for an int too but it's faster to read ints with int(). +Use ``float(string)`` rather than ``eval(string)``, if you know the value will be an int then ``int(string)``, +float() will work for an int too but it's faster to read ints with int(). + Checking String Start/End ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -322,7 +345,8 @@ Use... >>> if line.startswith("vert "): -Using ``startswith()`` is slightly faster (approx 5%) and also avoids a possible error with the slice length not matching the string length. +Using ``startswith()`` is slightly faster (approx 5%) and also avoids a possible +error with the slice length not matching the string length. my_string.endswith("foo_bar") can be used for line endings too. @@ -336,15 +360,19 @@ Use try/except Sparingly The **try** statement is useful to save time writing error checking code. -However **try** is significantly slower than an **if** since an exception has to be set each time, so avoid using **try** in areas of your code that execute in a loop and runs many times. +However **try** is significantly slower than an **if** since an exception has to be set each time, +so avoid using **try** in areas of your code that execute in a loop and runs many times. -There are cases where using **try** is faster than checking whether the condition will raise an error, so it is worth experimenting. +There are cases where using **try** is faster than checking whether the condition will raise an error, +so it is worth experimenting. Value Comparison ---------------- -Python has two ways to compare values ``a == b`` and ``a is b``, the difference is that ``==`` may run the objects comparison function ``__cmp__()`` whereas ``is`` compares identity, that both variables reference the same item in memory. +Python has two ways to compare values ``a == b`` and ``a is b``, +the difference is that ``==`` may run the objects comparison function ``__cmp__()`` whereas ``is`` compares identity, +that both variables reference the same item in memory. In cases where you know you are checking for the same value which is referenced from multiple places, ``is`` is faster. @@ -362,3 +390,4 @@ While developing a script it's good to time it to be aware of any changes in per # do something... print("My Script Finished: %.4f sec" % time.time() - time_start) + diff --git a/doc/python_api/rst/info_gotcha.rst b/doc/python_api/rst/info_gotcha.rst index 35f9c1bda9f..430a862cf7b 100644 --- a/doc/python_api/rst/info_gotcha.rst +++ b/doc/python_api/rst/info_gotcha.rst @@ -2,7 +2,8 @@ Gotchas ******* -This document attempts to help you work with the Blender API in areas that can be troublesome and avoid practices that are known to give instability. +This document attempts to help you work with the Blender API in areas +that can be troublesome and avoid practices that are known to give instability. .. _using_operators: @@ -10,16 +11,15 @@ This document attempts to help you work with the Blender API in areas that can b Using Operators =============== -Blender's operators are tools for users to access, that python can access them too is very useful nevertheless operators have limitations that can make them cumbersome to script. +Blender's operators are tools for users to access, that Python can access them too is very useful +nevertheless operators have limitations that can make them cumbersome to script. Main limits are... -* Can't pass data such as objects, meshes or materials to operate on (operators use the context instead) - -* The return value from calling an operator gives the success (if it finished or was canceled), +- Can't pass data such as objects, meshes or materials to operate on (operators use the context instead) +- The return value from calling an operator gives the success (if it finished or was canceled), in some cases it would be more logical from an API perspective to return the result of the operation. - -* Operators poll function can fail where an API function would raise an exception giving details on exactly why. +- Operators poll function can fail where an API function would raise an exception giving details on exactly why. Why does an operator's poll fail? @@ -32,20 +32,28 @@ When calling an operator gives an error like this: Which raises the question as to what the correct context might be? -Typically operators check for the active area type, a selection or active object they can operate on, but some operators are more picky about when they run. +Typically operators check for the active area type, a selection or active object they can operate on, +but some operators are more picky about when they run. -In most cases you can figure out what context an operator needs simply be seeing how it's used in Blender and thinking about what it does. +In most cases you can figure out what context an operator needs +simply be seeing how it's used in Blender and thinking about what it does. -Unfortunately if you're still stuck - the only way to **really** know whats going on is to read the source code for the poll function and see what its checking. +Unfortunately if you're still stuck - the only way to **really** know +whats going on is to read the source code for the poll function and see what its checking. -For python operators it's not so hard to find the source since it's included with Blender and the source file/line is included in the operator reference docs. +For Python operators it's not so hard to find the source +since it's included with Blender and the source file/line is included in the operator reference docs. -Downloading and searching the C code isn't so simple, especially if you're not familiar with the C language but by searching the operator name or description you should be able to find the poll function with no knowledge of C. +Downloading and searching the C code isn't so simple, +especially if you're not familiar with the C language but by searching the +operator name or description you should be able to find the poll function with no knowledge of C. .. note:: - Blender does have the functionality for poll functions to describe why they fail, but its currently not used much, if you're interested to help improve our API feel free to add calls to ``CTX_wm_operator_poll_msg_set`` where its not obvious why poll fails. + Blender does have the functionality for poll functions to describe why they fail, + but its currently not used much, if you're interested to help improve our API + feel free to add calls to ``CTX_wm_operator_poll_msg_set`` where its not obvious why poll fails. >>> bpy.ops.gpencil.draw() RuntimeError: Operator bpy.ops.gpencil.draw.poll() Failed to find Grease Pencil data to draw into @@ -54,40 +62,57 @@ Downloading and searching the C code isn't so simple, especially if you're not f The operator still doesn't work! -------------------------------- -Certain operators in Blender are only intended for use in a specific context, some operators for example are only called from the properties window where they check the current material, modifier or constraint. +Certain operators in Blender are only intended for use in a specific context, +some operators for example are only called from the properties window where they check the current material, +modifier or constraint. Examples of this are: -* :mod:`bpy.ops.texture.slot_move` -* :mod:`bpy.ops.constraint.limitdistance_reset` -* :mod:`bpy.ops.object.modifier_copy` -* :mod:`bpy.ops.buttons.file_browse` +- :mod:`bpy.ops.texture.slot_move` +- :mod:`bpy.ops.constraint.limitdistance_reset` +- :mod:`bpy.ops.object.modifier_copy` +- :mod:`bpy.ops.buttons.file_browse` -Another possibility is that you are the first person to attempt to use this operator in a script and some modifications need to be made to the operator to run in a different context, if the operator should logically be able to run but fails when accessed from a script it should be reported to the bug tracker. +Another possibility is that you are the first person to attempt to use this operator +in a script and some modifications need to be made to the operator to run in a different context, +if the operator should logically be able to run but fails when accessed from a script +it should be reported to the bug tracker. Stale Data ========== + No updates after setting values ------------------------------- -Sometimes you want to modify values from python and immediately access the updated values, eg: +Sometimes you want to modify values from Python and immediately access the updated values, eg: -Once changing the objects :class:`bpy.types.Object.location` you may want to access its transformation right after from :class:`bpy.types.Object.matrix_world`, but this doesn't work as you might expect. +Once changing the objects :class:`bpy.types.Object.location` +you may want to access its transformation right after from :class:`bpy.types.Object.matrix_world`, +but this doesn't work as you might expect. Consider the calculations that might go into working out the object's final transformation, this includes: -* animation function curves. -* drivers and their pythons expressions. -* constraints -* parent objects and all of their f-curves, constraints etc. +- animation function curves. +- drivers and their Python expressions. +- constraints +- parent objects and all of their f-curves, constraints etc. -To avoid expensive recalculations every time a property is modified, Blender defers making the actual calculations until they are needed. +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 -This can be done by calling :class:`bpy.types.Scene.update` after modifying values which recalculates all data that is tagged to be updated. + bpy.context.object.location = 1, 2, 3 + bpy.context.scene.update() + + +Now all dependent data (child objects, modifiers, drivers... etc) +has been recalculated and is available to the script. Can I redraw during the script? @@ -97,23 +122,33 @@ The official answer to this is no, or... *"You don't want to do that"*. To give some background on the topic... -While a script executes Blender waits for it to finish and is effectively locked until its done, while in this state Blender won't redraw or respond to user input. -Normally this is not such a problem because scripts distributed with Blender tend not to run for an extended period of time, nevertheless scripts *can* take ages to execute and its nice to see whats going on in the view port. +While a script executes Blender waits for it to finish and is effectively locked until its done, +while in this state Blender won't redraw or respond to user input. +Normally this is not such a problem because scripts distributed with Blender +tend not to run for an extended period of time, +nevertheless scripts *can* take ages to execute and its nice to see whats going on in the view port. -Tools that lock Blender in a loop and redraw are highly discouraged since they conflict with Blenders ability to run multiple operators at once and update different parts of the interface as the tool runs. +Tools that lock Blender in a loop and redraw are highly discouraged +since they conflict with Blenders ability to run multiple operators +at once and update different parts of the interface as the tool runs. -So the solution here is to write a **modal** operator, that is - an operator which defines a modal() function, See the modal operator template in the text editor. +So the solution here is to write a **modal** operator, that is - an operator which defines a modal() function, +See the modal operator template in the text editor. -Modal operators execute on user input or setup their own timers to run frequently, they can handle the events or pass through to be handled by the keymap or other modal operators. +Modal operators execute on user input or setup their own timers to run frequently, +they can handle the events or pass through to be handled by the keymap or other modal operators. Transform, Painting, Fly-Mode and File-Select are example of a modal operators. -Writing modal operators takes more effort than a simple ``for`` loop that happens to redraw but is more flexible and integrates better with Blenders design. +Writing modal operators takes more effort than a simple ``for`` loop +that happens to redraw but is more flexible and integrates better with Blenders design. -**Ok, Ok! I still want to draw from python** +**Ok, Ok! I still want to draw from Python** -If you insist - yes its possible, but scripts that use this hack wont be considered for inclusion in Blender and any issues with using it wont be considered bugs, this is also not guaranteed to work in future releases. +If you insist - yes its possible, but scripts that use this hack wont be considered +for inclusion in Blender and any issues with using it wont be considered bugs, +this is also not guaranteed to work in future releases. .. code-block:: python @@ -123,16 +158,18 @@ If you insist - yes its possible, but scripts that use this hack wont be conside Modes and Mesh Access ===================== -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. +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. -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. +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. In this situation you can... -* 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. +- 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: @@ -140,35 +177,55 @@ In this situation you can... NGons and Tessellation Faces ============================ -Since 2.63 NGons are supported, this adds some complexity since in some cases you need to access triangles/quads still (some exporters for example). +Since 2.63 NGons are supported, this adds some complexity +since in some cases you need to access triangles/quads still (some exporters for example). There are now 3 ways to access faces: -* :class:`bpy.types.MeshPolygon` - this is the data structure which now stores faces in object mode (access as ``mesh.polygons`` rather then ``mesh.faces``). -* :class:`bpy.types.MeshTessFace` - the result of triangulating (tessellated) polygons, the main method of face access in 2.62 or older (access as ``mesh.tessfaces``). -* :class:`bmesh.types.BMFace` - the polygons as used in editmode. +- :class:`bpy.types.MeshPolygon` - + this is the data structure which now stores faces in object mode + (access as ``mesh.polygons`` rather than ``mesh.faces``). +- :class:`bpy.types.MeshTessFace` - + the result of triangulating (tessellated) polygons, + the main method of face access in 2.62 or older (access as ``mesh.tessfaces``). +- :class:`bmesh.types.BMFace` - + the polygons as used in editmode. -For the purpose of the following documentation, these will be referred to as polygons, tessfaces and bmesh-faces respectively. +For the purpose of the following documentation, +these will be referred to as polygons, tessfaces and bmesh-faces respectively. 5+ sided faces will be referred to as ``ngons``. + Support Overview ---------------- -+--------------+------------------------------+--------------------------------+--------------------------------+ -|Usage |:class:`bpy.types.MeshPolygon`|:class:`bpy.types.MeshTessFace` |:class:`bmesh.types.BMFace` | -+==============+==============================+================================+================================+ -|Import/Create |Bad (inflexible) |Fine (supported as upgrade path)|Best | -+--------------+------------------------------+--------------------------------+--------------------------------+ -|Manipulate |Bad (inflexible) |Bad (loses ngons) |Best | -+--------------+------------------------------+--------------------------------+--------------------------------+ -|Export/Output |Good (ngons) |Good (When ngons can't be used) |Good (ngons, memory overhead) | -+--------------+------------------------------+--------------------------------+--------------------------------+ - +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + + * - Usage + - :class:`bpy.types.MeshPolygon` + - :class:`bpy.types.MeshTessFace` + - :class:`bmesh.types.BMFace` + * - Import/Create + - Poor *(inflexible)* + - Good *(supported as upgrade path)* + - Best + * - Manipulate + - Poor *(inflexible)* + - Poor *(loses ngons)* + - Best + * - Export/Output + - Good *(ngon support)* + - Good *(When ngons can't be used)* + - Good *(ngons, extra memory overhead)* .. note:: - Using the :mod:`bmesh` api is completely separate api from :mod:`bpy`, typically you would would use one or the other based on the level of editing needed, not simply for a different way to access faces. + Using the :mod:`bmesh` api is completely separate api from :mod:`bpy`, + typically you would would use one or the other based on the level of editing needed, + not simply for a different way to access faces. Creating @@ -176,9 +233,18 @@ Creating All 3 datatypes can be used for face creation. -* polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, you must have all your vertes and faces ready and create them all at once. This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), rather they reference an index and size in :class:`bpy.types.Mesh.loops` which are a fixed array too. -* tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, however for scripts upgrading from 2.62 this is by far the most straightforward option. This works by creating tessfaces and when finished - they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. The obvious limitation is ngons can't be created this way. -* bmesh-faces are most likely the easiest way for new scripts to create faces, since faces can be added one by one and the api has features intended for mesh manipulation. While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time. +- polygons are the most efficient way to create faces but the data structure is _very_ rigid and inflexible, + you must have all your vertes and faces ready and create them all at once. + This is further complicated by the fact that each polygon does not store its own verts (as with tessfaces), + rather they reference an index and size in :class:`bpy.types.Mesh.loops` which are a fixed array too. +- tessfaces ideally should not be used for creating faces since they are really only tessellation cache of polygons, + however for scripts upgrading from 2.62 this is by far the most straightforward option. + This works by creating tessfaces and when finished - + they can be converted into polygons by calling :class:`bpy.types.Mesh.update`. + The obvious limitation is ngons can't be created this way. +- bmesh-faces are most likely the easiest way for new scripts to create faces, + since faces can be added one by one and the api has features intended for mesh manipulation. + While :class:`bmesh.types.BMesh` uses more memory it can be managed by only operating on one mesh at a time. Editing @@ -186,18 +252,24 @@ Editing Editing is where the 3 data types vary most. -* polygons are very limited for editing, changing materials and options like smooth works but for anything else they are too inflexible and are only intended for storage. -* tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated. -* bmesh-faces are by far the best way to manipulate geometry. +- Polygons are very limited for editing, + changing materials and options like smooth works but for anything else + they are too inflexible and are only intended for storage. +- Tessfaces should not be used for editing geometry because doing so will cause existing ngons to be tessellated. +- BMesh-Faces are by far the best way to manipulate geometry. + Exporting --------- -All 3 data types can be used for exporting, the choice mostly depends on whether the target format supports ngons or not. +All 3 data types can be used for exporting, +the choice mostly depends on whether the target format supports ngons or not. -* polygons are the most direct & efficient way to export providing they convert into the output format easily enough. -* tessfaces work well for exporting to formats which dont support ngons, in fact this is the only place where their use is encouraged. -* bmesh-faces can work for exporting too but may not be necessary if polygons can be used since using bmesh gives some overhead because its not the native storage format in object mode. +- Polygons are the most direct & efficient way to export providing they convert into the output format easily enough. +- Tessfaces work well for exporting to formats which dont support ngons, + in fact this is the only place where their use is encouraged. +- BMesh-Faces can work for exporting too but may not be necessary if polygons can be used + since using bmesh gives some overhead because its not the native storage format in object mode. Upgrading Importers from 2.62 @@ -207,9 +279,9 @@ Importers can be upgraded to work with only minor changes. The main change to be made is used the tessellation versions of each attribute. -* mesh.faces --> :class:`bpy.types.Mesh.tessfaces` -* mesh.uv_textures --> :class:`bpy.types.Mesh.tessface_uv_textures` -* mesh.vertex_colors --> :class:`bpy.types.Mesh.tessface_vertex_colors` +- mesh.faces --> :class:`bpy.types.Mesh.tessfaces` +- mesh.uv_textures --> :class:`bpy.types.Mesh.tessface_uv_textures` +- mesh.vertex_colors --> :class:`bpy.types.Mesh.tessface_vertex_colors` Once the data is created call :class:`bpy.types.Mesh.update` to convert the tessfaces into polygons. @@ -217,7 +289,9 @@ Once the data is created call :class:`bpy.types.Mesh.update` to convert the tess Upgrading Exporters from 2.62 ----------------------------- -For exporters the most direct way to upgrade is to use tessfaces as with importing however its important to know that tessfaces may **not** exist for a mesh, the array will be empty as if there are no faces. +For exporters the most direct way to upgrade is to use tessfaces as with importing +however its important to know that tessfaces may **not** exist for a mesh, +the array will be empty as if there are no faces. So before accessing tessface data call: :class:`bpy.types.Mesh.update` ``(calc_tessface=True)``. @@ -225,7 +299,8 @@ So before accessing tessface data call: :class:`bpy.types.Mesh.update` ``(calc_t EditBones, PoseBones, Bone... Bones =================================== -Armature Bones in Blender have three distinct data structures that contain them. If you are accessing the bones through one of them, you may not have access to the properties you really need. +Armature Bones in Blender have three distinct data structures that contain them. +If you are accessing the bones through one of them, you may not have access to the properties you really need. .. note:: @@ -235,7 +310,9 @@ Armature Bones in Blender have three distinct data structures that contain them. Edit Bones ---------- -``bpy.context.object.data.edit_bones`` contains a editbones; to access them you must set the armature mode to edit mode first (editbones do not exist in object or pose mode). Use these to create new bones, set their head/tail or roll, change their parenting relationships to other bones, etc. +``bpy.context.object.data.edit_bones`` contains a editbones; +to access them you must set the armature mode to edit mode first (editbones do not exist in object or pose mode). +Use these to create new bones, set their head/tail or roll, change their parenting relationships to other bones, etc. Example using :class:`bpy.types.EditBone` in armature editmode: @@ -255,7 +332,9 @@ Returns an editbone only in edit mode. Bones (Object Mode) ------------------- -``bpy.context.object.data.bones`` contains bones. These *live* in object mode, and have various properties you can change, note that the head and tail properties are read-only. +``bpy.context.object.data.bones`` contains bones. +These *live* in object mode, and have various properties you can change, +note that the head and tail properties are read-only. Example using :class:`bpy.types.Bone` in object or pose mode: @@ -275,7 +354,9 @@ Accessible but read-only Pose Bones ---------- -``bpy.context.object.pose.bones`` contains pose bones. This is where animation data resides, i.e. animatable transformations are applied to pose bones, as are constraints and ik-settings. +``bpy.context.object.pose.bones`` contains pose bones. +This is where animation data resides, i.e. animatable transformations +are applied to pose bones, as are constraints and ik-settings. Examples using :class:`bpy.types.PoseBone` in object or pose mode: @@ -290,19 +371,27 @@ Examples using :class:`bpy.types.PoseBone` in object or pose mode: .. note:: - Notice the pose is accessed from the object rather than the object data, this is why blender can have 2 or more objects sharing the same armature in different poses. + Notice the pose is accessed from the object rather than the object data, + this is why blender can have 2 or more objects sharing the same armature in different poses. .. note:: - Strictly speaking PoseBone's are not bones, they are just the state of the armature, stored in the :class:`bpy.types.Object` rather than the :class:`bpy.types.Armature`, the real bones are however accessible from the pose bones - :class:`bpy.types.PoseBone.bone` + Strictly speaking PoseBone's are not bones, they are just the state of the armature, + stored in the :class:`bpy.types.Object` rather than the :class:`bpy.types.Armature`, + the real bones are however accessible from the pose bones - :class:`bpy.types.PoseBone.bone` Armature Mode Switching ----------------------- -While writing scripts that deal with armatures you may find you have to switch between modes, when doing so take care when switching out of editmode not to keep references to the edit-bones or their head/tail vectors. Further access to these will crash blender so its important the script clearly separates sections of the code which operate in different modes. +While writing scripts that deal with armatures you may find you have to switch between modes, +when doing so take care when switching out of edit-mode not to keep references +to the edit-bones or their head/tail vectors. +Further access to these will crash blender so its important the script +clearly separates sections of the code which operate in different modes. -This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, however for operator access you may still need to enter pose mode. +This is mainly an issue with editmode since pose data can be manipulated without having to be in pose mode, +however for operator access you may still need to enter pose mode. Data Names @@ -337,10 +426,13 @@ Or with name assignment... Data names may not match the assigned values if they exceed the maximum length, are already used or an empty string. -Its better practice not to reference objects by names at all, once created you can store the data in a list, dictionary, on a class etc, there is rarely a reason to have to keep searching for the same data by name. - +Its better practice not to reference objects by names at all, +once created you can store the data in a list, dictionary, on a class etc, +there is rarely a reason to have to keep searching for the same data by name. -If you do need to use name references, its best to use a dictionary to maintain a mapping between the names of the imported assets and the newly created data, this way you don't run this risk of referencing existing data from the blend file, or worse modifying it. +If you do need to use name references, its best to use a dictionary to maintain +a mapping between the names of the imported assets and the newly created data, +this way you don't run this risk of referencing existing data from the blend file, or worse modifying it. .. code-block:: python @@ -352,18 +444,22 @@ If you do need to use name references, its best to use a dictionary to maintain # normally some code, or function calls... - # use own dictionary rather then bpy.data + # use own dictionary rather than bpy.data mesh = mesh_name_mapping[meshid] Library Collisions ------------------ -Blender keeps data names unique - :class:`bpy.types.ID.name` so you can't name two objects, meshes, scenes etc the same thing by accident. +Blender keeps data names unique - :class:`bpy.types.ID.name` so you can't name two objects, +meshes, scenes etc the same thing by accident. -However when linking in library data from another blend file naming collisions can occur, so its best to avoid referencing data by name at all. +However when linking in library data from another blend file naming collisions can occur, +so its best to avoid referencing data by name at all. -This can be tricky at times and not even blender handles this correctly in some case (when selecting the modifier object for eg you can't select between multiple objects with the same name), but its still good to try avoid problems in this area. +This can be tricky at times and not even blender handles this correctly in some case +(when selecting the modifier object for eg you can't select between multiple objects with the same name), +but its still good to try avoid problems in this area. If you need to select between local and library data, there is a feature in ``bpy.data`` members to allow for this. @@ -388,21 +484,23 @@ If you need to select between local and library data, there is a feature in ``bp Relative File Paths =================== -Blenders relative file paths are not compatible with standard python modules such as ``sys`` and ``os``. +Blenders relative file paths are not compatible with standard Python modules such as ``sys`` and ``os``. -Built in python functions don't understand blenders ``//`` prefix which denotes the blend file path. +Built in Python functions don't understand blenders ``//`` prefix which denotes the blend file path. A common case where you would run into this problem is when exporting a material with associated image paths. ->>> bpy.path.abspath(image.filepath) + >>> bpy.path.abspath(image.filepath) -When using blender data from linked libraries there is an unfortunate complication since the path will be relative to the library rather then the open blend file. When the data block may be from an external blend file pass the library argument from the :class:`bpy.types.ID`. +When using blender data from linked libraries there is an unfortunate complication +since the path will be relative to the library rather than the open blend file. +When the data block may be from an external blend file pass the library argument from the :class:`bpy.types.ID`. ->>> bpy.path.abspath(image.filepath, library=image.library) + >>> bpy.path.abspath(image.filepath, library=image.library) -These returns the absolute path which can be used with native python modules. +These returns the absolute path which can be used with native Python modules. Unicode Problems @@ -443,23 +541,28 @@ Here are 2 ways around filesystem encoding issues: >>> bpy.context.object.name = filepath_utf8 -Unicode encoding/decoding is a big topic with comprehensive python documentation, to avoid getting stuck too deep in encoding problems - here are some suggestions: - -* Always use utf-8 encoiding or convert to utf-8 where the input is unknown. +Unicode encoding/decoding is a big topic with comprehensive Python documentation, +to avoid getting stuck too deep in encoding problems - here are some suggestions: -* Avoid manipulating filepaths as strings directly, use ``os.path`` functions instead. +- Always use utf-8 encoding or convert to utf-8 where the input is unknown. +- Avoid manipulating filepaths as strings directly, use ``os.path`` functions instead. +- Use ``os.fsencode()`` / ``os.fsdecode()`` instead of built in string decoding functions when operating on paths. +- To print paths or to include them in the user interface use ``repr(path)`` first + or ``"%r" % path`` with string formatting. -* Use ``os.fsencode()`` / ``os.fsdecode()`` rather then the built in string decoding functions when operating on paths. - -* To print paths or to include them in the user interface use ``repr(path)`` first or ``"%r" % path`` with string formatting. +.. note:: -* **Possibly** - use bytes instead of python strings, when reading some input its less trouble to read it as binary data though you will still need to decide how to treat any strings you want to use with Blender, some importers do this. + Sometimes it's preferrable to avoid string encoding issues by using bytes instead of Python strings, + when reading some input its less trouble to read it as binary data + though you will still need to decide how to treat any strings you want to use with Blender, + some importers do this. Strange errors using 'threading' module ======================================= -Python threading with Blender only works properly when the threads finish up before the script does. By using ``threading.join()`` for example. +Python threading with Blender only works properly when the threads finish up before the script does. +By using ``threading.join()`` for example. Heres an example of threading supported by Blender: @@ -498,7 +601,8 @@ Heres an example of threading supported by Blender: t.join() -This an example of a timer which runs many times a second and moves the default cube continuously while Blender runs **(Unsupported)**. +This an example of a timer which runs many times a second and moves +the default cube continuously while Blender runs **(Unsupported)**. .. code-block:: python @@ -515,38 +619,48 @@ This an example of a timer which runs many times a second and moves the default my_timer() -Use cases like the one above which leave the thread running once the script finishes may seem to work for a while but end up causing random crashes or errors in Blender's own drawing code. +Use cases like the one above which leave the thread running once the script finishes +may seem to work for a while but end up causing random crashes or errors in Blender's own drawing code. -So far, no work has gone into making Blender's python integration thread safe, so until its properly supported, best not make use of this. +So far, no work has gone into making Blender's Python integration thread safe, +so until its properly supported, best not make use of this. .. note:: - Pythons threads only allow co-currency and won't speed up your scripts on multi-processor systems, the ``subprocess`` and ``multiprocess`` modules can be used with Blender and make use of multiple CPU's too. + Pythons threads only allow co-currency and won't speed up your scripts on multi-processor systems, + the ``subprocess`` and ``multiprocess`` modules can be used with Blender and make use of multiple CPU's too. Help! My script crashes Blender =============================== -Ideally it would be impossible to crash Blender from python however there are some problems with the API where it can be made to crash. +Ideally it would be impossible to crash Blender from Python +however there are some problems with the API where it can be made to crash. -Strictly speaking this is a bug in the API but fixing it would mean adding memory verification on every access since most crashes are caused by the python objects referencing Blenders memory directly, whenever the memory is freed, further python access to it can crash the script. But fixing this would make the scripts run very slow, or writing a very different kind of API which doesn't reference the memory directly. +Strictly speaking this is a bug in the API but fixing it would mean adding memory verification +on every access since most crashes are caused by the Python objects referencing Blenders memory directly, +whenever the memory is freed, further Python access to it can crash the script. +But fixing this would make the scripts run very slow, +or writing a very different kind of API which doesn't reference the memory directly. Here are some general hints to avoid running into these problems. -* Be aware of memory limits, especially when working with large lists since Blender can crash simply by running out of memory. - -* Many hard to fix crashes end up being because of referencing freed data, when removing data be sure not to hold any references to it. - -* Modules or classes that remain active while Blender is used, should not hold references to data the user may remove, instead, fetch data from the context each time the script is activated. - -* Crashes may not happen every time, they may happen more on some configurations/operating-systems. +- Be aware of memory limits, + especially when working with large lists since Blender can crash simply by running out of memory. +- Many hard to fix crashes end up being because of referencing freed data, + when removing data be sure not to hold any references to it. +- Modules or classes that remain active while Blender is used, + should not hold references to data the user may remove, instead, + fetch data from the context each time the script is activated. +- Crashes may not happen every time, they may happen more on some configurations/operating-systems. .. note:: To find the line of your script that crashes you can use the ``faulthandler`` module. See `faulthandler docs <http://docs.python.org/dev/library/faulthandler.html>`_. - While the crash may be in Blenders C/C++ code, this can help a lot to track down the area of the script that causes the crash. + While the crash may be in Blenders C/C++ code, + this can help a lot to track down the area of the script that causes the crash. Undo/Redo @@ -566,28 +680,36 @@ This example shows how you can tell undo changes the memory locations. >>> hash(bpy.context.object) -9223372036849951740 -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. +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. +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. +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. +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 ------------------------- -Switching edit-mode ``bpy.ops.object.mode_set(mode='EDIT')`` / ``bpy.ops.object.mode_set(mode='OBJECT')`` will re-allocate objects data, any references to a meshes vertices/polygons/uvs, armatures bones, curves points etc cannot be accessed after switching edit-mode. +Switching edit-mode ``bpy.ops.object.mode_set(mode='EDIT')`` / ``bpy.ops.object.mode_set(mode='OBJECT')`` +will re-allocate objects data, +any references to a meshes vertices/polygons/uvs, armatures bones, +curves points etc cannot be accessed after switching edit-mode. Only the reference to the data its self can be re-accessed, the following example will crash. @@ -602,7 +724,8 @@ Only the reference to the data its self can be re-accessed, the following exampl print(polygons) -So after switching edit-mode you need to re-access any object data variables, the following example shows how to avoid the crash above. +So after switching edit-mode you need to re-access any object data variables, +the following example shows how to avoid the crash above. .. code-block:: python @@ -616,13 +739,15 @@ So after switching edit-mode you need to re-access any object data variables, th print(polygons) -These kinds of problems can happen for any functions which re-allocate the object data but are most common when switching edit-mode. +These kinds of problems can happen for any functions which re-allocate +the object data but are most common when switching edit-mode. Array Re-Allocation ------------------- -When adding new points to a curve or vertices's/edges/polygons to a mesh, internally the array which stores this data is re-allocated. +When adding new points to a curve or vertices's/edges/polygons to a mesh, +internally the array which stores this data is re-allocated. .. code-block:: python @@ -633,15 +758,20 @@ When adding new points to a curve or vertices's/edges/polygons to a mesh, intern # this will crash! point.co = 1.0, 2.0, 3.0 -This can be avoided by re-assigning the point variables after adding the new one or by storing indices's to the points rather then the points themselves. +This can be avoided by re-assigning the point variables after adding the new one or by storing +indices's to the points rather than the points themselves. -The best way is to sidestep the problem altogether add all the points to the curve at once. This means you don't have to worry about array re-allocation and its faster too since reallocating the entire array for every point added is inefficient. +The best way is to sidestep the problem altogether add all the points to the curve at once. +This means you don't have to worry about array re-allocation and its faster too +since reallocating the entire array for every point added is inefficient. 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. +**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. The ``remove()`` api calls will invalidate the data they free to prevent common mistakes. @@ -652,12 +782,13 @@ The following example shows how this precortion works. 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: + print(mesh.name) # <- give an exception rather than 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. +But take care because this is limited to scripts accessing the variable which is removed, +the next example will still crash. .. code-block:: python @@ -670,9 +801,11 @@ But take care because this is limited to scripts accessing the variable which is sys.exit ======== -Some python modules will call ``sys.exit()`` themselves when an error occurs, while not common behavior this is something to watch out for because it may seem as if blender is crashing since ``sys.exit()`` will quit blender immediately. - -For example, the ``optparse`` module will print an error and exit if the arguments are invalid. +Some Python modules will call ``sys.exit()`` themselves when an error occurs, +while not common behavior this is something to watch out for because it may seem +as if Blender is crashing since ``sys.exit()`` will close Blender immediately. -An ugly way of troubleshooting this is to set ``sys.exit = None`` and see what line of python code is quitting, you could of course replace ``sys.exit`` with your own function but manipulating python in this way is bad practice. +For example, the ``argparse`` module will print an error and exit if the arguments are invalid. +An ugly way of troubleshooting this is to set ``sys.exit = None`` and see what line of Python code is quitting, +you could of course replace ``sys.exit`` with your own function but manipulating Python in this way is bad practice. diff --git a/doc/python_api/rst/info_overview.rst b/doc/python_api/rst/info_overview.rst index b2d524b74af..960dd07ecf1 100644 --- a/doc/python_api/rst/info_overview.rst +++ b/doc/python_api/rst/info_overview.rst @@ -1,18 +1,25 @@ + .. _info_overview: ******************* Python API Overview ******************* -This document is to give an understanding of how python and blender fit together, covering some of the functionality that isn't obvious from reading the API reference and example scripts. +This document is to give an understanding of how Python and Blender fit together, +covering some of the functionality that isn't obvious from reading the API reference and example scripts. Python in Blender ================= -Blender embeds a python interpreter which is started with blender and stays active. This interpreter runs scripts to draw the user interface and is used for some of Blender's internal tools too. +Blender embeds a Python interpreter which is started with Blender and stays active. +This interpreter runs scripts to draw the user interface and is used for some of Blender's internal tools too. -This is a typical python environment so tutorials on how to write python scripts will work running the scripts in blender too. Blender provides the :mod:`bpy` module to the python interpreter. This module can be imported in a script and gives access to blender data, classes, and functions. Scripts that deal with blender data will need to import this module. +This is a typical Python environment so tutorials on how to write Python scripts +will work running the scripts in Blender too. +Blender provides the :mod:`bpy` module to the Python interpreter. +This module can be imported in a script and gives access to Blender data, classes, and functions. +Scripts that deal with Blender data will need to import this module. Here is a simple example of moving a vertex of the object named **Cube**: @@ -21,84 +28,96 @@ Here is a simple example of moving a vertex of the object named **Cube**: import bpy bpy.data.objects["Cube"].data.vertices[0].co.x += 1.0 -This modifies Blender's internal data directly. When you run this in the interactive console you will see the 3D viewport update. +This modifies Blender's internal data directly. +When you run this in the interactive console you will see the 3D viewport update. The Default Environment ======================= -When developing your own scripts it may help to understand how blender sets up its python environment. Many python scripts come bundled with blender and can be used as a reference because they use the same API that script authors write tools in. Typical usage for scripts include: user interface, import/export, scene manipulation, automation, defining your own toolset and customization. +When developing your own scripts it may help to understand how Blender sets up its Python environment. +Many Python scripts come bundled with Blender and can be used as a reference +because they use the same API that script authors write tools in. +Typical usage for scripts include: user interface, import/export, +scene manipulation, automation, defining your own toolset and customization. -On startup blender scans the ``scripts/startup/`` directory for python modules and imports them. The exact location of this directory depends on your installation. `See the directory layout docs <http://wiki.blender.org/index.php/Doc:2.6/Manual/Introduction/Installing_Blender/DirectoryLayout>`_ +On startup Blender scans the ``scripts/startup/`` directory for Python modules and imports them. +The exact location of this directory depends on your installation. +`See the directory layout docs +<https://www.blender.org/manual/getting_started/installing_blender/directorylayout.html>`__ Script Loading ============== -This may seem obvious but it's important to note the difference between executing a script directly or importing it as a module. - -Scripts that extend blender - define classes that exist beyond the scripts execution, this makes future access to these classes (to unregister for example) more difficult than importing as a module where class instance is kept in the module and can be accessed by importing that module later on. +This may seem obvious but it's important to note the difference +between executing a script directly or importing it as a module. -For this reason it's preferable to only use directly execute scripts that don't extend blender by registering classes. +Scripts that extend Blender - define classes that exist beyond the scripts execution, +this makes future access to these classes (to unregister for example) +more difficult than importing as a module where class instance is kept +in the module and can be accessed by importing that module later on. +For this reason it's preferable to only use directly execute scripts that don't extend Blender by registering classes. -Here are some ways to run scripts directly in blender. -* Loaded in the text editor and press **Run Script**. +Here are some ways to run scripts directly in Blender. -* Typed or pasted into the interactive console. +- Loaded in the text editor and press **Run Script**. +- Typed or pasted into the interactive console. +- Execute a Python file from the command line with Blender, eg: -* Execute a python file from the command line with blender, eg: + .. code-block:: sh - ``blender --python /home/me/my_script.py`` + blender --python /home/me/my_script.py To run as modules: -* The obvious way, ``import some_module`` command from the text window or interactive console. - -* Open as a text block and tick "Register" option, this will load with the blend file. - -* copy into one of the directories ``scripts/startup``, where they will be automatically imported on startup. - -* define as an addon, enabling the addon will load it as a python module. +- The obvious way, ``import some_module`` command from the text window or interactive console. +- Open as a text block and tick "Register" option, this will load with the blend file. +- copy into one of the directories ``scripts/startup``, where they will be automatically imported on startup. +- define as an addon, enabling the addon will load it as a Python module. Addons ------ -Some of blenders functionality is best kept optional, alongside scripts loaded at startup we have addons which are kept in their own directory ``scripts/addons``, and only load on startup if selected from the user preferences. +Some of Blenders functionality is best kept optional, +alongside scripts loaded at startup we have addons which are kept in their own directory ``scripts/addons``, +and only load on startup if selected from the user preferences. -The only difference between addons and built-in python modules is that addons must contain a **bl_info** variable which blender uses to read metadata such as name, author, category and URL. +The only difference between addons and built-in Python modules is that addons must contain a ``bl_info`` +variable which Blender uses to read metadata such as name, author, category and URL. The user preferences addon listing uses **bl_info** to display information about each addon. -`See Addons <http://wiki.blender.org/index.php/Dev:2.5/Py/Scripts/Guidelines/Addons>`_ for details on the **bl_info** dictionary. +`See Addons <http://wiki.blender.org/index.php/Dev:2.5/Py/Scripts/Guidelines/Addons>`__ +for details on the ``bl_info`` dictionary. Integration through Classes =========================== -Running python scripts in the text editor is useful for testing but you’ll want to extend blender to make tools accessible like other built-in functionality. - -The blender python api allows integration for: +Running Python scripts in the text editor is useful for testing but you'll +want to extend Blender to make tools accessible like other built-in functionality. -* :class:`bpy.types.Panel` +The Blender Python api allows integration for: -* :class:`bpy.types.Menu` +- :class:`bpy.types.Panel` +- :class:`bpy.types.Menu` +- :class:`bpy.types.Operator` +- :class:`bpy.types.PropertyGroup` +- :class:`bpy.types.KeyingSet` +- :class:`bpy.types.RenderEngine` -* :class:`bpy.types.Operator` -* :class:`bpy.types.PropertyGroup` +This is intentionally limited. Currently, for more advanced features such as mesh modifiers, +object types, or shader nodes, C/C++ must be used. -* :class:`bpy.types.KeyingSet` - -* :class:`bpy.types.RenderEngine` - - -This is intentionally limited. Currently, for more advanced features such as mesh modifiers, object types, or shader nodes, C/C++ must be used. - -For python intergration Blender defines methods which are common to all types. This works by creating a python subclass of a Blender class which contains variables and functions specified by the parent class which are pre-defined to interface with Blender. +For Python integration Blender defines methods which are common to all types. +This works by creating a Python subclass of a Blender class which contains variables and functions +specified by the parent class which are pre-defined to interface with Blender. For example: @@ -115,15 +134,20 @@ For example: bpy.utils.register_class(SimpleOperator) -First note that we subclass a member of :mod:`bpy.types`, this is common for all classes which can be integrated with blender and used so we know if this is an Operator and not a Panel when registering. +First note that we subclass a member of :mod:`bpy.types`, +this is common for all classes which can be integrated with Blender and +used so we know if this is an Operator and not a Panel when registering. -Both class properties start with a **bl_** prefix. This is a convention used to distinguish blender properties from those you add yourself. +Both class properties start with a ``bl_`` prefix. +This is a convention used to distinguish Blender properties from those you add yourself. -Next see the execute function, which takes an instance of the operator and the current context. A common prefix is not used for functions. +Next see the execute function, which takes an instance of the operator and the current context. +A common prefix is not used for functions. -Lastly the register function is called, this takes the class and loads it into blender. See `Class Registration`_. +Lastly the register function is called, this takes the class and loads it into Blender. See `Class Registration`_. -Regarding inheritance, blender doesn't impose restrictions on the kinds of class inheritance used, the registration checks will use attributes and functions defined in parent classes. +Regarding inheritance, Blender doesn't impose restrictions on the kinds of class inheritance used, +the registration checks will use attributes and functions defined in parent classes. class mix-in example: @@ -141,11 +165,20 @@ class mix-in example: bpy.utils.register_class(SimpleOperator) -Notice these classes don't define an ``__init__(self)`` function. While ``__init__()`` and ``__del__()`` will be called if defined, the class instances lifetime only spans the execution. So a panel for example will have a new instance for every redraw, for this reason there is rarely a cause to store variables in the panel instance. Instead, persistent variables should be stored in Blenders data so that the state can be restored when blender is restarted. +Notice these classes don't define an ``__init__(self)`` function. +While ``__init__()`` and ``__del__()`` will be called if defined, +the class instances lifetime only spans the execution. +So a panel for example will have a new instance for every redraw, +for this reason there is rarely a cause to store variables in the panel instance. +Instead, persistent variables should be stored in Blenders +ata so that the state can be restored when Blender is restarted. + +.. note:: -.. note:: Modal operators are an exception, keeping their instance variable as blender runs, see modal operator template. + Modal operators are an exception, keeping their instance variable as Blender runs, see modal operator template. -So once the class is registered with blender, instancing the class and calling the functions is left up to blender. In fact you cannot instance these classes from the script as you would expect with most python API's. +So once the class is registered with Blender, instancing the class and calling the functions is left up to Blender. +In fact you cannot instance these classes from the script as you would expect with most Python API's. To run operators you can call them through the operator api, eg: @@ -154,7 +187,8 @@ To run operators you can call them through the operator api, eg: import bpy bpy.ops.object.simple_operator() -User interface classes are given a context in which to draw, buttons window, file header, toolbar etc, then they are drawn when that area is displayed so they are never called by python scripts directly. +User interface classes are given a context in which to draw, buttons window, file header, toolbar etc, +then they are drawn when that area is displayed so they are never called by Python scripts directly. Registration @@ -164,9 +198,10 @@ Registration Module Registration ------------------- -Blender modules loaded at startup require ``register()`` and ``unregister()`` functions. These are the *only* functions that blender calls from your code, which is otherwise a regular python module. +Blender modules loaded at startup require ``register()`` and ``unregister()`` functions. +These are the *only* functions that Blender calls from your code, which is otherwise a regular Python module. -A simple blender/python module can look like this: +A simple Blender/Python module can look like this: .. code-block:: python @@ -184,12 +219,16 @@ A simple blender/python module can look like this: if __name__ == "__main__": register() -These functions usually appear at the bottom of the script containing class registration sometimes adding menu items. You can also use them for internal purposes setting up data for your own tools but take care since register won't re-run when a new blend file is loaded. +These functions usually appear at the bottom of the script containing class registration sometimes adding menu items. +You can also use them for internal purposes setting up data for your own tools but take care +since register won't re-run when a new blend file is loaded. -The register/unregister calls are used so it's possible to toggle addons and reload scripts while blender runs. -If the register calls were placed in the body of the script, registration would be called on import, meaning there would be no distinction between importing a module or loading its classes into blender. +The register/unregister calls are used so it's possible to toggle addons and reload scripts while Blender runs. +If the register calls were placed in the body of the script, registration would be called on import, +meaning there would be no distinction between importing a module or loading its classes into Blender. -This becomes problematic when a script imports classes from another module making it difficult to manage which classes are being loaded and when. +This becomes problematic when a script imports classes from another module +making it difficult to manage which classes are being loaded and when. The last 2 lines are only for testing: @@ -199,19 +238,24 @@ The last 2 lines are only for testing: register() This allows the script to be run directly in the text editor to test changes. -This ``register()`` call won't run when the script is imported as a module since ``__main__`` is reserved for direct execution. +This ``register()`` call won't run when the script is imported as a module +since ``__main__`` is reserved for direct execution. Class Registration ------------------ -Registering a class with blender results in the class definition being loaded into blender, where it becomes available alongside existing functionality. +Registering a class with Blender results in the class definition being loaded into Blender, +where it becomes available alongside existing functionality. -Once this class is loaded you can access it from :mod:`bpy.types`, using the bl_idname rather than the classes original name. +Once this class is loaded you can access it from :mod:`bpy.types`, +using the bl_idname rather than the classes original name. -When loading a class, blender performs sanity checks making sure all required properties and functions are found, that properties have the correct type, and that functions have the right number of arguments. +When loading a class, Blender performs sanity checks making sure all required properties and functions are found, +that properties have the correct type, and that functions have the right number of arguments. -Mostly you will not need concern yourself with this but if there is a problem with the class definition it will be raised on registering: +Mostly you will not need concern yourself with this but if there is a problem +with the class definition it will be raised on registering: Using the function arguments ``def execute(self, context, spam)``, will raise an exception: @@ -225,9 +269,13 @@ Using ``bl_idname = 1`` will raise. Multiple-Classes ^^^^^^^^^^^^^^^^ -Loading classes into blender is described above, for simple cases calling :mod:`bpy.utils.register_class` (SomeClass) is sufficient, but when there are many classes or a packages submodule has its own classes it can be tedious to list them all for registration. +Loading classes into Blender is described above, +for simple cases calling :mod:`bpy.utils.register_class` (SomeClass) is sufficient, +but when there are many classes or a packages submodule has its own +classes it can be tedious to list them all for registration. -For more convenient loading/unloading :mod:`bpy.utils.register_module` (module) and :mod:`bpy.utils.unregister_module` (module) functions exist. +For more convenient loading/unloading :mod:`bpy.utils.register_module` (module) +and :mod:`bpy.utils.unregister_module` (module) functions exist. A script which defines many of its own operators, panels menus etc. you only need to write: @@ -239,13 +287,19 @@ A script which defines many of its own operators, panels menus etc. you only nee def unregister(): bpy.utils.unregister_module(__name__) -Internally blender collects subclasses on registrable types, storing them by the module in which they are defined. By passing the module name to :mod:`bpy.utils.register_module` blender can register all classes created by this module and its submodules. +Internally Blender collects subclasses on registrable types, storing them by the module in which they are defined. +By passing the module name to :mod:`bpy.utils.register_module` +Blender can register all classes created by this module and its submodules. Inter Classes Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^ -When customizing blender you may want to group your own settings together, after all, they will likely have to co-exist with other scripts. To group these properties classes need to be defined, for groups within groups or collections within groups you can find yourself having to deal with order of registration/unregistration. +When customizing Blender you may want to group your own settings together, +after all, they will likely have to co-exist with other scripts. +To group these properties classes need to be defined, +for groups within groups or collections within groups +you can find yourself having to deal with order of registration/unregistration. Custom properties groups are themselves classes which need to be registered. @@ -311,7 +365,9 @@ Say you want to store material settings for a custom engine. Manipulating Classes ^^^^^^^^^^^^^^^^^^^^ -Properties can be added and removed as blender runs, normally happens on register or unregister but for some special cases it may be useful to modify types as the script runs. +Properties can be added and removed as Blender runs, +normally happens on register or unregister but for some +special cases it may be useful to modify types as the script runs. For example: @@ -341,7 +397,8 @@ This works just as well for PropertyGroup subclasses you define yourself. Dynamic Defined-Classes (Advanced) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In some cases the specifier for data may not be in blender, renderman shader definitions for example and it may be useful to define types and remove them on the fly. +In some cases the specifier for data may not be in Blender, +renderman shader definitions for example and it may be useful to define types and remove them on the fly. .. code-block:: python @@ -360,7 +417,8 @@ In some cases the specifier for data may not be in blender, renderman shader def .. note:: - Notice ``type()`` is called to define the class. This is an alternative syntax for class creation in python, better suited to constructing classes dynamically. + ``type()`` is called to define the class. + This is an alternative syntax for class creation in Python, better suited to constructing classes dynamically. Calling these operators: diff --git a/doc/python_api/rst/info_quickstart.rst b/doc/python_api/rst/info_quickstart.rst index a1052bf4208..ab106dd3bb7 100644 --- a/doc/python_api/rst/info_quickstart.rst +++ b/doc/python_api/rst/info_quickstart.rst @@ -1,3 +1,4 @@ + .. _info_quickstart: *********************** @@ -11,67 +12,61 @@ This API is generally stable but some areas are still being added and improved. The Blender/Python API can do the following: -* Edit any data the user interface can (Scenes, Meshes, Particles etc.) - -* Modify user preferences, keymaps and themes - -* Run tools with own settings - -* Create user interface elements such as menus, headers and panels - -* Create new tools - -* Create interactive tools - -* Create new rendering engines that integrate with Blender - -* Define new settings in existing Blender data - -* Draw in the 3D view using OpenGL commands from Python +- Edit any data the user interface can (Scenes, Meshes, Particles etc.) +- Modify user preferences, keymaps and themes +- Run tools with own settings +- Create user interface elements such as menus, headers and panels +- Create new tools +- Create interactive tools +- Create new rendering engines that integrate with Blender +- Define new settings in existing Blender data +- Draw in the 3D view using OpenGL commands from Python The Blender/Python API **can't** (yet)... -* Create new space types. - -* Assign custom properties to every type. - -* Define callbacks or listeners to be notified when data is changed. +- Create new space types. +- Assign custom properties to every type. +- Define callbacks or listeners to be notified when data is changed. Before Starting =============== -This document isn't intended to fully cover each topic. Rather, its purpose is to familiarize you with Blender Python API. +This document isn't intended to fully cover each topic. +Rather, its purpose is to familiarize you with Blender Python API. A quick list of helpful things to know before starting: -* Blender uses Python 3.x; some 3rd party extensions are not available yet. - -* The interactive console is great for testing one-liners, It also has autocompletion so you can inspect the api quickly. - -* Button tool tips show Python attributes and operator names. - -* Right clicking on buttons and menu items directly links to API documentation. - -* For more examples, the text menu has a templates section where some example operators can be found. +- Blender uses Python 3.x; some online documentation still assumes 2.x. +- The interactive console is great for testing one-liners. + It also has autocompletion so you can inspect the API quickly. +- Button tool tips show Python attributes and operator names. +- Right clicking on buttons and menu items directly links to API documentation. +- For more examples, the text menu has a templates section where some example operators can be found. +- To examine further scripts distributed with Blender, see: -* To examine further scripts distributed with Blender, see ``~/.blender/scripts/startup/bl_ui`` for the user interface and ``~/.blender/scripts/startup/bl_op`` for operators. + | ``~/.blender/scripts/startup/bl_ui`` for the user interface, + | ``~/.blender/scripts/startup/bl_op`` for operators. Running Scripts --------------- -The two most common ways to execute python scripts are using the built-in text editor or entering commands in the python console. +The two most common ways to execute Python scripts are using the built-in +text editor or entering commands in the Python console. -Both the **Text Editor** and **Python Console** are space types you can select from the view header. +Both the *Text Editor* and *Python Console* are space types you can select from the view header. -Rather then manually configuring your spaces for Python development, you may prefer to use the **Scripting** screen, included default with Blender, accessible from the top headers screen selector. +Rather than manually configuring your spaces for Python development, +you may prefer to use the *Scripting* screen, included default with Blender, +accessible from the top headers screen selector. -From the text editor you can open ``.py`` files or paste then from the clipboard, then test using **Run Script**. +From the text editor you can open ``.py`` files or paste then from the clipboard, then test using *Run Script*. -The Python Console is typically used for typing in snippets and for testing to get immediate feedback, but can also have entire scripts pasted into it. +The Python Console is typically used for typing in snippets and for testing to get immediate feedback, +but can also have entire scripts pasted into it. Scripts can also run from the command line with Blender but to learn Blender/Python this isn't essential. @@ -82,12 +77,14 @@ Key Concepts Data Access ----------- -Accessing datablocks +Accessing DataBlocks ^^^^^^^^^^^^^^^^^^^^ -Python accesses Blender's data in the same way as the animation system and user interface; this implies that any setting that can be changed via a button can also be changed from Python. +Python accesses Blender's data in the same way as the animation system and user interface; +this implies that any setting that can be changed via a button can also be changed from Python. -Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`. This gives access to library data. For example: +Accessing data from the currently loaded blend file is done with the module :mod:`bpy.data`. +This gives access to library data. For example: >>> bpy.data.objects <bpy_collection[3], BlendDataObjects> @@ -104,7 +101,8 @@ About Collections You'll notice that an index as well as a string can be used to access members of the collection. -Unlike Python's dictionaries, both methods are acceptable; however, the index of a member may change while running Blender. +Unlike Python's dictionaries, both methods are acceptable; +however, the index of a member may change while running Blender. >>> list(bpy.data.objects) [bpy.data.objects["Cube"], bpy.data.objects["Plane"]] @@ -116,10 +114,13 @@ Unlike Python's dictionaries, both methods are acceptable; however, the index of bpy.data.objects["Cube"] -Accessing attributes +Accessing Attributes ^^^^^^^^^^^^^^^^^^^^ -Once you have a data block, such as a material, object, groups etc., its attributes can be accessed much like you would change a setting using the graphical interface. In fact, the tooltip for each button also displays the Python attribute which can help in finding what settings to change in a script. +Once you have a data block, such as a material, object, groups etc., +its attributes can be accessed much like you would change a setting using the graphical interface. +In fact, the tooltip for each button also displays the Python attribute +which can help in finding what settings to change in a script. >>> bpy.data.objects[0].name 'Camera' @@ -131,7 +132,8 @@ Once you have a data block, such as a material, object, groups etc., its attribu bpy.data.materials['MyMaterial'] -For testing what data to access it's useful to use the "Console", which is its own space type. This supports auto-complete, giving you a fast way to dig into different data in your file. +For testing what data to access it's useful to use the "Console", which is its own space type. +This supports auto-complete, giving you a fast way to dig into different data in your file. Example of a data path that can be quickly found via the console: @@ -144,7 +146,8 @@ Example of a data path that can be quickly found via the console: Data Creation/Removal ^^^^^^^^^^^^^^^^^^^^^ -Those of you familiar with other python api's may be surprised that new datablocks in the bpy api can't be created by calling the class: +Those of you familiar with other Python API's may be surprised that +new datablocks in the bpy API can't be created by calling the class: >>> bpy.types.Mesh() Traceback (most recent call last): @@ -153,9 +156,10 @@ Those of you familiar with other python api's may be surprised that new databloc This is an intentional part of the API design. -The blender/python api can't create blender data that exists outside the main blender database (accessed through bpy.data), because this data is managed by blender (save/load/undo/append... etc). +The Blender/Python API can't create Blender data that exists outside the main Blender database +(accessed through :mod:`bpy.data`), because this data is managed by Blender (save/load/undo/append... etc). -Data is added and removed via methods on the collections in bpy.data, eg: +Data is added and removed via methods on the collections in :mod:`bpy.data`, eg: >>> mesh = bpy.data.meshes.new(name="MyMesh") >>> print(mesh) @@ -167,7 +171,10 @@ Data is added and removed via methods on the collections in bpy.data, eg: Custom Properties ^^^^^^^^^^^^^^^^^ -Python can access properties on any datablock that has an ID (data that can be linked in and accessed from :mod:`bpy.data`. When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist. +Python can access properties on any datablock that has an ID +(data that can be linked in and accessed from :mod:`bpy.data`. +When assigning a property, you can make up your own names, +these will be created when needed or overwritten if they exist. This data is saved with the blend file and copied with objects. @@ -180,7 +187,7 @@ Example: if "SomeProp" in bpy.context.object: print("Property found") - # Use the get function like a python dictionary + # Use the get function like a Python dictionary # which can have a fallback value. value = bpy.data.scenes["Scene"].get("test_prop", "fallback value") @@ -193,11 +200,9 @@ Example: Note that these properties can only be assigned basic Python types. -* int, float, string - -* array of ints/floats - -* dictionary (only string keys are supported, values must be basic types too) +- int, float, string +- array of ints/floats +- dictionary (only string keys are supported, values must be basic types too) These properties are valid outside of Python. They can be animated by curves or used in driver paths. @@ -205,7 +210,10 @@ These properties are valid outside of Python. They can be animated by curves or Context ------- -While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection. The context is always available from '''bpy.context''' and can be used to get the active object, scene, tool settings along with many other attributes. +While it's useful to be able to access data directly by name or as a list, +it's more common to operate on the user's selection. +The context is always available from ``bpy.context`` and can be used to get the active object, scene, +tool settings along with many other attributes. Common-use cases: @@ -213,22 +221,28 @@ Common-use cases: >>> bpy.context.selected_objects >>> bpy.context.visible_bones -Note that the context is read-only. These values cannot be modified directly, though they may be changed by running API functions or by using the data API. +Note that the context is read-only. +These values cannot be modified directly, +though they may be changed by running API functions or by using the data API. So ``bpy.context.object = obj`` will raise an error. But ``bpy.context.scene.objects.active = obj`` will work as expected. -The context attributes change depending on where they are accessed. The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known. +The context attributes change depending on where they are accessed. +The 3D view has different context members than the console, +so take care when accessing context attributes that the user state is known. -See :mod:`bpy.context` API reference +See :mod:`bpy.context` API reference. Operators (Tools) ----------------- -Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspective they are a tool but Python can run these with its own settings through the :mod:`bpy.ops` module. +Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. +From the user perspective they are a tool but Python can run these with its own settings +through the :mod:`bpy.ops` module. Examples: @@ -241,16 +255,19 @@ Examples: .. note:: - The menu item: Help -> Operator Cheat Sheet" gives a list of all operators and their default values in Python syntax, along with the generated docs. This is a good way to get an overview of all blender's operators. + The menu item: :menuselection:`Help --> Operator Cheat Sheet` + gives a list of all operators and their default values in Python syntax, along with the generated docs. + This is a good way to get an overview of all Blender's operators. Operator Poll() ^^^^^^^^^^^^^^^ -Many operators have a "poll" function which may check that the mouse is in a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc). -When an operator's poll function fails within python, an exception is raised. +Many operators have a "poll" function which may check that the cursor +is in a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc). +When an operator's poll function fails within Python, an exception is raised. -For example, calling bpy.ops.view3d.render_border() from the console raises the following error: +For example, calling ``bpy.ops.view3d.render_border()`` from the console raises the following error: .. code-block:: python @@ -258,7 +275,8 @@ For example, calling bpy.ops.view3d.render_border() from the console raises the In this case the context must be the 3d view with an active camera. -To avoid using try/except clauses wherever operators are called you can call the operators own .poll() function to check if it can run in the current context. +To avoid using try/except clauses wherever operators are called you can call the operators +own ``poll()`` function to check if it can run in the current context. .. code-block:: python @@ -271,13 +289,10 @@ Integration Python scripts can integrate with Blender in the following ways: -* By defining a rendering engine. - -* By defining operators. - -* By defining menus, headers and panels. - -* By inserting new buttons into existing menus, headers and panels +- By defining a rendering engine. +- By defining operators. +- By defining menus, headers and panels. +- By inserting new buttons into existing menus, headers and panels In Python, this is done by defining a class, which is a subclass of an existing type. @@ -288,62 +303,52 @@ Example Operator .. literalinclude:: ../../../release/scripts/templates_py/operator_simple.py -Once this script runs, ``SimpleOperator`` is registered with Blender and can be called from the operator search popup or added to the toolbar. +Once this script runs, ``SimpleOperator`` is registered with Blender +and can be called from the operator search popup or added to the toolbar. To run the script: -#. Highlight the above code then press Ctrl+C to copy it. - +#. Highlight the above code then press :kbd:`Ctrl-C` to copy it. #. Start Blender - -#. Press Ctrl+Right twice to change to the Scripting layout. - +#. Press :kbd:`Ctrl-Right` twice to change to the Scripting layout. #. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block. - -#. Press Ctrl+V to paste the code into the text panel (the upper left frame). - +#. Press :kbd:`Ctrl-V` to paste the code into the text panel (the upper left frame). #. Click on the button **Run Script**. - -#. Move your mouse into the 3D view, press spacebar for the operator search menu, and type "Simple". - +#. Move your cursor into the 3D view, press spacebar for the operator search menu, and type "Simple". #. Click on the "Simple Operator" item found in search. -.. seealso:: The class members with the **bl_** prefix are documented in the API +.. seealso:: The class members with the ``bl_`` prefix are documented in the API reference :class:`bpy.types.Operator` -.. note:: The output from the ``main`` function is sent to the terminal; in order to see this, be sure to :ref:`use the terminal <use_the_terminal>`. +.. note:: + + The output from the ``main`` function is sent to the terminal; + in order to see this, be sure to :ref:`use the terminal <use_the_terminal>`. Example Panel ------------- -Panels register themselves as a class, like an operator. Notice the extra **bl_** variables used to set the context they display in. +Panels register themselves as a class, like an operator. +Notice the extra ``bl_`` variables used to set the context they display in. .. literalinclude:: ../../../release/scripts/templates_py/ui_panel_simple.py To run the script: -#. Highlight the above code then press Ctrl+C to copy it - +#. Highlight the above code then press :kbd:`Ctrl-C` to copy it #. Start Blender - -#. Press Ctrl+Right twice to change to the Scripting layout - +#. Press :kbd:`Ctrl-Right` twice to change to the Scripting layout #. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block. - -#. Press Ctrl+V to paste the code into the text panel (the upper left frame) - +#. Press :kbd:`Ctrl-V` to paste the code into the text panel (the upper left frame) #. Click on the button **Run Script**. To view the results: #. Select the the default cube. - #. Click on the Object properties icon in the buttons panel (far right; appears as a tiny cube). - #. Scroll down to see a panel named **Hello World Panel**. - #. Changing the object name also updates **Hello World Panel's** Name: field. Note the row distribution and the label and properties that are available through the code. @@ -362,16 +367,15 @@ Blender's Python API can be split up into 3 categories. Native Types ------------ -In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal python types. +In simple cases returning a number or a string as a custom type would be cumbersome, +so these are accessed as normal Python types. -* blender float/int/boolean -> float/int/boolean - -* blender enumerator -> string +- Blender float/int/boolean -> float/int/boolean +- Blender enumerator -> string >>> C.object.rotation_mode = 'AXIS_ANGLE' - -* blender enumerator (multiple) -> set of strings +- Blender enumerator (multiple) -> set of strings .. code-block:: python @@ -389,7 +393,8 @@ Used for Blender datablocks and collections: :class:`bpy.types.bpy_struct` For data that contains its own attributes groups/meshes/bones/scenes... etc. -There are 2 main types that wrap Blenders data, one for datablocks (known internally as bpy_struct), another for properties. +There are 2 main types that wrap Blenders data, one for datablocks +(known internally as ``bpy_struct``), another for properties. >>> bpy.context.object bpy.data.objects['Cube'] @@ -405,7 +410,9 @@ Mathutils Types Used for vectors, quaternion, eulers, matrix and color types, accessible from :mod:`mathutils` -Some attributes such as :class:`bpy.types.Object.location`, :class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location` can be accessed as special math types which can be used together and manipulated in various useful ways. +Some attributes such as :class:`bpy.types.Object.location`, +:class:`bpy.types.PoseBone.rotation_euler` and :class:`bpy.types.Scene.cursor_location` +can be accessed as special math types which can be used together and manipulated in various useful ways. Example of a matrix, vector multiplication: @@ -440,7 +447,9 @@ Animation There are 2 ways to add keyframes through Python. -The first is through key properties directly, which is similar to inserting a keyframe from the button as a user. You can also manually create the curves and keyframe data, then set the path to the property. Here are examples of both methods. +The first is through key properties directly, which is similar to inserting a keyframe from the button as a user. +You can also manually create the curves and keyframe data, then set the path to the property. +Here are examples of both methods. Both examples insert a keyframe on the active object's Z axis. diff --git a/doc/python_api/rst/info_tips_and_tricks.rst b/doc/python_api/rst/info_tips_and_tricks.rst index e345f36a148..28d129b5b13 100644 --- a/doc/python_api/rst/info_tips_and_tricks.rst +++ b/doc/python_api/rst/info_tips_and_tricks.rst @@ -1,10 +1,12 @@ + *************** Tips and Tricks *************** Here are various suggestions that you might find useful when writing scripts. -Some of these are just python features that scripters may not have thought to use with blender, others are blender specific. +Some of these are just Python features that scripters may not have thought to use with Blender, +others are Blender specific. .. _use_the_terminal: @@ -12,18 +14,21 @@ Some of these are just python features that scripters may not have thought to us Use The Terminal ================ -When writing python scripts, it's useful to have a terminal open, this is not the built-in python console but a terminal application which is used to start blender. +When writing Python scripts, it's useful to have a terminal open, +this is not the built-in Python console but a terminal application which is used to start Blender. There are 3 main uses for the terminal, these are: -* You can see the output of ``print()`` as your script runs, which is useful to view debug info. - -* The error trace-back is printed in full to the terminal which won't always generate an error popup in blender's user interface (depending on how the script is executed). - -* If the script runs for too long or you accidentally enter an infinite loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early. +- You can see the output of ``print()`` as your script runs, which is useful to view debug info. +- The error trace-back is printed in full to the terminal which won't always generate an error popup in + Blender's user interface (depending on how the script is executed). +- If the script runs for too long or you accidentally enter an infinite loop, + :kbd:`Ctrl-C` in the terminal (:kbd:`Ctrl-Break` on Windows) will quit the script early. .. note:: - For Linux and OSX users this means starting the terminal first, then running blender from within it. On Windows the terminal can be enabled from the help menu. + + For Linux and OSX users this means starting the terminal first, then running Blender from within it. + On Windows the terminal can be enabled from the help menu. Interface Tricks @@ -33,43 +38,56 @@ Interface Tricks Access Operator Commands ------------------------ -You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops``... command to run that button, a handy (hidden) feature is that you can press Ctrl+C over any menu item/button to copy this command into the clipboard. +You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...])`` command +to run that button, a handy (hidden) feature is that you can press :kbd:`Ctrl-C` over +any menu item/button to copy this command into the clipboard. Access Data Path ---------------- -To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away. To get this quickly you can right click on the setting and select select **Copy Data Path**, +To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away. +To get this quickly you can right click on the setting and select select **Copy Data Path**, if this can't be generated, only the property name is copied. .. note:: - This uses the same method for creating the animation path used by :class:`bpy.types.FCurve.data_path` and :class:`bpy.types.DriverTarget.data_path` drivers. + This uses the same method for creating the animation path used by + :class:`bpy.types.FCurve.data_path` and + :class:`bpy.types.DriverTarget.data_path` drivers. -.. _info_show_all_operators +.. _info_show_all_operators: Show All Operators ================== -While blender logs operators in the Info space, this only reports operators with the ``REGISTER`` option enabeld so as not to flood the Info view with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``. +While Blender logs operators in the Info space, +this only reports operators with the ``REGISTER`` option enabeld so as not to flood the *Info* view +with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``. -However, for testing it can be useful to see **every** operator called in a terminal, do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting blender or by setting :mod:`bpy.app.debug_wm` to True while blender is running. +However, for testing it can be useful to see **every** operator called in a terminal, +do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting Blender +or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running. Use an External Editor ====================== -Blenders text editor is fine for small changes and writing tests but its not full featured, for larger projects you'll probably want to use a standalone editor or python IDE. +Blenders text editor is fine for small changes and writing tests but its not full featured, +for larger projects you'll probably want to use a standalone editor or Python IDE. -Editing a text file externally and having the same text open in blender does work but isn't that optimal so here are 2 ways you can easily use an external file from blender. +Editing a text file externally and having the same text open in Blender does work but isn't that optimal +so here are 2 ways you can easily use an external file from Blender. + +Using the following examples you'll still need textblock in Blender to execute, +but reference an external file rather than including it directly. -Using the following examples you'll still need textblock in blender to execute, but reference an external file rather then including it directly. Executing External Scripts -------------------------- -This is the equivalent to running the script directly, referencing a scripts path from a 2 line textblock. +This is the equivalent to running the script directly, referencing a scripts path from a 2 line text-block. .. code-block:: python @@ -102,12 +120,17 @@ This example shows loading a script in as a module and executing a module functi myscript.main() -Notice that the script is reloaded every time, this forces use of the modified version, otherwise the cached one in ``sys.modules`` would be used until blender was restarted. +Notice that the script is reloaded every time, this forces use of the modified version, +otherwise the cached one in ``sys.modules`` would be used until Blender was restarted. -The important difference between this and executing the script directly is it has to call a function in the module, in this case ``main()`` but it can be any function, an advantage with this is you can pass arguments to the function from this small script which is often useful for testing different settings quickly. +The important difference between this and executing the script directly is it +has to call a function in the module, in this case ``main()`` but it can be any function, +an advantage with this is you can pass arguments to the function from this +small script which is often useful for testing different settings quickly. -The other issue with this is the script has to be in pythons module search path. -While this is not best practice - for testing you can extend the search path, this example adds the current blend files directory to the search path, then loads the script as a module. +The other issue with this is the script has to be in Pythons module search path. +While this is not best practice - for testing you can extend the search path, +this example adds the current blend files directory to the search path, then loads the script as a module. .. code-block:: python @@ -128,71 +151,86 @@ While this is not best practice - for testing you can extend the search path, th Don't Use Blender! ================== -While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc. adds overhead. +While developing your own scripts Blenders interface can get in the way, +manually reloading, running the scripts, opening file import etc. adds overhead. -For scripts that are not interactive it can end up being more efficient not to use blenders interface at all and instead execute the script on the command line. +For scripts that are not interactive it can end up being more efficient not to use +Blenders interface at all and instead execute the script on the command line. -.. code-block:: python +.. code-block:: sh blender --background --python myscript.py You might want to run this with a blend file so the script has some data to operate on. -.. code-block:: python +.. code-block:: sh blender myscene.blend --background --python myscript.py .. note:: - Depending on your setup you might have to enter the full path to the blender executable. - + Depending on your setup you might have to enter the full path to the Blender executable. -Once the script is running properly in background mode, you'll want to check the output of the script, this depends completely on the task at hand however here are some suggestions. -* render the output to an image, use an image viewer and keep writing over the same image each time. +Once the script is running properly in background mode, you'll want to check the output of the script, +this depends completely on the task at hand however here are some suggestions. -* save a new blend file, or export the file using one of blenders exporters. +- render the output to an image, use an image viewer and keep writing over the same image each time. +- save a new blend file, or export the file using one of Blenders exporters. +- if the results can be displayed as text - print them or write them to a file. -* if the results can be displayed as text - print them or write them to a file. - -This can take a little time to setup, but it can be well worth the effort to reduce the time it takes to test changes - you can even have blender running the script ever few seconds with a viewer updating the results, so no need to leave your text editor to see changes. +While this can take a little time to setup, it can be well worth the effort +to reduce the time it takes to test changes - you can even have +Blender running the script every few seconds with a viewer updating the results, +so no need to leave your text editor to see changes. Use External Tools ================== -When there are no readily available python modules to perform specific tasks it's worth keeping in mind you may be able to have python execute an external command on your data and read the result back in. +When there are no readily available Python modules to perform specific tasks it's +worth keeping in mind you may be able to have Python execute an external command +on your data and read the result back in. -Using external programs adds an extra dependency and may limit who can use the script but to quickly setup your own custom pipeline or writing one-off scripts this can be handy. +Using external programs adds an extra dependency and may limit who can use the script +but to quickly setup your own custom pipeline or writing one-off scripts this can be handy. Examples include: -* Run The Gimp in batch mode to execute custom scripts for advanced image processing. - -* Write out 3D models to use external mesh manipulation tools and read back in the results. - -* Convert files into recognizable formats before reading. +- Run The Gimp in batch mode to execute custom scripts for advanced image processing. +- Write out 3D models to use external mesh manipulation tools and read back in the results. +- Convert files into recognizable formats before reading. Bundled Python & Extensions =========================== -The Blender releases distributed from blender.org include a complete python installation on all platforms, this has the disadvantage that any extensions you have installed in your systems python wont be found by blender. +The Blender releases distributed from blender.org include a complete Python installation on all platforms, +this has the disadvantage that any extensions you have installed in your systems Python wont be found by Blender. There are 2 ways around this: -* remove blender python sub-directory, blender will then fallback on the systems python and use that instead **python version must match the one that blender comes with**. +- remove Blender Python sub-directory, Blender will then fallback on the systems Python and use that instead + .. warning:: + + The Python version must match the one that Blender comes with. -* copy the extensions into blender's python sub-directory so blender can access them, you could also copy the entire python installation into blenders sub-directory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same relative locations. Doing this has the advantage that you can redistribute this bundle to others with blender and/or the game player, including any extensions you rely on. +- copy the extensions into Blender's Python sub-directory so Blender can access them, + you could also copy the entire Python installation into Blenders sub-directory, + replacing the one Blender comes with. + This works as long as the Python versions match and the paths are created in the same relative locations. + Doing this has the advantage that you can redistribute this bundle to others with Blender and/or the game player, + including any extensions you rely on. Drop Into a Python Interpreter in Your Script ============================================= -In the middle of a script you may want to inspect some variables, run some function and generally dig about to see whats going on. +In the middle of a script you may want to inspect some variables, +run some function and generally dig about to see whats going on. .. code-block:: python @@ -217,10 +255,13 @@ The next example is an equivalent single line version of the script above which __import__('code').interact(local=dict(globals(), **locals())) -``code.interact`` can be added at any line in the script and will pause the script an launch an interactive interpreter in the terminal, when you're done you can quit the interpreter and the script will continue execution. +``code.interact`` can be added at any line in the script +and will pause the script an launch an interactive interpreter in the terminal, +when you're done you can quit the interpreter and the script will continue execution. -If you have **IPython** installed you can use their ``embed()`` function which will implicitly use the current namespace, this has autocomplete and some useful features that the standard python eval-loop doesn't have. +If you have **IPython** installed you can use its ``embed()`` function which uses the current namespace. +The IPython prompt has auto-complete and some useful features that the standard Python eval-loop doesn't have. .. code-block:: python @@ -228,7 +269,7 @@ If you have **IPython** installed you can use their ``embed()`` function which w IPython.embed() -Admittedly this highlights the lack of any python debugging support built into blender, but its still handy to know. +Admittedly this highlights the lack of any Python debugging support built into Blender, but its still handy to know. .. note:: @@ -242,27 +283,32 @@ Advanced Blender as a module ------------------- -From a python perspective it's nicer to have everything as an extension which lets the python script combine many components. +From a Python perspective it's nicer to have everything as an extension +which lets the Python script combine many components. Advantages include: -* you can use external editors/IDE's with blenders python API and execute scripts within the IDE (step over code, inspect variables as the script runs). +- you can use external editors/IDE's with Blenders Python API and execute scripts within the IDE + (step over code, inspect variables as the script runs). +- editors/IDE's can auto complete Blender modules & variables. +- existing scripts can import Blender API's without having to run inside Blender. -* editors/IDE's can auto complete blender modules & variables. -* existing scripts can import blender API's without having to run inside blender. +This is marked advanced because to run Blender as a Python module requires a special build option. - -This is marked advanced because to run blender as a python module requires a special build option. - -For instructions on building see `Building blender as a python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_ +For instructions on building see +`Building Blender as a Python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_ Python Safety (Build Option) ---------------------------- -Since it's possible to access data which has been removed (see Gotcha's), this can be hard to track down the cause of crashes. +Since it's possible to access data which has been removed (see Gotcha's), +this can be hard to track down the cause of crashes. + +To raise Python exceptions on accessing freed data (rather than crashing), +enable the CMake build option WITH_PYTHON_SAFETY. -To raise python exceptions on accessing freed data (rather then crashing), enable the CMake build option WITH_PYTHON_SAFETY. +This enables data tracking which makes data access about 2x slower +which is why the option isn't enabled in release builds. -This enables data tracking which makes data access about 2x slower which is why the option is not enabled in release builds. diff --git a/doc/python_api/rst/info_tutorial_addon.rst b/doc/python_api/rst/info_tutorial_addon.rst index 5637cf2f638..239c28859a3 100644 --- a/doc/python_api/rst/info_tutorial_addon.rst +++ b/doc/python_api/rst/info_tutorial_addon.rst @@ -19,21 +19,17 @@ Prerequisites Before going through the tutorial you should... -* Familiarity with the basics of working in Blender. - -* Know how to run a script in Blender's text editor (as documented in the quick-start) - -* Have an understanding of Python primitive types (int, boolean, string, list, tuple, dictionary, and set). - -* Be familiar with the concept of Python modules. - -* Basic understanding of classes (object orientation) in Python. +- Familiarity with the basics of working in Blender. +- Know how to run a script in Blender's text editor (as documented in the quick-start) +- Have an understanding of Python primitive types (int, boolean, string, list, tuple, dictionary, and set). +- Be familiar with the concept of Python modules. +- Basic understanding of classes (object orientation) in Python. Suggested reading before starting this tutorial. -* `Dive Into Python <http://getpython3.com/diveintopython3/index.html>`_ sections (1, 2, 3, 4, and 7). -* :ref:`Blender API Quickstart <info_quickstart>` +- `Dive Into Python <http://getpython3.com/diveintopython3/index.html>`_ sections (1, 2, 3, 4, and 7). +- :ref:`Blender API Quickstart <info_quickstart>` to help become familiar with Blender/Python basics. @@ -45,13 +41,11 @@ Documentation Links While going through the tutorial you may want to look into our reference documentation. -* :ref:`Blender API Overview <info_overview>`. - +- :ref:`Blender API Overview <info_overview>`. - *This document is rather detailed but helpful if you want to know more on a topic.* - -* :mod:`bpy.context` api reference. - +- :mod:`bpy.context` api reference. - *Handy to have a list of available items your script may operate on.* - -* :class:`bpy.types.Operator`. - +- :class:`bpy.types.Operator`. - *The following addons define operators, these docs give details and more examples of operators.* @@ -78,11 +72,11 @@ To give an example, here is the simplest possible addon. print("Goodbye World") -* ``bl_info`` is a dictionary containing addon meta-data such as the title, version and author to be displayed in the +- ``bl_info`` is a dictionary containing addon meta-data such as the title, version and author to be displayed in the user preferences addon list. -* ``register`` is a function which only runs when enabling the addon, this means the module can be loaded without +- ``register`` is a function which only runs when enabling the addon, this means the module can be loaded without activating the addon. -* ``unregister`` is a function to unload anything setup by ``register``, this is called when the addon is disabled. +- ``unregister`` is a function to unload anything setup by ``register``, this is called when the addon is disabled. @@ -184,12 +178,15 @@ This addon takes the body of the script above, and adds them to an operator's `` register() -.. note:: ``bl_info`` is split across multiple lines, this is just a style convention used to more easily add items. +.. note:: + + ``bl_info`` is split across multiple lines, this is just a style convention used to more easily add items. + +.. note:: -.. note:: Rather than using ``bpy.context.scene``, we use the ``context.scene`` argument passed to ``execute()``. - In most cases these will be the same however in some cases operators will be passed a custom context - so script authors should prefer the ``context`` argument passed to operators. - + Rather than using ``bpy.context.scene``, we use the ``context.scene`` argument passed to ``execute()``. + In most cases these will be the same however in some cases operators will be passed a custom context + so script authors should prefer the ``context`` argument passed to operators. To test the script you can copy and paste this into Blender text editor and run it, this will execute the script directly and call register immediately. @@ -202,8 +199,8 @@ However running the script wont move any objects, for this you need to execute t :height: 574px :alt: Spacebar -Do this by pressing ``SpaceBar`` to bring up the operator search dialog and type in "Move X by One" (the ``bl_label``), -then press ``Enter``. +Do this by pressing :kbd:`Spacebar` to bring up the operator search dialog and type in +"Move X by One" (the ``bl_label``), then :kbd:`Enter`. @@ -211,11 +208,12 @@ The objects should move as before. *Keep this addon open in Blender for the next step - Installing.* + Install The Addon ----------------- -Once you have your addon within in Blender's text editor, you will want to be able to install it so it can be enabled in -the user preferences to load on startup. +Once you have your addon within in Blender's text editor, +you will want to be able to install it so it can be enabled in the user preferences to load on startup. Even though the addon above is a test, lets go through the steps anyway so you know how to do it for later. @@ -224,10 +222,11 @@ restrictions that apply to Python modules and end with a ``.py`` extension. Once the file is on disk, you can install it as you would for an addon downloaded online. -Open the user **File -> User Preferences**, Select the **Addon** section, press **Install Addon...** and select the file. +Open the user :menuselection:`File -> User Preferences`, +Select the *Addon* section, press *Install Addon...* and select the file. -Now the addon will be listed and you can enable it by pressing the check-box, if you want it to be enabled on restart, -press **Save as Default**. +Now the addon will be listed and you can enable it by pressing the check-box, +if you want it to be enabled on restart, press *Save as Default*. .. note:: @@ -241,7 +240,7 @@ press **Save as Default**. print(addon_utils.paths()) More is written on this topic here: - `Directory Layout <http://wiki.blender.org/index.php/Doc:2.6/Manual/Introduction/Installing_Blender/DirectoryLayout>`_ + `Directory Layout <https://www.blender.org/manual/getting_started/installing_blender/directorylayout.html>`_ Your Second Addon @@ -563,20 +562,26 @@ Bringing it all together # handle the keymap wm = bpy.context.window_manager - km = wm.keyconfigs.addon.keymaps.new(name='Object Mode', space_type='EMPTY') - kmi = km.keymap_items.new(ObjectCursorArray.bl_idname, 'SPACE', 'PRESS', ctrl=True, shift=True) - kmi.properties.total = 4 - addon_keymaps.append((km, kmi)) + # Note that in background mode (no GUI available), keyconfigs are not available either, so we have to check this + # to avoid nasty errors in background case. + kc = wm.keyconfigs.addon + if kc: + km = wm.keyconfigs.addon.keymaps.new(name='Object Mode', space_type='EMPTY') + kmi = km.keymap_items.new(ObjectCursorArray.bl_idname, 'SPACE', 'PRESS', ctrl=True, shift=True) + kmi.properties.total = 4 + addon_keymaps.append((km, kmi)) def unregister(): - bpy.utils.unregister_class(ObjectCursorArray) - bpy.types.VIEW3D_MT_object.remove(menu_func) - + # Note: when unregistering, it's usually good practice to do it in reverse order you registered. + # Can avoid strange issues like keymap still referring to operators already unregistered... # handle the keymap for km, kmi in addon_keymaps: km.keymap_items.remove(kmi) addon_keymaps.clear() + bpy.utils.unregister_class(ObjectCursorArray) + bpy.types.VIEW3D_MT_object.remove(menu_func) + if __name__ == "__main__": register() @@ -627,15 +632,12 @@ you want to see example code for, this is a good place to start. Here are some sites you might like to check on after completing this tutorial. -* :ref:`Blender/Python API Overview <info_overview>` - +- :ref:`Blender/Python API Overview <info_overview>` - *For more background details on Blender/Python integration.* - -* `How to Think Like a Computer Scientist <http://interactivepython.org/courselib/static/thinkcspy/index.html>`_ - +- `How to Think Like a Computer Scientist <http://interactivepython.org/courselib/static/thinkcspy/index.html>`_ - *Great info for those who are still learning Python.* - -* `Blender Development (Wiki) <http://wiki.blender.org/index.php/Dev:Contents>`_ - +- `Blender Development (Wiki) <http://wiki.blender.org/index.php/Dev:Contents>`_ - *Blender Development, general information and helpful links.* - -* `Blender Artists (Coding Section) <http://blenderartists.org/forum/forumdisplay.php?47-Coding>`_ - +- `Blender Artists (Coding Section) <http://blenderartists.org/forum/forumdisplay.php?47-Coding>`_ - *forum where people ask Python development questions* |