Pi3D ES 2.0 Documentation

[Jim Manley]

I had volunteered a while back to help with documentation and a tutorial, and now I can't find the thread where it was discussed. I'm going to push for us to get our own Pi3D subforum as I think once "normal" people (whoever they are! ) are able to use Pi3D, I believe it will become very popular.

IIRC, someone was auto-generating API docs using a Python utility, but I noticed that there still is no Documentation directory in the integration branch on github as is called out in the readme file. It would be nice to have a single file (or, better yet, a web page with links into the corresponding source files, including relative anchors using the # URL syntax) that has all of the Pi3D API signatures (with required and optional arguments identified). An alphabetical listing as well as another organized with related APIs together would be great (if someone can generate one, I'll generate the other).

I noticed that there doesn't seem to be a primitive for a triangle - there's a rectangular plane and a tetrahedron, but curiously, no triangle, the building block of all other OGLES surfaces.

[paddyg]

Jim, the google forum (https://groups.google.com/forum/#!forum/pi3d) is what we use in the absence of a pi3d category here. Your name has been added to it as an interested party so it ought to work for you. We have opted for sphinx which produces nice documentation 'automatically' from docstrings. Tom got it working nicely but the stuff I have been pushing back to github is lacking some of its formatting (It previously looked like the general python web documentation)! Use the search for 'sphinx' on the google forum above and you will see some notes of what I did to get sphinx working (slightly incorrectly) on my pi.

You are right that the link to the documentation that should be on the github ReadMe is no longer there, it's because I am re-using that document, I add it back. It is:
http://pi3d.github.com/html/index.html
You will see that there is now copious documentation so if you are wanting to contribute, have a go at reading some of it and if it doesn't make sense.. fix it!

[paddyg]

Just noticed the last para. There is a Canvas which is a minimal triangular object but it's designed to fill the screen so the 2d_flat shader can draw on it and does a couple of non-standard things. A more general Triangle would be very easy to do based on the Sprite.

[Jim Manley]

Thanks again as usual, Paddy! I fuzzily remembered the Gurgle group just as I was nodding off last night and recalled that's where the sphinx tool for generating docs had been mentioned. I just checked out the link and WHOA!!! Now THAT'S beautiful documentation! It appears from the demos that there are some arguments that are optional and while I haven't looked at every single signature, I didn't see any indication of that in what I did peruse. For example, can a Shape be drawn without specifying a shader and a texture?

One of the reasons I'm volunteering to help with the docs and a tutorial is that I'm pretty good at asking stupid questions that others are either afraid of asking for fear of looking dumb, or that are so obvious that no one else thought to ask them. I'm also fairly talented at doing the kinds of things that newbies do that most developers would never think of doing in a thousand years, so I make an effective test subject who's generally able to break anything without much effort. Marketing types run in wild-eyed fear when they see me coming toward their booths at trade shows ... I don't mean to make them cry, but their products/services just aren't ready for the real world, yet.

I do have to say that Pi3D has been very satisfying to take for a spin and that I haven't found any really glaring problems. Another of my attributes is that unlike many testers, I actually understand the code (once I know where to look ) and I can at least point at potential problems and solutions, if not also actually help solve them (usually more a matter of time than ability - I really do need to decide what I want to be if I grow up! ).

[paddyg]

Jim, I don't think there is such a thing as a stupid question. It often annoys me to see trite answers on stackoverflow: 'look it up in the manual'. 99 times out of 100 google will find the answer far faster than wading through the manual and more often than not it takes you to stackoverflow! I've tried to emulate this process by asking myself stupid questions and answering them in the FAQ, it would have been obviously useless for me to simply answer every FAQ with look it up in the manual.

There are (almost too) many ways to set Shapes up to draw. The draw method needs to have a shader, light and camera specified but if neglect the light and camera it will pick up 'default instances' which most of the time are just what you want. You do, however need to explicitly create the shader so it does the kind of rendering you want, but you can feed that in by various means, many of which also cater for specifying the texture(s) to use as well:
1. set them directly in the Buffer array - the other methods are really just wrappers for this i.e.
myshape.buf[0].shader = myshader
myshape.buf[0].textures = [mytexture]
2. include them at draw time
myshape.draw(myshader, [mytexture])
3. set them beforehand
myshape.set_draw_details((myshader, [mytexture])
4. probably other versions of these specific to different types of shape

Paddy

PS I will copy and paste this into the FAQs!