First commit to make some structure in doc/ directory.
- moved source/blender/python/doc -> doc/python_api
- moved source/gameengine/PyDoc/*.rst -> doc/python_api/rst
- modified accordingly sphinx_doc_gen.py and sphinx_doc_gen.sh
(later on I'll try alternative/ scripts by neXyon as promised :)
- source/gameengine/PyDoc/ is still there because contains epydoc stuff for the bge, will ask more and look into it later
* A few places in the bge.events docs mentioned bge.keys, when it should have been bge.events
* Created two aliases to bge.events.RETKEY: ENTERKEY and RETURNKEY
* ENTERKEY and RETURNKEY have been added to the docs and RETKEY marked as deprecated
* Added an example of using bge.logic.keyboard to the bge.events docs
This patch makes SCA_PythonKeyboard.events and SCA_PythonMouse.events return a dictionary of all inputs (including inactive) instead of a list of active inputs.
Example usage:
import bge
if bge.logic.keyboard.events[bge.events.SPACEBAR] = bge.logic.KX_INPUT_JUST_ACTIVATED:
print("Spacebar pressed!")
A couple of changes to the patch:
* Wrap python stuff in #ifndef DISABLE_PYTHON
* Clear and decref m_event_dict in the destructors
A couple of things not related to the patch:
* Made member variables private
* Removed a commented out (and no longer used) method (SCA_PythonMouse.show())
This patch allows a user to pass binary data to LibLoad() to load a blend file from memory instead of a file path. I don't know how useful this will be for others, but I've used it so far for:
* Decrypting .blend files and loading them without having to store the .blend on the hard drive
* Pulling .blend data out of an archive and loading it (again skipping the hard drive)
So, it seems the biggest use for this is skipping a bit of file IO (and possibly some security problems).
Example usage:
import bge
with f as open('myfile.blend', 'rb'):
data = f.read()
bge.logic.LibLoad('Name', 'Scene', data)
- remove scons option WITH_BF_FHS, its not needed anymore.
- comment WITH_BF_DOCS, was using epydocs which we dont use now.
- blenderlite target was broken, always using openmp.
- building without python wasnt working.
- fixed some warnings.
BL_ArmatureChannel.rotaion_euler -> BL_ArmatureChannel.rotation_euler
Making the docs match the code:
BL_ArmatureChannel.rotation -> BL_ArmatureChannel.rotation_quaternion
BL_ArmatureChannel.euler_rotation -> BL_ArmatureChannel.rotation_euler
bge.types
---------
- removed lists if they were already available in bge.logic and crosslinked
where the list contained description, moved the descriptions in bge.logic
so we have useful thing in one place only
- fixed a lot of bad formatting, like bad indentation and usage of TAB
- changed from literal to codeblocks that smerch for the useful suggestion :)
- whered appropriate I've moved code examples to the end, after notes and all
it is blocking to have a big black block before actually see a method parameters or return type
- have doubt about the list at bge.types.html#bge.types.SCA_MouseSensor.mode
possibly tomorrow will ask Dalai
bge.logic
---------
- added sensor status list
- cross linked with bge.types where needed
- added a section "ShapeAction Actuator" because in bge.types these constants are docuemented, but in 2.5 I don't see the ShapeAction Actuator
(anymore, or for now)
I'll ask Dalai tomorrow or when possible (check bge.logic.html#shape-action-actuator once cambo rebuilds the docs)
- moved descriptions from bge.types lists to logic page where appropriate
- where possible, added custom directive :value: so we have a consistent way to show the value of constants
some more cleanup:
- made structure in source/gameengine/PyDoc/bge.events.rst to be able to crosslink properly
- cleaned notes and warnings syntax, and also now they are always the last elements after all the other tags
- substituted some lists of possible values of a parameter with links to lists of values (not finished)
like in bge.types.html#bge.types.SCA_PythonKeyboard
- uncertain about some values, like in http://www.blender.org/documentation/250PythonDoc/bge.types.html#bge.types.SCA_ISensor.status
(list of KX_SENSOR_INACTIVE,... etc aren't documented or non-existant, will investigate)
- now that I've made syntax changes in the previous commit I moved blocks to to have sensors/actuators grouped together
- added sections to have a nice table of contents
- formatted 2 lists and links to classes
* source/blender/python/doc/sphinx_doc_gen.py
changed syntax for declating attributes type to use :type: instead of *type* os it
* source/gameengine/Ketsji/KX_PythonInit.cpp
While documenting I've found that we have two naming conventions for constraints in BGE python api,
example: KX_CONSTRAINTACT_DIRPZ and KX_ACT_CONSTRAINT_FHPX: the right convention is KX_CONSTRAINTACT_xxx
After talking with dalai and cambpell we agreed that this kind of change is better suited for NExyon GSoC
so I marked as TODO
Also, found 2 duplicate rows, fixed after askin nexyon
* source/gameengine/PyDoc/bge.logic.rst
there were 2 blocks for constraints, I've put them together in docs and fixed some other lines
* source/gameengine/PyDoc/bge.types.rst
first cleanup: mainly started using ":type:", it was mixed usage of *type* and **type**
started cleaning some bullet list in a way that varibles link to the constant in appropriate page
I'll continue later
PhysicsConstraints module documented by Jean-François (Ninja Goliath) based on GameKit 2nd ed.
Thanks for the initiative and the great help!
General advice for anyone helping with EpyDocs:
* use :: instead of : to keep the indentation correct,
* use B{} for clarity when needed (e.g. createConstraints)
Adding F13 to F19 to complement Matt's recent commit
* There are other (not so important) functions in PhysicsConstraints module that are not exposed in the documentation right now.
The generated page is temporarily here, if someone want to review it:
http://blenderecia.orgfree.com/blender/tmp/PhysicsConstraints-module.html
The patch exposes mouse and keyboard read-only properties in the GameLogic module
Also renames bge.keys to bge.events (* Note: name of bge submodules (logic, render, ...) may change before 2.5 final release [right Campbell?]).
"""
This patch adds two new types to the BGE:
SCA_PythonKeyboard
SCA_PythonMouse
These two types allow users to make use of the keyboard and mouse without the need for a keyboard or mouse sensor.
SCA_PythonKeyboard has an events property that acts just like SCA_KeyboardSensor.events.
SCA_PythonMouse also has an events property to check for mouse events. Further more it supports getting and setting normalized cursor position (from 0.0 to 1.0) with SCA_PythonMouse.position. The cursor can be shown/hidden using SCA_PythonMouse.visible.
"""
Its use is similar with current mouse and keyboard controllers. With the exception of mouse position being normalized and writable as well (replacing Rasterizer.setMousePosition).
Code Sample:
######
from bge import logic, events
mouse = logic.mouse
keyboard = logic.keyboard
for key,status in keyboard.events:
if status == logic.KX_INPUT_JUST_ACTIVATED:
if key == events.WKEY:
print(mouse.position)
# move_forward()
mouse.visible = True # turn cursor visible
mouse.position = 0.5,0.5 # centralize mouse - use tuple
######
* Important Note: mouse.position still will not work properly for Letterbox mode.
In order to fix letterboxing I may need to move the set x,y mouse function to inside the canvas code (to avoid duplicated code between mouse sensor and bge.logic.mouse). I'll leave this for another commit though.
Thanks Mitchell for the work on that.
- added new mathutils.Color() type, use with rna so we can do for eg:
material.diffuse_color.r = 1.0
# also has hsv access
material.diffuse_color.s = 0.6
- made Mathutils and Geometry module names lowercase.
We have already a .sh file to build epydocs from Linux, so why not to have it in Windows as well ;) I think that this guide can help people interested in help with the API documentation to test their work.
I'm actually already in touch with at least one volunteer helping with PhysicsConstraints module. VideoTexture may not be a one man job though, for I hope this document can also help.
of course it wasn't only a matter of adding the properties in the api :)
The code of validValueForIntervalProperty and modeChange are the same BUT in the future they shouldn't be, for I think it's fine to keep them as separated functions.
Bonus fix: Also we are now checking if the new mode is interval and update the range expression.
Add optional parameter to VideoTexture.Texture refresh() method
to specify timestamp (in seconds from start of movie) of the frame
to be loaded. This value is passed down to image source and for
VideoFFmpeg source, it is used instead of current time to load
the frame from the video file.
When combined with an audio actuator, it can be used to synchronize
the sound and the image: specify the same video file in the sound
actuator and use the KX_SoundActuator time attribute as timestamp
to refresh: the frame corresponding to the sound will be loaded:
GameLogic.video.refresh(True, soundAct.time)
PhysicsConstraints is documented in the Game Kit Book:
http://download.blender.org/documentation/gamekit1/
VideoTexture is documented in the wiki:
http://wiki.blender.org/index.php/Dev:Source/GameEngine/2.49/VideoTexture
I don't think I will have time to fill the documentation. But I hope this commit helps someone interested in helping it.
Therefore volunteers to document those modules are highly welcome !!! (let's give to BGE the documentation it deserves)!
* + added GameLogic.Lave/LoadGlobalDict + some typo fixes
How it works now:
whenever you have to read/write object names you can do it without the prefix "OB". (it's not hard at all to fix scripts)
How it was before:
It was a mess :)
We had an inconsistent API where sometimes you had to input "OBname" and other "name" directly to assign object as data (usually in actuators).
Justification for the change:
Talking with Campbell we had since a while ago this feeling that this should be changed any time we were going to deprecate the API. So in order to deliver Blender 2.5beta0 with a more close-to-the-final API we decided that today was a good day to implement that.
Remaining issues:
1) VideoTexture uses IM or MA to identify the output material/texture. I haven't touched that, but it does look a bit off. (i.e. I didn't changed any MA, IM naming)
2) I didn't see the code of dynamic mesh. It may need to be edited as well.
http://wiki.blender.org/index.php/BlenderDev/Blender2.5/Unix_FHS
for scons WITH_BF_FHS enabled an alternative layout eg.
scons WITH_BF_FHS=1 BF_INSTALLDIR="/usr/local"
for CMake just run "make install" after make (CMAKE_INSTALL_PREFIX is used for the base path)
Currently only scripts use both the system and user path correctly, other areas of blender have their own path code inline with lots of ifdefs, needs to be carefully updated.
Instead use __contains__, eg.
if key in gameOb: ...
Mathutils returns from PyMath.cpp were incorrectly using wrapped Mathutils types. Wrapped types should only be used with a callback now.
