Details

Reviewers

Campbell Barton (campbellbarton)
Porteries Tristan (panzergame)
Thomas Szepe (hg1)
Daniel Stokes (kupoman)
Jorge Bernal (lordloki)
Mitchell Stokes (moguri)

Maniphest Tasks

T44284: bge.texture.Texture(gameObj) - refresh() API documentation is outdatted/incomplete.

Commits

rBS6ed1a1abe23f: BGE: bge.texture API documentation enhancement
rB6ed1a1abe23f: BGE: bge.texture API documentation enhancement
rB108b2f820727: BGE: bge.texture API documentation enhancement

Summary

This patch attempts to improve and review the documentation of bge.texture, as requested in the TODO list.

More specifically, it

fixes the rst syntax, including titles of the examples bge.texture.py and bge.texture.1.py;
adds, standardizes and reviews description of the API elements, particularly signatures, types, etc.
adds SOURCE_* constants to the doc
splits the doc into thematical parts (Video, Image, Texture, and Filter Classes, Functions, Constants).

Notes:

The parameter "mode" of ImageBuff.plot has to be described better. Actually, the whole set of IMB_BLEND_* constants (from IMB_imbuf.h) should be exposed to Python. I'll do that in a future diff, and complete the doc at the same moment (adding those IMB_BLEND_* constants to the Constants part of this doc).
The option of using webcams in VideoFFmpeg is still particularly not well documented. I am planning to make a proposal about fixing T18634 (and its corresponding TODO in the list) by integrating OpenCV in the BGE (and Blender?). The idea would then probably be to add a new class, f.ex. ImageWebcam, making this functionnality more specialized. So for now I don't think it is worth to document that part much.

This patch fixes T44284 too.

Diff Detail

Repository: rB Blender

Event Timeline

Quentin Wenger (Matpi) updated this revision to Diff 4397.Jun 13 2015, 10:47 PM

Quentin Wenger (Matpi) retitled this revision from to BGE: bge.texture API documentation enhancement.

Quentin Wenger (Matpi) updated this object.

Quentin Wenger (Matpi) added reviewers: Mitchell Stokes (moguri), Daniel Stokes (kupoman), Campbell Barton (campbellbarton), Porteries Tristan (panzergame), Jorge Bernal (lordloki).

Quentin Wenger (Matpi) set the repository for this revision to rB Blender.

Quentin Wenger (Matpi) added projects: Game Engine, Game Python, Documentation.

Added IMB_BLEND_* constants to the bge.texture module + Added doc for them

Quentin Wenger (Matpi) updated this object.Jun 14 2015, 12:59 AM

Nice work @Quentin Wenger (Matpi) :) it looks good to me, your patch show hided stuff in video texture.

This revision is now accepted and ready to land.Jun 14 2015, 10:08 AM

Change ImageBuff.plot signature: mode=IMB_BLEND_COPY. I haven't found any way to make it linked (:data: domain doesn't work), so I added it as simple text - not problematic as the doc of mode parameter shows the appropriate link.

Thomas Szepe (hg1) added a subscriber: Thomas Szepe (hg1).Jun 15 2015, 11:16 PM

Thomas Szepe (hg1) added inline comments.

doc/python_api/rst/bge.texture.rst
281–282	That is wrong. The value is a python integer converted to an unsigned char 0-255 (black to white).
322	positionY [, mode=IMB_BLEND_COPY]) or positionY, [mode=IMB_BLEND_COPY]) will look better.
336–362	I hope you know, if you don't make a list, sphinx will align vertical text still horizontal. The output will look like this. mode (int) – Drawing mode (IMB_BLEND_MIX, IMB_BLEND_ADD, IMB_BLEND_SUB, IMB_BLEND_MUL, IMB_BLEND_LIGHTEN, IMB_BLEND_DARKEN, IMB_BLEND_ERASE_ALPHA, IMB_BLEND_ADD_ALPHA, IMB_BLEND_OVERLAY, IMB_BLEND_HARDLIGHT, IMB_BLEND_COLORBURN, IMB_BLEND_LINEARBURN, IMB_BLEND_COLORDODGE, IMB_BLEND_SCREEN, IMB_BLEND_SOFTLIGHT, IMB_BLEND_PINLIGHT, IMB_BLEND_VIVIDLIGHT, IMB_BLEND_LINEARLIGHT, IMB_BLEND_DIFFERENCE, IMB_BLEND_EXCLUSION, IMB_BLEND_HUE, IMB_BLEND_SATURATION, IMB_BLEND_LUMINOSITY, IMB_BLEND_COLOR, IMB_BLEND_COPY, IMB_BLEND_COPY_RGB, IMB_BLEND_COPY_ALPHA). (optional)
444	The attribute image returns a integer list [r,g,b,a]. Range: 0 to 255.
997–1004	The resulting output looks really terrible (also the original). Maybe you can improve the readability with a list.
source/gameengine/VideoTexture/blendVideoTex.cpp
54	Do you really need extern "C". On Windows with Visual studio it will compile without it.

Quentin Wenger (Matpi) added inline comments.Jun 16 2015, 12:01 AM

doc/python_api/rst/bge.texture.rst
281–282	Whoops, yes, you're right, I mixed up "b" parsing arguments with bools...
322	Don't agree here: this is the standard way to do it, look for example at os.getenv (took python 2.7 API because it uses nearly the same theme as Blender API doc).
336–362	Yes, I know, but lists aren't supported into arguments AFAIK (look at the compiled doc for 2.74 -> nothing shown). The only way I found was to make a simple list, even if horizontal. But I'd be very happy to find a way to make vertical lists...
444	Don't agree, look ImageBase.cpp/Image_getImage or test. Or am I completely wrong?
997–1004	As said above, lists are problematic. But you're right, this part should be made better.
source/gameengine/VideoTexture/blendVideoTex.cpp
54	Not sure... But normally you should use it. See for example ImageBuff.cpp.

Reflect changes in master + bugfix in ImageBuff attribute color

Make vertical lists; small syntax improvements; beautify imageToArray doc.

Add link to Wikipedia's Blend Modes as description of IMB_BLEND_* constants (same as in the manual: http://www.blender.org/manual/glossary/index.html#term-color-blend-modes).

Make optional arguments in signatures more consistent.

Some more consistence in optional arguments in signatures.

Thomas Szepe (hg1) added inline comments.Jun 16 2015, 8:14 PM

doc/python_api/rst/bge.texture.rst
322	Yes I know, but for me it looks ugly. Maybe it is better to remove the square bracket. I looked into the Blender API and I don't find any methods which are using square bracket for optional arguments. I think it is better to ask Campbell.
444	Yes you are right, it now prints out Buffer(GL_BYTE, [...]). In previous it returns only a list in the printout. Example: Buffer(GL_BYTE, [0, 0, 255, 255, 128, 128, 255, 255, 255, 255, 255, 255, 127, 0, 127, 255, 128, 128, 127, 255, 127, 255, 127, 255, 255, 0, 0, 255, 128, 128, 0, 255, 0, 255, 0, 255])

Quentin Wenger (Matpi) added inline comments.Jun 16 2015, 9:30 PM

doc/python_api/rst/bge.texture.rst
322	Ok, changed it to key=default_value to reflect Blender's standard.
322	Sorry, I answered but forgot to submit my answer... :-/ I actually discussed with Campbell, and he told me that in Blender the "defaults" solution is in use rather than the "square brackets" one. My last diff shows that change. Sorry again for the inconvenience.

Remove values of constants, useless and hard to keep updated.

Quentin Wenger (Matpi) updated this object.Jun 19 2015, 11:55 AM

Quentin Wenger (Matpi) added a task: T44284: bge.texture.Texture(gameObj) - refresh() API documentation is outdatted/incomplete..

Looks good to me. Good work

Looks good to me.

Closed by commit rB108b2f820727: BGE: bge.texture API documentation enhancement (authored by Quentin Wenger (Matpi), committed by Porteries Tristan (panzergame)). · Explain WhyJul 6 2015, 8:34 PM

This revision was automatically updated to reflect the committed changes.

BGE: bge.texture API documentation enhancement
ClosedPublic
Actions

Details

Diff Detail

Event Timeline

Revision Contents
Changeset List

Diff 4601

doc/python_api/examples/bge.texture.1.py

doc/python_api/examples/bge.texture.py

doc/python_api/rst/bge.texture.rst

source/gameengine/VideoTexture/blendVideoTex.cpp

BGE: bge.texture API documentation enhancementClosedPublicActions

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List

Diff 4601

doc/python_api/examples/bge.texture.1.py

doc/python_api/examples/bge.texture.py

doc/python_api/rst/bge.texture.rst

source/gameengine/VideoTexture/blendVideoTex.cpp

BGE: bge.texture API documentation enhancement
ClosedPublic
Actions

Revision Contents
Changeset List