Browsing Python Source? <Super Noob Q>

Hi!

I’m a total newbie when it comes to Panda3D, so I thought I could browse through some Python source and learn the API. It always seems that I end up looking at C++ source and not Python.

For example, I wanted learn the Egg interface. Here’s a snippet from the manual…

v = EggVertex()
v.setPos(Point3D(0, 0, 0))
poly.addVertex(vp.addVertex(v))

So how do I know that an EggVertex takes Point3D as an arg to set it? I couldn’t find any python source that indicated this. Where is Point3D defined? Does the vertexpool return the vertex you added to the pool? The C++ code looked like it returned a pointer to the pool iteself.

In short, is there any python code that I can look at that would explain the Egg interface? Or any other interface?

Thanks!

There’s not any Python code to read for these wrapped C++ classes, but you can get by once you learn a few simple rules.

Presumably you already know about the general renaming rule, e.g. add_vertex -> addVertex.

You should also know that we rename a few classes for historical reasons. These are the linear math classes:
LPoint3f -> Point3
LPoint3d -> Point3D
LVector3f -> Vec3
LVector3d -> Vec3D
LVecBase3f -> VBase3
LVecBase3d -> VBase3D
LMatrix4f -> Mat4
LMatrix4d -> Mat4D

and similarly for the other LPoint2f, LPoint4f, and LMatrix3f variants.

So, you can look in the C++ code, and browse eggVertex.h, and see the following variants for EggVertex::set_pos():

  INLINE void set_pos(double pos);
  INLINE void set_pos(const LPoint2d &pos);
  INLINE void set_pos(const LPoint3d &pos);
  INLINE void set_pos(const LPoint4d &pos);

which tells you that eggVertex.setPos() can receive a single floating-point number, or a Point2D, Point3D, or Point4D. (The generated API reference should list these too, but unfortunately it doesn’t seem to show all of the overloads for a given function; this needs to be fixed.)

A simpler answer is to type, at your Python prompt:

help(v.setPos)

and you should see something like this:

>>> help(v.setPos)
Help on built-in function setPos:

setPos(...)
    C++ Interface:
    setPos(non-const EggVertex this, const Point2D pos)
    setPos(non-const EggVertex this, const Point3D pos)
    setPos(non-const EggVertex this, const Point4D pos)
    setPos(non-const EggVertex this, float pos)
    
    // The pos might have 1, 2, 3, or 4 dimensions.  That complicates
    // things a bit.
    
    // The pos might have 1, 2, 3, or 4 dimensions.  That complicates
    // things a bit.
    
    ////////////////////////////////////////////////////////////////////
    //     Function: EggVertex::set_pos
    //       Access: Published
    //  Description: Sets the vertex position.  This variant sets the
    //               vertex to a one-dimensional value.
    ////////////////////////////////////////////////////////////////////
    
    ////////////////////////////////////////////////////////////////////
    //     Function: EggVertex::set_pos
    //       Access: Published
    //  Description: Sets the vertex position.  This variant sets the
    //               vertex to a two-dimensional value.
    ////////////////////////////////////////////////////////////////////
    
    ////////////////////////////////////////////////////////////////////
    //     Function: EggVertex::set_pos
    //       Access: Published
    //  Description: Sets the vertex position.  This variant sets the
    //               vertex to a three-dimensional value.
    ////////////////////////////////////////////////////////////////////
    
    ////////////////////////////////////////////////////////////////////
    //     Function: EggVertex::set_pos
    //       Access: Published
    //  Description: Sets the vertex position.  This variant sets the
    //               vertex to a four-dimensional value.
    ////////////////////////////////////////////////////////////////////

The first few lines show the various acceptable overloads for the method, in Pythonized form. (The first parameter, by the way, is the “this” pointer, or “self” as Python convention usually names it, and is implicit, so don’t be distracted by it.) The remaining lines are the literal comments extracted from the C++ code for each overload.

The VertexPool returns the vertex. Here’s the C++ prototype, in eggVertexPool.h:

  EggVertex *add_vertex(EggVertex *vertex, int index = -1);

And if you ask Python, you get:

>>> help(vp.addVertex)
Help on built-in function addVertex:

addVertex(...)
    C++ Interface:
    addVertex(non-const EggVertexPool this, non-const EggVertex vertex)
    addVertex(non-const EggVertexPool this, non-const EggVertex vertex, int index)
    
    // add_vertex() adds a freshly-allocated vertex.  It is up to the
    // user to allocate the vertex.
    
    ////////////////////////////////////////////////////////////////////
    //     Function: EggVertexPool::add_vertex
    //       Access: Public
    //  Description: Adds the indicated vertex to the pool.  It is an
    //               error if the vertex is already a member of this or
    //               any other pool.  The vertex must have been allocated
    //               from the free store; its pointer will now be owned by
    //               the vertex pool.  If the index number is supplied,
    //               tries to assign that index number; it is an error if
    //               the index number is already in use.
    //
    //               It is possible that a forward reference to this
    //               vertex was requested in the past; if so, the data
    //               from the supplied vertex is copied onto the forward
    //               reference, which becomes the actual vertex.  In this
    //               case, a different pointer is saved (and returned)
    //               than the one actually passed in.  In the usual case,
    //               however, the vertex pointer passed in is the one that
    //               is saved in the vertex pool and returned from this
    //               method.
    ////////////////////////////////////////////////////////////////////

Which doesn’t report the return value explicitly, but the comment does explain that a vertex is returned.

David

I did not know that, thanks!

I guess I’m a bit surprised that there’s not much if any Python code under the hood so to speak. I think with your comments here, I can hit it again, and try and make some sense out of it.

Thanks again.

pydoc does a much better job than the online API reference tool.
Maybe we should consider using it instead.