documents moved to CMU wiki: www.panda3d.org

2025-10-05 11:28:17 -04:00 · 2005-05-02 16:55:03 +00:00 · 2005-05-02 16:55:03 +00:00 · ab21c536ad
commit ab21c536ad
parent 856a53bd5c
3 changed files with 0 additions and 756 deletions
--- a/panda/src/doc/howto.fix_transparency_issues.txt
+++ b/panda/src/doc/howto.fix_transparency_issues.txt
@ -1,110 +0,0 @@
 HOW TO FIX TRANSPARENCY ISSUES
 Usually transparency works as expected in Panda automatically, but
 sometimes it just seems to go awry, where a semitransparent object in
 the background seems to partially obscure a semitransparent object in
 front of it.  This is especially likely to happen with large flat
 polygon cutouts, or when a transparent object is contained within
 another transparent object, or when parts of a transparent object can
 be seen behind other parts of the same object.
 The fundamental problem is that correct transparency, in the absence
 of special hardware support involving extra framebuffer bits, requires
 drawing everything in order from farthest away to nearest.  This means
 sorting each polygon--actually, each pixel, for true correctness--into
 back-to-front order before drawing the scene.
 It is, of course, impossible to split up every transparent object into
 individual pixels or polygons for sorting individually, so Panda sorts
 objects at the Geom level, according to the center of the bounding
 volume.  This works well 95% of the time.
 You run into problems with large flat polygons, though, since these
 tend to have parts that are far away from the center of their bounding
 volume.  The bounding-volume sorting is especially likely to go awry
 when you have two or more large flats close behind the other, and you
 view them from slightly off-axis.  (Try drawing a picture, of the two
 flats as seen from the top, and imagine yourself viewing them from
 different directions.  Also imagine where the center of the bounding
 volumes is.)
 Now, there are a number of solutions to this sort of problem.  No one
 solution is right for every situation.
 First, the easiest thing to do is to use M_dual transparency.  This is
 a special transparency mode in which the completely invisible parts of
 the object aren't drawn into the Z-buffer at all, so that they don't
 have any chance of obscuring things behind them.  This only works well
 if the flats are typical cutouts, where there is a big solid part
 (alpha == 1.0) and a big transparent part (alpha == 0.0), and not a
 lot of semitransparent parts (0.0 < alpha < 1.0).  It is also a
 slightly more expensive rendering mode than the default of M_alpha, so
 it's not enabled by default in Panda.  But egg-palettize will turn it
 on automatically for a particular model if it detects textures that
 appear to be cutouts of the appropriate nature, which is another
 reason to use egg-palettize if you are not using it already.
 If you don't use egg-palettize (you really should, you know), you can
 just hand-edit the egg files to put the line:
  <Scalar> alpha { dual }
 within the <Texture> reference for the textures in question.
 A second easy option is to use M_multisample transparency, which
 doesn't have any ordering issues at all, but it only looks good on
 very high-end cards that have special multisample bits to support
 full-screen antialiasing.  Also, at the present it only looks good on
 these high-end cards in OpenGL mode (since our pandadx drivers don't
 support M_multisample explicitly right now).  But if M_multisample is
 not supported by a particular hardware or panda driver, it
 automatically falls back to M_binary, which also doesn't have any
 ordering issues, but it always has jaggy edges along the cutout edge.
 This only works well on texture images that represent cutouts, like
 M_dual, above.
 If you use egg-palettize, you can engage M_multisample mode by putting
 the keyword "ms" on the line with the texture(s).  Without
 egg-palettize, hand-edit the egg files to put the line:
  <Scalar> alpha { ms }
 within the <Texture> reference for the textures in question.
 A third easy option is to chop up one or both competing models into
 smaller pieces, each of which can be sorted independently by Panda.
 For instance, you can split one big polygon into a grid of little
 polygons, and the sorting is more likely to be accurate for each piece
 (because the center of the bounding volume is closer to the pixels).
 You can draw a picture to see how this works.  In order to do this
 properly, you can't just make it one big mesh of small polygons, since
 Panda will make a mesh into a single Geom of tristrips; instead, it
 needs to be separate meshes, so that each one will become its own
 Geom.  Obviously, this is slightly more expensive too, since you are
 introducing additional vertices and adding more objects to the sort
 list; so you don't want to go too crazy with the smallness of your
 polygons.
 A fourth option is simply to disable the depth write on your
 transparent objects.  This is most effective when you are trying to
 represent something that is barely visible, like glass or a soap
 bubble.  Doing this doesn't improve the likelihood of correct sorting,
 but it will tend to make the artifacts of an incorrect sorting less
 obvious.  You can achieve this by using the transparency option
 "blend_no_occlude" in an egg file, or by explicitly disabling the
 depth write on a loaded model with node_path.set_depth_write(false).
 You should be careful only to disable depth write on the transparent
 pieces, and not on the opaque parts.
 A final option is to make explicit sorting requests to Panda.  This is
 often the last resort because it is more difficult, and doesn't
 generalize well, but it does have the advantage of not adding
 additional performance penalties to your scene.  It only works well
 when the transparent objects can be sorted reliably with respect to
 everything else behind them.  For instance, clouds in the sky can
 reliably be drawn before almost everything else in the scene, except
 the sky itself.  Similarly, a big flat that is up against an opaque
 wall can reliably be drawn after all of the opaque objects, but before
 any other transparent object, regardless of where the camera happens
 to be placed in the scene.  See howto.control_render_order.txt for
 more information about explicitly controlling the rendering order.
--- a/panda/src/doc/howto.use_multitexture.txt
+++ b/panda/src/doc/howto.use_multitexture.txt
@ -1,243 +0,0 @@
 MULTITEXTURE OVERVIEW
 Modern graphics cards are capable of applying more than one texture
 image at once to geometry as they render polygons.  This capability is
 referred to as multitexture.
 The textures are applied in a pipeline fashion, where the output of
 each texturing operation is used as the input to the next.  A
 particular graphics card will have a certain number of texture units
 dedicated to this function, which limits the number of textures that
 may be pipelined in this way.
 To apply a texture in Panda, you must have a Texture object (which you
 might have loaded from disk, or extracted from a model) and a
 TextureStage object (which you can create on-the-fly).  The primary
 call to add a texture to the pipeline is:
  nodepath.set_texture(texture_stage, texture);
 This adds the indicated texture into the pipeline for all the geometry
 at nodepath level and below, associating it with the indicated
 TextureStage object.
 The purpose of the TextureStage object is to represent a single stage
 in the texture pipeline.  You can create as many TextureStage objects
 as you like; each one can associate a different texture, and each of
 those textures will be applied together (within the limits of your
 hardware).  If you want to change out a particular texture within the
 pipeline without disturbing the others, keep a handle to the
 TextureStage object that you used for that stage, and issue a
 set_texture() call using the same TextureStage object and a different
 texture--this replaces the texture that you assigned previously.  (You
 may do this on the same NodePath, or on a lower NodePath level to
 override the texture specified from above.)
 To undo a set_texture() call for a particular stage or for all stages,
 do:
  nodepath.clear_texture(texture_stage)
  nodepath.clear_texture()
 Don't confuse this with the calls to actively disable a particular
 texture stage or to disable texturing altogether, which are:
  nodepath.set_texture_off(texture_stage)
  nodepath.set_texture_off()
 The difference between the two is that set_texture_off() inserts a
 command into the scene graph to specifically turn off the texture
 associated with the indicated texture stage, while clear_texture()
 simply removes the texture stage from this node's list of assigned
 textures.  Use clear_texture() to undo a previous call to
 set_texture() on a given node.  You need set_texture_off() more
 rarely; you might use this when you want to override a particular
 setting from above to turn off just one particular stage of the
 pipeline (for instance, you may have a set_texture() applied at the
 root of a scene to apply a particular effect to everything in the
 scene, but use set_texture_off() on one particular model for which you
 don't want that effect applied).
 There is also a default TextureStage object that is used for all of
 the old single-texture Panda interfaces (like
 nodepath.set_texture(texture)).  It is also the TextureStage that will
 be used to apply Textures onto models (e.g. egg files and/or bam
 files) that do not specify the use of multitexturing.  This default
 TextureStage can be accessed by TextureStage::get_default().
 There are a number of different blend modes that you may specify for
 each texture stage in the pipeline; these are specified with
 texture_stage.set_mode().  The mode may be one of:
     TextureStage::M_modulate
       Multiplies the incoming color by the texture color.  This
       allows the texture to darken, but not brighten, the incoming
       color.
     TextureStage::M_add
       Adds the incoming color and the texture color.  This allows the
       texture to brighten, but not darken, the incoming color, and
       tends to lead to bright, desaturated colors.
     TextureStage::M_decal
       Shows the texture color where the texture is alpha = 1, and the
       incoming color where the texture is alpha = 0.  This can be
       used to paint a texture on top of the existing texture.
     TextureStage::M_blend
       Defined for grayscale textures only.  You can specify an
       arbitrary color as a separate parameter with
       texture_stage.set_color(), and then the result of M_blend is to
       produced the specified color where the texture is white, and
       the incoming color where the texture is black.  This can be
       used to paint arbitrary color stripes or a similar effect over
       an existing texture.
     TextureStage::M_blend_color_scale
       This is identical to M_blend, except that the blend color,
       specified by texture_stage.set_color(), is also modified by the
       color scale applied to the scene graph.
     TextureStage::M_replace
       Completely replaces the incoming color with the texture color;
       probably not terribly useful in a multitexture environment,
       except for the first texture stage.
     TextureStage::M_combine
       This mode supercedes most of the above with a more powerful
       collection of options, including signed add and/or subtract,
       and linear interpolation between two different colors using a
       third parameter.  You can specify the input(s) as one or more
       combinations of a specified constant color, or the previous
       texture in the pipeline, or the incoming color.  However, very
       old graphics drivers may not support this mode.
       Since combine mode has a number of associated parameters, you
       enable this mode by calling set_combine_rgb() and
       set_combine_alpha() with the appropriate parameters; it's not
       necessary to call set_mode(M_combine).  A complete description
       of this mode is not given here.
 Some of the above modes are very order-dependent.  For this reason,
 you may use texture_stage.set_sort() to specify the order in which
 textures should be applied, using an integer sort parameter.  When
 Panda collects the textures together for rendering a particular piece
 of geometry, it will sort them in order from lowest sort value to
 highest sort value.  The default sort value is 0.  Thus, you can
 specify a large positive number to apply a texture on top of existing
 textures, or a large negative number to apply it beneath existing
 textures.  
 The egg loader will create texture stages automatically in the
 presence of a multitexturing specification in the egg file, and it
 will assign to these stages sort values in multiples of 10: the lowest
 texture stage will have a sort value of 0, the next 10, the next 20,
 and so on.
 Since the number of texture units available on the hardware is
 limited, and is usually a small number (and some hardware doesn't
 support multitexturing at all, so effectively has only one texture
 unit), Panda needs some rule for selecting the subset of textures to
 render when you have requested more texture stages than are available.
 For this Panda relies on the texture_stage.set_priority() value, which
 is an integer value that represents the importance of this particular
 texture.  If the requested textures will not fit on the available
 number of texture units, Panda will select the n textures with the
 highest priority (and then sort them into order by the set_sort()
 parameter).  Between two textures with the same priority, Panda will
 prefer the one with the lower sort value.  The default priority is 0.
 If you need to know the actual limit, you can query your available
 number of texture stages from the GraphicsStateGuardian, with the call
 gsg->get_max_texture_stages() (e.g. from Python, call
 base.win.getGsg().getMaxTextureStages()).
 TEXTURE COORDINATES
 In many cases, all of the texture stages need to use the same set of
 texture coordinates, which is the default behavior.  You can also
 apply a different texture matrix on some texture stages to apply a
 linear transformation to the texture coordinates (for instance, to
 position a decal on the surface).
  nodepath.set_tex_offset(texture_stage, u_offset, v_offset);
  nodepath.set_tex_scale(texture_stage, u_scale, v_scale);
  nodepath.set_tex_rotate(texture_stage, degrees);
  nodepath.set_tex_transform(texture_stage, general_transform);
 These operations accumulate through nested nodes just like standard
 scene graph transforms.  In fact, you can get and set relative texture
 transforms:
  rel_offset = nodepath.get_tex_offset(other, texture_stage);
  nodepath.set_tex_scale(other, texture_stage, u_scale, v_scale);
  (etc.)
 You may create LerpIntervals to lerp texture matrices.  There are no
 interval types that operate directly on a texture matrix, but you can
 set up a TexProjectorEffect to bind a node's transform to the texture
 matrix:
  nodepath.set_tex_projector(texture_stage, from, to)
 Where "from" and "to" are arbitrary NodePaths.  The TexProjectorEffect
 will measure the relative transform between "from" and "to" each frame
 and apply it to the nodepath's texture matrix.  Once this is in place,
 you may create a LerpPosInterval, or any other Panda construct, to
 adjust either the "from" or the "to" NodePath, which will thus
 indirectly adjust the texture matrix by the same amount.
 Sometimes, a texture stage may need to use a completely different set
 of texture coordinates, for instance as provided by the artist who
 generated the model.  Panda allows a model to store any number of
 different sets of texture coordinates on its vertices, each with a
 unique name.  You can associate any texture stage with any set of
 texture coordinates you happen to have available on your model:
  texture_stage.set_texcoord_name(name)
 Finally, you may need to generate texture coordinates for a particular
 texture stage on the fly.  This is particularly useful, for instance,
 to apply reflection maps, e.g. sphere maps or cube maps.  To enable
 this effect, use:
  nodepath.set_tex_gen(texture_stage, mode)
 Where mode is one of the enumerated types named by TexGenAttrib::Mode;
 at the present, this may be any of M_world_position,
 M_object_position, M_eye_position, or M_sphere_map.  The first three
 modes simply apply the X, Y, Z coordinates of the vertex to its U, V
 texture coordinates (a texture matrix may then be applied to transform
 the generated texture coordinates into the particular U, V coordinate
 space that you require).  The remaining modes generate texture
 coordinates appropriate to a reflection map of the corresponding type,
 based on the position and normal of each vertex, relative to the
 camera.
 The texture generation mode and the tex projector mode may be combined
 to provide hardware-assisted projective texturing, where a texture is
 applied to geometry as if it were projected from a particular point in
 space, like a slide projector.  This is particularly useful for
 applying shadow maps or flashlight effects, for instance.  There is a
 convenience function on NodePath that automatically makes the three
 separate calls needed to enable projective texturing:
  nodepath.project_texture(texture_stage, texture, projector);
 Where projector is a NodePath that references a LensNode.  The
 indicated texture is applied to the geometry at nodepath and below, as
 if it were projected from the indicated projector.  The lens
 properties such as field of view may be adjusted on the fly to adjust
 the projection.
 (Note that Panda also provides a ProjectionScreen object, which
 performs an effect very similar to the project_texture() call, except
 that it is performed entirely in the CPU, whereas project_texture()
 will offload the work onto the graphics card if the card supports
 this.  This may or may not result in a performance improvement over
 ProjectionScreen, depending on the nature of your scene and your CPU
 load versus your graphics card load.)
--- a/panda/src/doc/howto.use_pstats
+++ b/panda/src/doc/howto.use_pstats
@ -1,403 +0,0 @@
 QUICK INTRODUCTION
 PStats is Panda's built-in performance analysis tool.  It can graph
 frame rate over time, and can further graph the work spent within each
 frame into user-defined subdivisions of the frame (for instance, app,
 cull and draw), and thus can be an invaluable tool in identifying
 performance bottlenecks.  It can also show frame-based data that
 reflects any arbitrary quantity other than time intervals, for
 instance, texture memory in use or number of vertices drawn.
 The performance graphs may be drawn on the same computer that is
 running the Panda client, or they may be drawn on another computer on
 the same LAN, which is useful for analyzing fullscreen applications.
 The remote computer need not be running the same operating system as
 the client computer.
 To use PStats, you first need to build the PStats server program,
 which is part of the Pandatool tree (it's called pstats.exe on
 Windows, and gtk-stats on a Unix platform).  Start by running the
 PStats server program (it runs in the background), and then start your
 Direct/Panda client with the following in your Config.prc file:
  want-pstats 1
 Or, at runtime, issue the Python command:
  PStatClient.connect()
 Or if you're running pview, press shift-S.
 Any of the above will contact your running PStats server program,
 which will proceed to open a window and start a running graph of your
 client's performance.  If you are running the server on a different
 machine than the client, add the pstats-host variable to your client's
 Config.prc file, naming the hostname or IP address of the machine
 running the PStats server.
 If you are developing Python code, you may be interested in reporting
 the relative time spent within each Python task (by subdividing the
 total time spent in Python, as reported under "Show Code").  To do
 this, add the following lines to your Config.prc file before you start
 ShowBase:
  task-timer-verbose 1
  pstats-tasks 1
 THE PSTATS SERVER (The user interface)
 The GUI for managing the graphs and drilling down to view more detail
 is entirely controlled by the PStats server program.  At the time of
 this writing, there are two different versions of the PStats server,
 one for Unix called gtk-stats and one for Windows called simply
 pstats.  The interfaces are similar but not identical; the following
 paragraphs describe the Windows version.
 When you run pstats.exe, it adds a program to the taskbar but does not
 immediately open a window.  The program name is typically "PStats
 5185", showing the default PStats TCP port number of 5185; see "HOW IT
 WORKS" below for more details about the TCP communication system.  For
 the most part you don't need to worry about the port number, as long
 as server and client agree (and the port is not already being used by
 another application).
 Each time a client connects to the PStats server, a new monitor window
 is created.  This monitor window owns all of the graphs that you
 create to view the performance data from that particular connection.
 Initially, a strip chart showing the frame time of the main thread is
 created by default; you can create additional graphs by selecting from
 the Graphs pulldown menu.
 Time-based Strip Charts
 This is the graph type you will use most frequently to examine
 performance data.  The horizontal axis represents the passage of time;
 each frame is represented as a vertical slice on the graph.  The
 overall height of the colored bands represents the total amount of
 time spent on each frame; within the frame, the time is further
 divided into the primary subdivisions represented by different color
 bands (and labeled on the left).  These subdivisions are called
 "collectors" in the PStats terminology, since they represent time
 collected by different tasks.
 Normally, the three primary collectors are App, Cull, and Draw, the
 three stages of the graphics pipeline.  Atop these three colored
 collectors is the label "Frame", which represents any remaining time
 spent in the frame that was not specifically allocated to one of the
 three child collectors (normally, there should not be significant time
 reported here).
 The frame time in milliseconds, averaged over the past three seconds,
 is drawn above the upper right corner of the graph.  The labels on the
 guide bars on the right are also shown in milliseconds; if you prefer
 to think about a target frame rate rather than an elapsed time in
 milliseconds, you may find it useful to select "Hz" from the Units
 pulldown menu, which changes the time units accordingly.
 The running Panda client suggests its target frame rate, as well as
 the initial vertical scale of the graph (that is, the height of the
 colored bars).  You can change the scale freely by clicking within the
 graph itself and dragging the mouse up or down as necessary.  One of
 the horizontal guide bars is drawn in a lighter shade of gray; this
 one represents the actual target frame rate suggested by the client.
 The other, darker, guide bars are drawn automatically at harmonic
 subdvisions of the target frame rate.  You can change the target frame
 rate with the Config.prc variable pstats-target-frame-rate on the
 client.
 You can also create any number of user-defined guide bars by dragging
 them into the graph from the gray space immediately above or below the
 graph.  These are drawn in a dashed blue line.  It is sometimes useful
 to place one of these to mark a performance level so it may be
 compared to future values (or to alternate configurations).
 The primary collectors labeled on the left might themselves be further
 subdivided, if the data is provided by the client.  For instance, App
 is often divided into Show Code, Animation, and Collisions, where Show
 Code is the time spent executing any Python code, Animation is the
 time used to compute any animated characters, and Collisions is the
 time spent in the collision traverser(s).
 To see any of these further breakdowns, double-click on the
 corresponding colored label (or on the colored band within the graph
 itself).  This narrows the focus of the strip chart from the overall
 frame to just the selected collector, which has two advantages.
 Firstly, it may be easier to observe the behavior of one particular
 collector when it is drawn alone (as opposed to being stacked on top
 of some other color bars), and the time in the upper-right corner will
 now reflect just the total time spent within just this collector.
 Secondly, if there are further breakdowns to this collector, they will
 now be shown as further colored bars.  As in the Frame chart, the
 topmost label is the name of the parent collector, and any time shown
 in this color represents time allocated to the parent collector that
 is not accounted for by any of the child collectors.
 You can further drill down by double-clicking on any of the new
 labels; or double-click on the top label, or the white part of the
 graph, to return back up to the previous level.
 Value-based Strip Charts
 There are other strip charts you may create, which show arbitrary
 kinds of data per frame other than elapsed time.  These can only be
 accessed from the Graphs pulldown menu, and include things such as
 texture memory in use and vertices drawn.  They behave similarly to
 the time-based strip charts described above.
 Piano Roll Charts
 This graph is used less frequently, but when it is needed it is a
 valuable tool to reveal exactly how the time is spent within a frame.
 The PStats server automatically collects together all the time spent
 within each collector and shows it as a single total, but in reality
 it may not all have been spent in one continuous block of time.
 For instance, when Panda draws each display region in single-threaded
 mode, it performs a cull traversal followed by a draw traversal for
 each display region.  Thus, if your Panda client includes multiple
 display regions, it will alternate its time spent culling and drawing
 as it processes each of them.  The strip chart, however, reports only
 the total cull time and draw time spent.
 Sometimes you really need to know the sequence of events in the frame,
 not just the total time spent in each collector.  The piano roll chart
 shows this kind of data.  It is so named because it is similar to the
 paper music roll for an old-style player piano, with holes punched
 down the roll for each note that is to be played.  The longer the
 hole, the longer the piano key is held down.  (Think of the chart as
 rotated 90 degrees from an actual piano roll.  A player piano roll
 plays from bottom to top; the piano roll chart reads from left to
 right.)
 Unlike a strip chart, a piano roll chart does not show trends; the
 chart shows only the current frame's data.  The horizontal axis shows
 time within the frame, and the individual collectors are stacked up in
 an arbitrary ordering along the vertical axis.
 The time spent within the frame is drawn from left to right; at any
 given time, the collector(s) that are active will be drawn with a
 horizontal bar.  You can observe the CPU behavior within a frame by
 reading the graph from left to right.  You may find it useful to
 select "pause" from the Speed pulldown menu to freeze the graph on
 just one frame while you read it.
 Note that the piano roll chart shows time spent within the frame on
 the horizontal axis, instead of the vertical axis, as it is on the
 strip charts.  Thus, the guide bars on the piano roll chart are
 vertical lines instead of horizontal lines, and they may be dragged in
 from the left or the right sides (instead of from the top or bottom,
 as on the strip charts).  Apart from this detail, these are the same
 guide bars that appear on the strip charts.
 The piano roll chart may be created from the Graphs pulldown menu.
 Additional threads
 If the panda client has multiple threads that generate PStats data,
 the PStats server can open up graphs for these threads as well.  Each
 separate thread is considered unrelated to the main thread, and may
 have the same or an independent frame rate.  Each separate thread will
 be given its own pulldown menu to create graphs associated with that
 thread; these auxiliary thread menus will appear on the menu bar
 following the Graphs menu.  At the time of this writing, support for
 multiple threads within the PStats graph is largely theoretical and
 untested.
 HOW TO DEFINE YOUR OWN COLLECTORS
 The PStats client code is designed to be generic enough to allow users
 to define their own collectors to time any arbitrary blocks of code
 (or record additional non-time-based data), from either the C++ or the
 Python level.
 The general idea is to create a PStatCollector for each separate block
 of code you wish to time.  The name which is passed to the
 PStatCollector constructor is a unique identifier: all collectors that
 share the same name are deemed to be the same collector.
 Furthermore, the collector's name can be used to define the
 hierarchical relationship of each collector with other existing
 collectors.  To do this, prefix the collector's name with the name of
 its parent(s), followed by a colon separator.  For instance,
 PStatCollector("Draw:Flip") defines a collector named "Flip", which is
 a child of the "Draw" collector, defined elsewhere.
 You can also define a collector as a child of another collector by
 giving the parent collector explicitly followed by the name of the
 child collector alone, which is handy for dynamically-defined
 collectors.  For instance, PStatCollector(draw, "Flip") defines the
 same collector named above, assuming that draw is the result of the
 PStatCollector("Draw") constructor.
 Note that, because of an unfortunate limitation with the interrogate
 parser, statically-defined PStatCollector objects can't be parsed by
 interrogate.  (In general, interrogate can't parse C++ objects that
 are constructed with parameters at the outermost scoping level.)  As a
 workaround, we usually protect these declarations from interrogate by
 using the syntax #ifndef CPPPARSER .. #endif.
 Once you have a collector, simply bracket the region of code you wish
 to time with collector.start() and collector.stop().  It is important
 to ensure that each call to start() is matched by exactly one call to
 stop().  If you are programming in C++, it is highly recommended that
 you use the PStatTimer class to make these calls automatically, which
 guarantees the correct pairing; the PStatTimer's constructor calls
 start() and its destructor calls stop(), so you may simply define a
 PStatTimer object at the beginning of the block of code you wish to
 time.  If you are programming in Python, you must call start() and
 stop() explicitly.
 When you call start() and there was another collector already started,
 that previous collector is paused until you call the matching stop()
 (at which time the previous collector is resumed).  That is, time is
 accumulated only towards the collector indicated by the innermost
 start() .. stop() pair.
 Time accumulated towards any collector is also counted towards that
 collector's parent, as defined in the collector's constructor
 (described above).
 It is important to understand the difference between collectors nested
 implicitly by runtime start/stop invocations, and the static hierarchy
 implicit in the collector definition.  Time is accumulated in parent
 collectors according to the statically-defined parents of the
 innermost active collector only, without regard to the runtime stack
 of paused collectors.
 For example, suppose you are in the middle of processing the "Draw"
 task and have therefore called start() on the "Draw" collector.  While
 in the middle of processing this block of code, you call a function
 that has its own collector called "Cull:Sort".  As soon as you start
 the new collector, you have paused the "Draw" collector and are now
 accumulating time in the "Cull:Sort" collector.  Once this new
 collector stops, you will automatically return to accumulating time in
 the "Draw" collector.  The time spent within the nested "Cull:Sort"
 collector will be counted towards the "Cull" total time, not the
 "Draw" total time.
 Color and Other Optional Collector Properties
 If you do not specify a color for a particular collector, it will be
 assigned a random color at runtime.  At present, the only way to
 specify a color is to modify
 panda/src/pstatclient/pStatProperties.cxx, and add a line to the table
 for your new collector(s).  You can also define additional properties
 here such as a suggested initial scale for the graph and, for
 non-time-based collectors, a unit name and/or scale factor.  The order
 in which these collectors are listed in this table is also relevant;
 they will appear in the same order on the graphs.  The first column
 should be set to 1 for your new collectors unless you wish them to be
 disabled by default.  You must recompile the client (but not the
 server) to reflect changes to this table.
 HOW IT WORKS (What's actually happening)
 The PStats code is divided into two main parts: the client code and
 the server code.
 The PStats Client
 The client code is in panda/src/pstatclient, and is available to run
 in every Panda client unless it is compiled out.  (It will be compiled
 out if OPTIMIZE is set to level 4, unless DO_PSTATS is also explicitly
 set to non-empty.  It will also be compiled out if NSPR is not
 available, since both client and server depend on the NSPR library to
 exchange data, even when running the server on the same machine as the
 client.)
 The client code is designed for minimal runtime overhead when it is
 compiled in but not enabled (that is, when the client is not in
 contact with a PStats server), as well as when it is enabled (when the
 client is in contact with a PStats server).  It is also designed for
 zero runtime overhead when it is compiled out.
 There is one global PStatClient class object, which manages all of the
 communications on the client side.  Each PStatCollector is simply an
 index into an array stored within the PStatClient object, although the
 interface is intended to hide this detail from the programmer.
 Initially, before the PStatClient has established a connection, calls
 to start() and stop() simply return immediately.
 When you call PStatClient.connect(), the client attempts to contact
 the PStatServer via a TCP connection to the hostname and port named in
 the pstats-host and pstats-port Config.prc variables, respectively.
 (The default hostname and port are localhost and 5185.)  You can also
 pass in a specific hostname and/or port to the connect() call.  Upon
 successful connection and handshake with the server, the PStatClient
 sends a list of the available collectors, along with their names,
 colors, and hierarchical relationships, on the TCP channel.
 Once connected, each call to start() and stop() adds a collector
 number and timestamp to an array maintained by the PStatClient.  At
 the end of each frame, the PStatClient boils this array into a
 datagram for shipping to the server.  Each start() and stop() event
 requires 6 bytes; if the resulting datagram will fit within a UDP
 packet (1K bytes, or about 84 start/stop pairs), it is sent via UDP;
 otherwise, it is sent on the TCP channel.  (Some fraction of the
 packets that are eligible for UDP, from 0% to 100%, may be sent via
 TCP instead; you can specify this with the pstats-tcp-ratio Config.prc
 variable.)
 Also, to prevent flooding the network and/or overwhelming the PStats
 server, only so many frames of data will be sent per second.  This
 parameter is controlled by the pstats-max-rate Config.prc variable and
 is set to 30 by default.  (If the packets are larger than 1K, the max
 transmission rate is also automatically reduced further in
 proportion.)  If the frame rate is higher than this limit, some frames
 will simply not be transmitted.  The server is designed to cope with
 missing frames and will assume missing frames are similar to their
 neighbors.
 The server does all the work of analyzing the data after that.  The
 client's next job is simply to clear its array and prepare itself for
 the next frame.
 The PStats Server
 The generic server code is in pandatool/src/pstatserver, and the
 GUI-specific server code is in pandatool/src/gtk-stats and
 pandatool/src/win-stats, for Unix and Windows, respectively.  (There
 is also an OS-independent text-stats subdirectory, which builds a
 trivial PStats server that presents a scrolling-text interface.  This
 is mainly useful as a proof of technology rather than as a usable
 tool.)
 The GUI-specific code is the part that manages the interaction with
 the user via the creation of windows and the handling of mouse input,
 etc.; most of the real work of interpreting the data is done in the
 generic code in the pstatserver directory.
 The PStatServer owns all of the connections, and interfaces with the
 NSPR library to communicate with the clients.  It listens on the
 specified port for new connections, using the pstats-port Config.prc
 variable to determine the port number (this is the same variable that
 specifies the port to the client).  Usually you can leave this at its
 default value of 5185, but there may be some cases in which that port
 is already in use on a particular machine (for instance, maybe someone
 else is running another PStats server on another display of the same
 machine).
 Once a connection is received, it creates a PStatMonitor class (this
 class is specialized for each of the different GUI variants) that
 handles all the data for this particular connection.  In the case of
 the windows pstats.exe program, each new monitor instance is
 represented by a new toplevel window.  Multiple monitors can be
 active at once.
 The work of digesting the data from the client is performed by the
 PStatView class, which analyzes the pattern of start and stop
 timestamps, along with the relationship data of the various
 collectors, and boils it down into a list of the amount of time spent
 in each collector per frame.
 Finally, a PStatStripChart or PStatPianoRoll class object defines the
 actual graph output of colored lines and bars; the generic versions of
 these include virtual functions to do the actual drawing (the GUI
 specializations of these redefine these methods to make the
 appropriate calls).