improving the Manual


#1

The following is a list of pages from the Manual which are considered “incomplete” or are empty. The list is for the Python versions of the pages. I might add the C++ list later.

If you think you could improve these pages, post in this thread.

Incomplete pages:
----------------------

List of All Attributes: panda3d.org/manual/index.php … Attributes
Alpha Testing: panda3d.org/manual/index.php/Alpha_Testing
Clip Planes: panda3d.org/manual/index.php/Clip_Planes
Portal Culling: panda3d.org/manual/index.php/Portal_Culling
Transparency and Blending: panda3d.org/manual/index.php … d_Blending
Cg Shader Tutorial: panda3d.org/manual/index.php … r_Tutorial
Multi-Channel: panda3d.org/manual/index.php/Multi-Channel
The Heightfield Tesselator: panda3d.org/manual/index.php … Tesselator
Low-Level Render to Texture: panda3d.org/manual/index.php … to_Texture
Using the Particle Panel: panda3d.org/manual/index.php … icle_Panel
Joystick Support: panda3d.org/manual/index.php … ck_Support
Types of forces: panda3d.org/manual/index.php/Types_of_forces
Simulating the Physics World: panda3d.org/manual/index.php … sics_World
Attaching Bodies using Joints: panda3d.org/manual/index.php … ing_Joints
The Global Clock: panda3d.org/manual/index.php … obal_Clock
File Reading: panda3d.org/manual/index.php/File_Reading
Sample Programs in the Distribution: panda3d.org/manual/index.php … stribution – missing sample: “Distortion”.
Sample Programs: Roaming Ralph: panda3d.org/manual/index.php … ming_Ralph – actually it’s the sample that needs updating
Performance Tuning: panda3d.org/manual/index.php … nce_Tuning
Performance Issue: Miscellaneous: panda3d.org/manual/index.php … cellaneous
Reference Counting: panda3d.org/manual/index.php … e_Counting

Empty pages:
----------------------

[color=cyan]Loading Particle Systems: panda3d.org/manual/index.php … le_Systems -ADDED
Math Engine: panda3d.org/manual/index.php/Math_Engine
Performance Issue: Too Many State Changes: panda3d.org/manual/index.php … te_Changes
Performance Issue: Excessive Fill: panda3d.org/manual/index.php … ssive_Fill
Performance Issue: Memory Full: panda3d.org/manual/index.php … emory_Full
[color=cyan]Performance Issue: Python Calculation: panda3d.org/manual/index.php … alculation -ADDED
Performance Issue: Failure to Garbage Collect: panda3d.org/manual/index.php … ge_Collect
Performance Issue: Collision System Misuse: panda3d.org/manual/index.php … tem_Misuse
Performance Issue: Motherboard Integrated Video: panda3d.org/manual/index.php … ated_Video
[color=cyan]Performance Issue: Too Many Polygons: panda3d.org/manual/index.php … y_Polygons -ADDED
Converting from SoftImage: panda3d.org/manual/index.php … _SoftImage

I would like to give extra attention to the Cg Tutorial. It was meant to be a 12 part tutorial, but only the first 2 parts were added to the manual. However, the code for the other parts are written and can be accessed from the following links:
panda3d.org/manual/index.php … ial_Part_3
panda3d.org/manual/index.php … ial_Part_4
panda3d.org/manual/index.php … ial_Part_5
panda3d.org/manual/index.php … ial_Part_6
panda3d.org/manual/index.php … ial_Part_7
panda3d.org/manual/index.php … ial_Part_8
panda3d.org/manual/index.php … ial_Part_9
panda3d.org/manual/index.php … al_Part_10
panda3d.org/manual/index.php … al_Part_11
panda3d.org/manual/index.php … al_Part_12

The code is very well documented.
So all is left is to write the text and add the pages to the toc.


#2

I will try to find some time to finish the portal culling page (I wrote what is currently there).
Also I’ve been meaning to submit a patch for the multi channel audio so it can use any speaker config that FMOD supports (not just 2.0 and 5.1), so I can write up the multi channel page when I do that.


#3

Looking forward to it. Please also write the C++ versions of the pages if you have the required knowledge.


#4

Okay, I went through all the manual pages, fixing bunch of typos. First post updated.

Artificial Intelligence (PANDAI) pages don’t seem to use the standard way of text formatting. Also these pages link to Youtube videos, which I think is a very bad idea as Youtube is blocked in some countries. Could they be reuploaded to Panda’s servers or Vimeo?

Also the Bullet pages and PandaAI pages have download links from other sites like googlecode and p3dp, I don’t think you can be too sure that they won’t get removed (accidentally) in the future.

Also I’m thinking a page which explains what each library in the bin folder is for would be useful, for those people who want to squeeze few megabytes from their game. The manual already has such a list for the executables in that folder. panda3d.org/manual/index.php … xecutables

panda3d.org/manual/index.php … r_Lectures has the same links as the previous page, makes me wonder if the page is needed.

Also, the offline manual doesn’t seem to render correctly in Firefox: i.imgur.com/5r4ft.jpg

Finally, I noticed that some pages have code in

 tags, while others have them in  tags. Is the first for code which is for both Python and C++ pages? Because some manual pages don’t seem to follow this rule.
      

#5

You’d have to talk to the people maintaining PandAI about the PandAI manual pages. We don’t maintain PandAI.

Good idea on the page explaining the Panda libraries.

 is the old notation, before we had syntax highlighting in the manual.  The pages simply haven't been updated yet.

#6

So what should I replace the tags with? ? Will it still show up the same way in the C++ versions of the manual?

Also, i think I could write the “Performance Issue: Python Calculation” page. I could write about the performance issues when generating vertices and pixels with Python or reading them from files and ways to improve the performance. Would that be enough?

I could use some explaining myself. I don’t know much and I’m not sure if I know it right.

avcodec-53.dll         - 
avdevice-53.dll        - 
avfilter-2.dll         - 
avformat-53.dll        - 
avutil-51.dll          - 
cg.dll                 - Cg runtime
cgD3D10.dll            - I thought Panda3d doesn't use DX10 and 11, are these two needed?
cgD3D11.dll            - 
cgD3D8.dll             - Also shaders and ShaderGenerator don't work in DX8/9 mode, are these also needed?
cgD3D9.dll             - 
cgGL.dll               - Cg for OpenGL
cv100.dll              - 
cvaux100.dll           - 
cvcam100.dll           - 
cxcore100.dll          - 
cxts001.dll            - 
d3dx9_37.dll           - 
fmodex.dll             - 
fmodexL.dll            - 
highgui100.dll         - 
libguide40.dll         - 
libp3direct.dll        - 
libp3dtool.dll         - 
libp3dtoolconfig.dll   - 
libp3fmod_audio.dll    - 
libp3framework.dll     - 
libp3glstuff.dll       -  
libp3mayaloader2008.dll- 
libp3mayaloader2009.dll- 
libp3mayaloader2010.dll- 
libp3mayaloader2011.dll- 
libp3mayaloader2012.dll- 
libp3mayaloader6.dll   - 
libp3mayaloader65.dll  - 
libp3mayaloader7.dll   - 
libp3mayaloader8.dll   - 
libp3mayaloader85.dll  - 
libp3openal_audio.dll  - OpenAL audio library wrapper
libp3ptloader.dll      - 
libp3pystub.dll        - 
libp3vision.dll        - 
libp3windisplay.dll    - 
libpanda.dll           - main Panda3d library
libpandaai.dll         - PandaAI
libpandabullet.dll     - Bullet physics engine
libpandadx8.dll        - Panda3d DirectX 8 renderer
libpandadx9.dll        - Panda3d DirectX 9 renderer
libpandaegg.dll        - 
libpandaexpress.dll    - 
libpandafx.dll         - 
libpandagl.dll         - Panda3d openGL renderer
libpandaode.dll        - ODE physics engine wrapper
libpandaphysics.dll    - Panda3d phyiscs engine
libpandaphysx.dll      - PhysX physics engine
libpandaskel.dll       - 
libpandatiff.dll       - 
libtinydisplay.dll     - Panda3d software renderer
mfc90.dll              - 
mfc90u.dll             - 
mfcm90.dll             - 
mfcm90u.dll            - 
ml100.dll              - 
msvcm80.dll            - 
msvcm90.dll            - 
msvcp80.dll            - 
msvcp90.dll            - 
msvcr80.dll            - 
msvcr90.dll            - 
msvcrt.dll             - 
ode.dll                - ODE physics engine
OpenAL32.dll           - OpenAL audio library
postproc-51.dll        - 
python2X.dll           - Panda's local Python
swscale-2.dll          - 

#7

The questions you asked are answered by the editing guidelines, which of course you’ve read before making any modifications:
panda3d.org/manual/index.php/Talk:Main_page

As for the libraries, to the best of my knowledge:

avcodec-53.dll         - Part of ffmpeg, linked into the core, so don't remove it
avdevice-53.dll        - Part of ffmpeg.  We don't use this one.
avfilter-2.dll         - Same, we don't use this one either.
avformat-53.dll        - Part of ffmpeg, linked into the core, so don't remove it
avutil-51.dll          - Part of ffmpeg, linked into the core, don't remove
cg.dll                 - Cg runtime
cgD3D10.dll            - Cg+DX10, you can remove this
cgD3D11.dll            - You can remove this, too
cgD3D8.dll             - Same
cgD3D9.dll             - Cg for DirectX 9
cgGL.dll               - Cg for OpenGL
cv100.dll              - Part of OpenCV, linked into the p3vision module
cvaux100.dll           - Same
cvcam100.dll           - Same
cxcore100.dll          - Same
cxts001.dll            - I have no idea.
d3dx9_37.dll           - Part of DirectX 9 runtime
fmodex.dll             - FMOD EX sound system
fmodexL.dll            - Same, but I don't think we use this one
highgui100.dll         - Part of OpenCV, linked into p3vision
libguide40.dll         - I don't remember.  Maya? Or OpenCV?
libp3direct.dll        - Contains various modules like the interval system
libp3dtool.dll         - Core of Panda, don't remove
libp3dtoolconfig.dll   - Part of Panda's core
libp3fmod_audio.dll    - Panda's FMOD module.
libp3framework.dll     - Not 100% sure if Python users need this one
libp3glstuff.dll       - Important for OpenGL stuff.
libp3mayaloader2008.dll- obvious
libp3mayaloader2009.dll- "
libp3mayaloader2010.dll- "
libp3mayaloader2011.dll- "
libp3mayaloader2012.dll- "
libp3mayaloader6.dll   - "
libp3mayaloader65.dll  - "
libp3mayaloader7.dll   - "
libp3mayaloader8.dll   - "
libp3mayaloader85.dll  - "
libp3openal_audio.dll  - OpenAL audio library wrapper 
libp3ptloader.dll      - Allows you to load .x, ,dxf, etc using loader.loadModel
libp3pystub.dll        - Only needed for the binary tools to run, not the libraries
libp3vision.dll        - Webcam stuff, and OpenCV integration
libp3windisplay.dll    - Needed by display modules on Windows
libpanda.dll           - Contains the gist of the Panda3D stuff
libpandaai.dll         - PandaAI 
libpandabullet.dll     - Bullet physics integration 
libpandadx8.dll        - Panda3D DirectX 8 renderer 
libpandadx9.dll        - Panda3D DirectX 9 renderer 
libpandaegg.dll        - Egg loader, you can remove this if you don't load eggs
libpandaexpress.dll    - Part of Panda's core
libpandafx.dll         - Some esoteric stuff like special lenses
libpandagl.dll         - Panda3d OpenGL renderer 
libpandaode.dll        - ODE physics engine wrapper 
libpandaphysics.dll    - Panda3D's internal physics engine 
libpandaphysx.dll      - PhysX physics engine integration
libpandaskel.dll       - Example module, you don't need this.
libpandatiff.dll       - Loads tiff images, I think it's linked into the core
libtinydisplay.dll     - Panda3D software renderer 
mfc90.dll              - Microsoft Foundation Class
mfc90u.dll             - "
mfcm90.dll             - "
mfcm90u.dll            - "
ml100.dll              - OpenCV stuff again
msvcm80.dll            - MS standard library
msvcm90.dll            - "
msvcp80.dll            - "
msvcp90.dll            - "
msvcr80.dll            - "
msvcr90.dll            - "
msvcrt.dll             - "
ode.dll                - ODE physics engine 
OpenAL32.dll           - OpenAL audio library 
postproc-51.dll        - An ffmpeg library we don't use
python2X.dll           - Just a copy snatched from the Python installation
swscale-2.dll          - Part of ffmpeg, we do use this

#8

Certainly, however I’m not sure my question is addressed there. The page says to put language specific stuff in [langauge][/language] tags and they will be displayed only if you are in that language version of the page.
Then it says to use this tag to highlight the language specific syntax. However, it does not mention if I should replace

 tags with the  tags if I’m only going to add for a single language. The manual page says you can use [func][/func] tags to let the manual try to convert to the other langauge itself, however I’m not sure if it’s meant for complete code snippets or just class/function names.

I’ll write the Python calculations page if you don’t mind then.

Thanks. However, I think we need just a little bit more accurate info before adding the page.

When you say this, does this mean it is never used by Panda? Why is it included in the SDK then in the first place?

Not so obvious for me (not a Maya user).
Also, the quotation marks mean same as above, or unknown?


#9

Performance Issue: Too Many Polygons: panda3d.org/manual/index.php/Preusser


#10

Looks good. Maybe it would be helpful to add in a little section explaining how to determine whether the slowdown is really caused by a too large amount of geoms or polygons, and whether or not animations are the bottleneck; both of which can be analysed using PStats.

You need to highlight Python code. So yes, all Python code should be enclosed in tags and not

 tags.


#11

I think people should find out if they use too many meshes in the “Too Many Meshes” page instead, which is linked from this page. Skinning doesn’t seem to have it’s own page though, so it could go here.


#12

OK, I’ve edited the sentence to make clear that getting the number of Geoms is explained in the “Too Many Meshes” page. However I couldn’t find out how to get the time it takes on the Geoms alone or the time that is spent on skinning in PStats.

BTW, how do you create a new page in the manual?


#13

Type it into the URL bar as if it already existed, then click edit.


#14

In general, there aren’t good ways to measure the time it takes to render the Geoms alone. Panda only sends the render calls to the graphics driver, which renders the scene. There aren’t calipers inside the graphics driver to measure what it is doing (at least, none available to Panda). We can time the actual sending of the render calls, but that tells us very little about why it takes the time it does–is it too many vertices, too many pixels, or too many geoms? No way to tell just from one measurement.

To actually determine what is going on requires a bit of intuition and detective work. For instance, reducing the size of the window gives you one data point, by reducing the number of pixels without affecting anything else. If this improves performance, you know you have a bottleneck that’s related to pixels (either too much depth complexity or too complex a pixel shader).

Similarly, you can try calling flattenStrong() on a scene to reduce the number of Geoms without affecting anything else. (This only works on certain scenes, of course.) If this improves performance, you know you have a bottleneck that’s related to geom count.

As for skinning, if by this you mean the time Panda spends computing the vertices for animation, that can be read in PStats in the “*:Animation” category, with a separate entry for each differently-named character.

David


#15

Hm OK.
I see a graph even when I use hardware skinning. But how does Panda know how long it takes for the GPU?
BTW, in what state is the hardware skinning support? The prc variable says it’s not quite ready, but I haven’t had problems with it. Could it just be an outdated comment?

And why is the “*” category in PStats named like that?


#16

If you see any time spent in “skinning”, then you’re not using hardware skinning. This category shows the time spent to compute vertices on the CPU.

In fact, hardware skinning is really not supported for most modern hardware. The current implementation in Panda relies on a somewhat outdated fixed-function OpenGL extension. It’s still present on some computers, but can only handle extremely limited characters (like with only four bones). More than that, and it will fall over into software skinning. One day we may offer a shader-based implementation as well (but it will have its own set of limitations, as these things always do).

You can also prove where the skinning is being computed by setting “show-animated-vertices 1” in your Config.prc file; this will flash vertices red when they are animated on the CPU, and blue when they are animated on the GPU.

The “" category is intended for the general overhead category. These are things that might be computed in either App or Cull, or possibly in another thread altogether, depending on your setup. It was originally intended that the "” category would be automatically mapped into the appropriate toplevel category based on its runtime determination, but this feature wasn’t added.

David


#17

Hm, OK. I’ve updated the page. panda3d.org/manual/index.php/Preusser
Is there anything else I can add?

I think the “*” category caused and will cause some confusion unless the manual page gets updated or the code gets implemented.


#18

Why is it confusing? Should it be called something else instead?


#19

Does the asterisk mean anything here?


#20

Yes, it means “None of the above.” Neither App, nor Cull, nor Draw; and yet it’s not its own category either. Calling it something like “Overhead” might make it appear to be equally important to App, Cull, and Draw, which it isn’t really.

David