0030. Predefined Classes

Post by **3DfromNULL** » 2021-Apr-19 8:30

The file "ptsxpydef1.py" (you installed in tsx\ptsx2py\ or tsx\ptsx3py\ folder) defines convenient classes to bridge between your python scripts and tsxAPI (C++) functions.

In the previous example, we created a cube.

Code: Select all

cb1 = p.CreateCube( 1, 2., 2., 2. )
p.SceneAddObject( cb1, e_tsxFALSE )
p.SceneDraw()

We can move it relatively using GNodeTranslate() or move it absolutely using GNodeSetLocation(). Let's see the latter's corresponding C++ syntax defined in tsxAPIxx.doc.

void tsxGNodeSetLocation(tsxGNODE* pGNode, CtsxVector3f* loc)

The void means that the function returns nothing. The "tsxGNODE*" means that the type is a pointer to GNODE. The GNODE is also (as with tsxPOLYHEDRON appeared in the previous tutorial) an abstract type and the pointer is just an integer value. We naturally specify cb1 as the 1st parameter. The 2nd parameter is a pointer to CtsxVector3f. The CtsxVector3f is not an abstract type but a C++ struct that has a finite byte length, and defined in tsxAPIxx.doc (and a C++ header file in SDK) as;

Code: Select all

struct CtsxVector3f
{
    float x, y, z;
};

The byte length of the struct (i.e. sizeof( struct CtsxVector3f ) in C++) is 12 because it consists of three float values and each of them is 4 bytes. In order to allocate the 12 bytes of memory area, the file ptsxpydef1.py provides a class;

Code: Select all

import ptsxpy as p

cb1 = p.CreateCube( 1, 2., 2., 2. )
p.SceneAddObject( cb1, e_tsxFALSE )
vec1 = Vec3f( 3., 4., 5. )
p.GNodeSetLocation( cb1, vec1.p )
p.SceneDraw()

The line of Vec3f() creates an instance of a class. In this example, it takes three parameters for x, y, z, make an instance (in the context of the Python script) and return an instance (to be accurate, a class object of Python). The instance has a C++ pointer (integer value) named "p" as a member in itself, and it points 12 bytes memory area allocated by the line. In general, we can refer a member of a class like classinstance.member. In the case, it is "vec1.p".

Please don't confuse p.xxxxx with xxxxx.p. The former "p" is an alias name defined freely at the beginning of the script. If you declare it like "import ptsxpy as AAA" instead, then you can write like AAA.CreateCube() in following lines. On the other hand, you cannot replace the ".p" to other word (unless you change the ptsxpydef1.py).

When we mistakenly forget to add ".p" like "p.GNodeSetLocation( cb1, vec1 )", ptsxpy should report an error in the console window and terminate the execution of the script at the line.

As a side note, the reason why the author decided "p" as the standard alias name is that it is the initial of ptsxpy. I used "ptsx" as the alias in the early days of test phase but stopped to use and replace it with "p" because it's too long and disturb reading (make the readability worse).

Of course, you can also write as below if you would like to omit preceding "p." in all lines;

Code: Select all

from ptsxpy import *
cb1 = CreateCube( 1, 2., 2., 2. )
...

One of disadvantages of doing so is that the maintenance of syntax-highlighting definition (for web page like this and text editor) becomes complicated. In fact, I don't implement any syntax-highlighting of individual API function to this page for that reason, and do only syntax-highlighting of "p.xxxxx".

Now the cube moved to the specified coordinate (in the air), and tS hold it till it is deleted explicitly. The 12 byte memory area allocated by Vec3f() is freed automatically by its destructor when the class instance becomes a state "not used". For example, the more compact code below seems to be logical but should not work well because the memory area allocated as Vec3f instance might be freed before it is used by tS API;

Code: Select all

### WRONG CODE! Don't write like this!! ###
p.GNodeSetLocation( cb1, Vec3f( 5., 0., 0. ).p ) ### WRONG CODE! ###

If you would like to check the timing when the destructor is executed, try inserting print() to each destructor in ptsxpydef1.py. Each destructor begins with a line like below;

Code: Select all

    def __del__( self ):

In this example, the automatic freeing is very convenient because we need not worry about memory-leak. On the other hand, in case that tS keeps looking at the dynamically allocated memory area, you must maintain the area using lower level functions (like ptsxgp.alloc_xxxxx(), p.Malloc(), p.Calloc(), etc.) instead of classes so that any freed area is not referred by tS.

Full list of predefined classes in ptsxpydef1.py file (of ptsxpy version 0.0.10) are;

Code: Select all

Vec3f
Vec2f
Vec3fArray
Axes3f
Txmx3f
BBox3f
WidgetReg
CollisionReport
Quaternion
ViewParam
WDG_CALLBACKS
Color
ColorArray
SurfaceProps
ProTexGranite
ProTexMarble
ProTexWood
TextureProps
BumpProps
Txmx2f
Rect
FaceVx
FaceVxArray
Face
FaceArray
Hole
UV
Edge
EdgeArray
LatticeVector
LatticeFloor
MatRectProps
DerivCurves
SubDivEdge
SubDivEdgeArray
SubDivFace
SubDivFaceArray
PhysEnvir
FloatColor
RenderToFileData
RenderData
Image
TextureFromLightingData
String
CharArray
Float
FloatArray
Double
DoubleArray
Long
LongArray
Ulong
Short
Ushort
IntArray

Note:

Classes named xxxxArray allocate array of xxxx.
Most classes have corresponding xxxx_p class that is inherited from xxxx class in order to give a type to a C++ pointer (i.e. regard a integer value as a pointer to specific struct) like cast of C/C++. For example, it's convenient in case that an API function fills a pointer in 4 byte memory area specified to its parameter and you use it as a pointer to Vec3f. Please read sample scripts for details.
The name of most classes completely correspond to struct CtsxXXXX defined in tsxAPIxx.doc and header files, or to C/C++ types like float, long, etc.
As a few exceptions: Vec3f allocates a struct CtsxVector3f, and Vec2f allocates a struct CtsxVector2f. The reason why the author didn't use "Vector3f" and "Vector2f" as their corresponding class name is; Because they are too long to use frequently.

Please read each class in ptsxpydef1.py for details. It's a plain text file.