From 7bbf4b78313df9f6d2c760b527eb36a5d0418b82 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 2 Mar 2012 16:05:54 +0000 Subject: style cleanup - spelling - turns out we had tessellation spelt wrong all over. - use \directive for doxy (not @directive) - remove BLI_sparsemap.h - was from bmesh merge IIRC but entire file commented and not used. --- source/gameengine/PyDoc/API_intro.py | 110 --------- source/gameengine/PyDoc/PhysicsConstraints.py | 293 ------------------------ source/gameengine/PyDoc/VideoTexture.py | 217 ------------------ source/gameengine/PyDoc/bge_api_validate_py.txt | 136 ----------- source/gameengine/PyDoc/epy_docgen.sh | 16 -- source/gameengine/PyDoc/how_to_build_win.txt | 16 -- 6 files changed, 788 deletions(-) delete mode 100644 source/gameengine/PyDoc/API_intro.py delete mode 100644 source/gameengine/PyDoc/PhysicsConstraints.py delete mode 100644 source/gameengine/PyDoc/VideoTexture.py delete mode 100644 source/gameengine/PyDoc/bge_api_validate_py.txt delete mode 100755 source/gameengine/PyDoc/epy_docgen.sh delete mode 100644 source/gameengine/PyDoc/how_to_build_win.txt (limited to 'source/gameengine/PyDoc') diff --git a/source/gameengine/PyDoc/API_intro.py b/source/gameengine/PyDoc/API_intro.py deleted file mode 100644 index 097abbfbf1a..00000000000 --- a/source/gameengine/PyDoc/API_intro.py +++ /dev/null @@ -1,110 +0,0 @@ -# This is not a real module, it's simply an introductory text. - -""" -The Blender Game Engine Python API Reference -============================================ - - See U{release notes} for updates, changes and new functionality in the Game Engine Python API. - - Blender Game Engine Modules: - ---------------------------- - - Modules that include methods for accessing GameEngine data and functions. - - - L{GameLogic} utility functons for game logic. - - L{GameKeys} keyboard input and event conversion. - - L{Rasterizer} display and rendering. - - L{GameTypes} contains all the python types spesific to the GameEngine. - - Modules with documentation in progress: - --------------------- - - L{VideoTexture} - - L{PhysicsConstraints} - - Additional Modules: - ------------------- - - These modules have no GameEngine specific functionality but are useful in many cases. - - - L{mathutils} - - L{Geometry} - - L{BGL} - - -Introduction: -============= - - This reference documents the Blender Python API, a growing collection of - Python modules (libraries) that give access to part of the program's internal - data and functions. - - Through scripting Blender can be extended in real-time via - U{Python }, an impressive high level, multi-paradigm, open - source language. Newcomers are recommended to start with the tutorial that - comes with it. - - This opens many interesting possibilities not available with logic bricks. - - Game Engine API Stability: - -------------------------- - - When writing python scripts there are a number of situations you should avoid to prevent crashes or unstable behavior. - While the API tries to prevent problems there are some situations where error checking would be too time consuming. - - Known cases: - - Memory Limits. - - There is nothing stopping you from filling a list or making a string so big that that causes blender to run out of memory, in this case python should rasie a MemoryError, but its likely blender will crash before this point. - - - Accessing any data that has been freed. - - For instance accessing a KX_GameObject after its End Object actuator runs. - This will cause a SystemError, however for L{KX_MeshProxy}, L{KX_VertexProxy} and L{KX_VertexProxy} it will crash the blender game engine. - - See: L{GameTypes.PyObjectPlus.invalid} which many types inherit. - - - Mixing L{KX_GameObject} between scenes. - - For instance tracking/parenting an L{KX_GameObject} object to an object from other scene. - - External Modules: - ----------------- - - Since 2.49 support for importing modules has been added. - - This allows you to import any blender textblock with a .py extension. - - External python scripts may be imported as modules when the script is in the same directory as the blend file. - - The current blend files path is included in the sys.path for loading modules. - All linked libraries will also be included so you can be sure when linking in assets from another blend file the scripts will load too. - - A note to newbie script writers: - -------------------------------- - - Interpreted languages are known to be much slower than compiled code, but for - many applications the difference is negligible or acceptable. Also, with - profiling (or even simple direct timing with L{Blender.sys.time}) to - identify slow areas and well thought optimizations, the speed can be - I{considerably} improved in many cases. Try some of the best BPython scripts - to get an idea of what can be done, you may be surprised. - -@author: The Blender Python Team -@requires: Blender 2.49 or newer. -@version: 2.49 -@see: U{www.blender.org}: documentation and forum -@see: U{blenderartists.org}: user forum -@see: U{projects.blender.org} -@see: U{www.python.org} -@see: U{www.python.org/doc} -@see: U{Blending into Python}: User contributed documentation, featuring a blender/python cookbook with many examples. - -@note: the official version of this reference guide is only updated for each - new Blender release. But you can build the current SVN - version yourself: install epydoc, grab all files in the - source/gameengine/PyDoc/ folder of Blender's SVN and use the - epy_docgen.sh script also found there to generate the html docs. - Naturally you will also need a recent Blender binary to try the new - features. If you prefer not to compile it yourself, there is a testing - builds forum at U{blender.org}. -""" diff --git a/source/gameengine/PyDoc/PhysicsConstraints.py b/source/gameengine/PyDoc/PhysicsConstraints.py deleted file mode 100644 index bec8973edc6..00000000000 --- a/source/gameengine/PyDoc/PhysicsConstraints.py +++ /dev/null @@ -1,293 +0,0 @@ -""" -Documentation for the PhysicsConstraints module. -================================================ - -Example:: - - - # Adding a point constraint # - ############################### - - - # import BGE internal module - import PhysicsConstraints - - # get object list - obj_list = GameLogic.getCurrentScene().objects - - # get object named Obj_1 - root = obj_list["root"] - obj = obj_list["obj"] - - # get object physics ID - phido = obj.getPhysicsId() - - # get root physics ID - phidr = root.getPhysicsId() - - # want to use point constraint type - constraint_type = 1 - - # Use bottom right front corner of object for point constraint position - point_pos_x = 1.0 - point_pos_y = -1.0 - point_pos_z = -1.0 - - # create a point constraint - const = PhysicsConstraints.createConstraint( phido, phidr, constraint_type, point_pos_x, point_pos_y, point_pos_z) - - # stores the new constraint ID to be used later - obj["constraint_ID"] = const.getConstraintId() - - -Example:: - - - # Removing a point constraint # - ################################# - - - # import BGE internal module - import PhysicsConstraints - - # get object list - obj_list = GameLogic.getCurrentScene().objects - - # get object 1 - obj = obj_list["obj"] - - # get constraint ID that was saved as an obj property - # when the constraint was created - constraint_ID = obj["constraint_ID"] - - # remove constraint - PhysicsConstraints.removeConstraint(constraint_ID) - -""" - -def createConstraint(obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z): - """ - Create a point constraint between two objects, an edge constraint between two objects, or a vehicle constraint on an object. - - You only have to input the needed parammeters depending on the type of constraint you are trying to create. - - - B{Point Constraint} :: - - While creating a point constraint, the "pointPos" values define where you want the pivot point to be located. - If you are creating a point constraint be sure to assing the integer "1" as the constraintType value. - - Parameters to use: - obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z - - B{Edge Constraint} :: - - While creating an edge constraint, the "edgePos" values define where you want the center of the edge constraint to be. - Also, the "edgeAngle" values define in which direction you want the edge constraint to point (As a 3 dimensions vector). - If you want to create an edge constraint be sure to assing the integer "2" as the constraintType value. - - Parameters to use: - obj_PhysicsID, root_PhysicsID, constraintType, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z} - - B{Vehicle Constraint} :: - - While creating a point constraint, the "pointPos" values define where you want the pivot point to be located. - If you want to create an edge constraint be sure to assing the integer "0" as the constraintType value. - - Parameters to use : - obj_PhysicsID, root_PhysicsID, constraintType - - @type obj_PhysicsID: integer - @param obj_PhysicsID: The physic ID of the first object to constraint. - - @type root_PhysicsID: integer - @param root_PhysicsID: The physic ID of the second object to constraint. - - @type constraintType: integer - @param constraintType: The type of constraint. - - @type pointPos_x: float - @param pointPos_x: The X position of the point constraint. - - @type pointPos_y: float - @param pointPos_y: The Y position of the point constraint. - - @type pointPos_z: float - @param pointPos_z: The Z position of the point constraint. - - @type edgePos_x: float - @param edgePos_x: The X value of the center of the edge constraint. - - @type edgePos_y: float - @param edgePos_y: The Y value of the center of the edge constraint. - - @type edgePos_z: float - @param edgePos_z: The Z value of the center of the edge constraint. - - @type edgeAngle_x: float - @param edgeAngle_x: The X value of the edge's orientation vector. - - @type edgeAngle_y: float - @param edgeAngle_y: The Y value of the edge's orientation vector. - - @type edgeAngle_z: float - @param edgeAngle_z: The Z value of the edge's orientation vector. - - @rtype: integer - @return: The created constraint ID - """ - - -def getAppliedImpulse(constraint_ID): - """ - Returns the applied impulse. - - @param constraint_ID: The constraint ID that was saved on the creation of the constraint. - @type constraint_ID: integer - @rtype: float - @return: Measure the stress on a constraint. - """ - - -def getVehicleConstraint(constraint_ID): - """ - Returns the vehicle constraint ID. - - @param constraint_ID: The constraint ID that was saved on the creation of the constraint. - @type constraint_ID: integer - @rtype: integer - """ -def removeConstraint(constraint_ID): - """ - - Removes the constraint between 2 game objects (point and edge constraints). - - It does not remove vehicle constraints. - - @param constraint_ID: The constraint ID that was saved on the creation of the constraint. - @type constraint_ID: integer - """ -def setDeactivationLinearTreshold(linearTreshold): - """ - - Sets the linear velocity that an object must be below before the deactivation timer can start. - - This affects every object in the scene, except for game objects that have 'No sleeping' turned on. - - @param linearTreshold: The linear velocity. - @type linearTreshold: float - """ -def setDeactivationAngularTreshold(angularTreshold): - """ - - Sets the angular velocity that an object must be below before the deactivation timer can start. - - This affects every object in the scene, except for game objects that have 'No sleeping' turned on. - - @param angularTreshold: The angular velocity. - @type angularTreshold: float - """ -def setDeactivationTime(time): - """ - - Time (in seconds) after objects with velocity less then thresholds (see below) are deactivated. - - This affects every object in the scene, except for game objects that have 'No sleeping' turned on. - - This function is directly related with the 2 above functions. - - - @param time: The time in seconds. - @type time: float - """ -def setGravity(gx, gy, gz): - """ - Sets the gravity for the actual scene only. - - All other scenes remain unaffected. - - This affects every object in the scene that has physics enabled. - - @param gx: The force of gravity on world x axis. - @type gx: float - @param gy: The force of gravity on world y axis. - @type gy: float - @param gz: The force of gravity on world z axis. - @type gz: float - """ -def setLinearAirDamping(damping): - """ - - Sets the linear air resistance for all objects in the scene. - - @param damping: The linear air resistance. - @type damping: float - """ -def setNumIterations(numIter): - """ - Sets the number of times an iterative constraint solver is repeated. - - Increasing the number of iterations improves the constraint solver at the cost of performances & the speed of the game engine. - - @param numIter: The number of timesubsteps. (Input 0 to suspend simulation numSubStep) - @type numIter: integer - """ -def setNumTimeSubSteps(numSubStep): - """ - Set the quality of the entire physics simulation including collision detection and constraint solver. - - Increase the number of time substeps to improves the quality of the entire physics simulation at the cost of the performance & the speed of the game engine. - - @param numSubStep: The number of timesubsteps. (Input 0 to suspend simulation numSubStep) - @type numSubStep: integer - """ -#def setDebugMode(): -# """ -# -# -# -# @param numIter: -# @type numIter: -# """ -#def setCcdMode(): -# """ -# Does something -# -# @rtype: -# """ -#def setContactBreakingTreshold(): -# """ -# Does something -# -# @rtype: -# """ -#def setSolverDamping(): -# """ -# Does something -# -# @rtype: -# """ -#def setSolverTau(): -# """ -# Does something -# -# @rtype: -# """ -#def setSolverType(): -# """ -# Does something -# -# @rtype: -# """ -#def setSorConstant(): -# """ -# Does something -# -# @rtype: -# """ -#def setUseEpa(): -# """ -# Does something -# -# @rtype: -# """ diff --git a/source/gameengine/PyDoc/VideoTexture.py b/source/gameengine/PyDoc/VideoTexture.py deleted file mode 100644 index 9d2148d8eaf..00000000000 --- a/source/gameengine/PyDoc/VideoTexture.py +++ /dev/null @@ -1,217 +0,0 @@ -""" -The VideoTexture module allows you to manipulate textures during the game. - -Several sources for texture are possible: video files, image files, -video capture, memory buffer, camera render or a mix of that. - -The video and image files can be loaded from the internet using an URL -instead of a file name. - -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. - -VideoTexture uses FFmpeg to load images and videos. All the formats and codecs -that FFmpeg supports are supported by VideoTexture, including but not limited to:: - - * AVI - * Ogg - * Xvid - * Theora - * dv1394 camera - * video4linux capture card (this includes many webcams) - * videoForWindows capture card (this includes many webcams) - * JPG - -The principle is simple: first you identify a texture on an existing object using -the L{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, -except that you are now in control of the texture. - -When the texture object is deleted, the new texture is deleted and the old texture restored. - -Example:: - import VideoTexture - import GameLogic - - contr = GameLogic.getCurrentController() - obj = contr.owner - - # the creation of the texture must be done once: save the - # texture object in an attribute of GameLogic module makes it persistent - if not hasattr(GameLogic, 'video'): - - # identify a static texture by name - matID = VideoTexture.materialID(obj, 'IMvideo.png') - - # create a dynamic texture that will replace the static texture - GameLogic.video = VideoTexture.Texture(obj, matID) - - # define a source of image for the texture, here a movie - movie = GameLogic.expandPath('//trailer_400p.ogg') - GameLogic.video.source = VideoTexture.VideoFFmpeg(movie) - GameLogic.video.source.scale = True - - # quick off the movie, but it wont play in the background - GameLogic.video.source.play() - - # you need to call this function every frame to ensure update of the texture. - GameLogic.video.refresh(True) - - -""" -def getLastError(): - """ - Returns the description of the last error that occurred in a VideoTexture function. - - @rtype: string - """ -def imageToArray(image,mode): - """ - Returns a BGL.buffer corresponding to the current image stored in a texture source object - - @param image: Image source object. - @type image: object of type L{VideoFFmpeg}, L{ImageFFmpeg}, L{ImageBuff}, L{ImageMix}, L{ImageRender}, L{ImageMirror} or L{ImageViewport} - @param 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. - The default mode is "RGBA". - @type mode: string - @rtype: BGL.buffer - @returns: 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. - """ - -def materialID(object,name): - """ - Returns a numeric value that can be used in L{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, - 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 - 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: VideoTexture.materialID(obj, 'IMvideo.png') - - @param object: the game object that uses the texture you want to make dynamic - @type object: game object - @param name: name of the texture/material you want to make dynamic. - @type name: string - @rtype: integer - """ -def setLogFile(filename): - """ - Sets the name of a text file in which runtime error messages will be written, in addition to the printing - 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. - - @param filename: name of error log file - @type filename: string - @rtype: integer - """ -def FilterBGR24(): - """ - Returns a new input filter object to be used with L{ImageBuff} object when the image passed - to the ImageBuff.load() function has the 3-bytes pixel format BGR. - - @rtype: object of type FilterBGR24 - """ -def FilterBlueScreen(): - """ - Does something - - @rtype: - """ -def FilterColor(): - """ - Does something - - @rtype: - """ -def FilterGray(): - """ - Does something - - @rtype: - """ -def FilterLevel(): - """ - Does something - - @rtype: - """ -def FilterNormal(): - """ - Does something - - @rtype: - """ -def FilterRGB24(): - """ - Returns a new input filter object to be used with L{ImageBuff} object when the image passed - to the ImageBuff.load() function has the 3-bytes pixel format RBG. - - @rtype: object of type FilterRGB24 - """ -def FilterRGBA32(): - """ - Returns a new input filter object to be used with L{ImageBuff} object when the image passed - to the ImageBuff.load() function has the 4-bytes pixel format RGBA. - - @rtype: object of type FilterRGBA32 - """ -def ImageBuff(): - """ - Does something - - @rtype: - """ -def ImageFFmpeg(): - """ - Does something - - @rtype: - """ -def ImageMirror(): - """ - Does something - - @rtype: - """ -def ImageMix(): - """ - Does something - - @rtype: - """ -def ImageRender(): - """ - Does something - - @rtype: - """ -def ImageViewport(): - """ - Does something - - @rtype: - """ -def Texture(): - """ - Does something - - @rtype: L{Texture} - """ -def VideoFFmpeg(): - """ - Does something - - @rtype: - """ diff --git a/source/gameengine/PyDoc/bge_api_validate_py.txt b/source/gameengine/PyDoc/bge_api_validate_py.txt deleted file mode 100644 index ebd74c06bb3..00000000000 --- a/source/gameengine/PyDoc/bge_api_validate_py.txt +++ /dev/null @@ -1,136 +0,0 @@ -#~ This program is free software; you can redistribute it and/or modify -#~ it under the terms of the GNU General Public License as published by -#~ the Free Software Foundation; version 2 of the License. - -#~ This program is distributed in the hope that it will be useful, -#~ but WITHOUT ANY WARRANTY; without even the implied warranty of -#~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -#~ GNU General Public License for more details. - -# This script must run from a logic brick so it has access to the game engine api -# it assumes the root blender source directory is the current working directory -# -# Currently it only prints missing modules and methods (not attributes) - -import sys, os - -BGE_API_DOC_PATH = 'source/gameengine/PyDoc' - - -mods = ['GameLogic', 'Rasterizer', 'GameKeys'] -mods_dict = {} -for m in mods: - mods_dict[m] = sys.modules[m] - - -import GameTypes -type_members = {} - -for type_name in dir(GameTypes): - if type_name.startswith('__'): - continue - - type_object = getattr(GameTypes, type_name) - - members = [] - type_members[type_object.__name__] = members - - for member in type_object.__dict__.keys(): - if member.startswith('__'): - continue - - # print type_object.__name__ + '.' + k - members.append(member) - - - -doc_dir= os.path.join(os.getcwd(), BGE_API_DOC_PATH) - -if doc_dir not in sys.path: - sys.path.append(doc_dir) - - -def check_attribute(class_ob, member): - doc = class_ob.__doc__ - if not doc: - return False - - for l in doc.split('\n'): - l = l.strip() - - ''' - @ivar foo: blah blah - to - foo - - ''' - - if l.startswith('@ivar') or l.startswith('@var'): - var = l.split()[1].split(':')[0] - - if var == member: - return True - - return False - - - - - - -print '\n\n\nChecking Docs' - -PRINT_OK = False - -pymod = sys.modules['GameTypes'] -del sys.modules['GameTypes'] # temp remove -mod = __import__('GameTypes') # get the python module -reload(mod) # incase were editing it -sys.modules['GameTypes'] = pymod - -for type_name in sorted(type_members.keys()): - members = type_members[type_name] - - try: - type_class = getattr(mod, type_name) - except: - print "missing class: %s.%s - %s" % (type_name, type_name, str(sorted(members))) - continue - - for member in sorted(members): - try: - getattr(type_class, member) - if PRINT_OK: - print "\tfound: %s.%s" % (type_name, member) - except: - if check_attribute(type_class, member): - if PRINT_OK: - print "\tfound attr: %s.%s" % (type_name, member) - else: - print "\tmissing: %s.%s" % (type_name, member) - - -# Now check the modules -for mod_name, pymod in mods_dict.iteritems(): - print pymod - del sys.modules[mod_name] - - # Now well get the python version - pydoc = __import__(mod_name) - pydoc = reload(pydoc) # avoid using the out dated pyc file only - print pydoc.__file__ - - for member in sorted(dir(pymod)): - if hasattr(pydoc, member) or check_attribute(pydoc, member): - if PRINT_OK: - print "\tfound module attr: %s.%s" % (mod_name, member) - else: - print "\tmissing module attr: %s.%s" % (mod_name, member) - - # Restore real module - sys.modules[mod_name] = pymod - - -sys.path.pop() # remove the pydoc dir from our import paths - - diff --git a/source/gameengine/PyDoc/epy_docgen.sh b/source/gameengine/PyDoc/epy_docgen.sh deleted file mode 100755 index dd30256f42f..00000000000 --- a/source/gameengine/PyDoc/epy_docgen.sh +++ /dev/null @@ -1,16 +0,0 @@ -# epy_docgen.sh -# generates blender python doc using epydoc -# requires epydoc in your PATH. -# run from the doc directory containing the .py files -# usage: sh epy_docgen.sh - -# set posix locale so regex works properly for [A-Z]*.py -LC_ALL=POSIX - -epydoc --debug -v -o BPY_GE --url "http://www.blender.org" --top API_intro \ - --name "Blender GameEngine" --no-private --no-sourcecode --inheritance=included \ - *.py \ - ../../../source/blender/python/api2_2x/doc/BGL.py \ - ../../../source/blender/python/api2_2x/doc/Mathutils.py \ - ../../../source/blender/python/api2_2x/doc/Geometry.py - diff --git a/source/gameengine/PyDoc/how_to_build_win.txt b/source/gameengine/PyDoc/how_to_build_win.txt deleted file mode 100644 index 5610ced3b2a..00000000000 --- a/source/gameengine/PyDoc/how_to_build_win.txt +++ /dev/null @@ -1,16 +0,0 @@ -How To Build the BGE Documentation in Windows -------------------------------------------------------------------------- -1) download and install Python 2.6 - http://www.python.org -2) download and install Epydocs - http://epydoc.sourceforge.net - -* for the following lines we will assume that your installation of Python is in C:\Python26 and epydocs is installed in the default folder Scripts\epydoc. - -3) creates a epy_docgen.bat file in this folder (source\gameengine\PyDoc\) and paste the following line into it: - -:::::: -C:\Python26\python.exe C:\Python26\Scripts\epydoc.py --debug -v -o BPY_GE --url "http://www.blender.org" --top API_intro --name "Blender GameEngine" --no-private --no-sourcecode --inheritance=included *.py ../../../source/blender/python/api2_2x/doc/BGL.py ../../../source/blender/python/api2_2x/doc/Mathutils.py ../../../source/blender/python/api2_2x/doc/Geometry.py -:::::: - -4) run your created batch file. If everything goes well it creates a folder named BPY_GE with all the generated documentation. - -Documentation valid in March of 2010 - Blender 2.5alpha2 -- cgit v1.2.3