0050. Auxiliary (General Purpose) Functions

Getting started, ptsxpy, Python language, trueSpace, programming, syntax highlighting for text editor, etc.
Note: it's provisional and topics will be added and revised at random till some sort of documentations are prepared.
Post Reply
User avatar
3DfromNULL
Site Admin
Posts: 45
Joined: 2018-Jul-13 9:35

0050. Auxiliary (General Purpose) Functions

Post by 3DfromNULL »

The "ptscgp" module provides auxiliary (general purpose) functions for user scripts. These functions are implemented in the ptsxXpysbXX.dll and user cannot change them directly unlike the ptsxpydef1.py.

User script can use them by importing ptsxgp (in addition to ptsxpy for most cases).

Code: Select all

import ptsxpy as p
import ptsxgp
In the line "import ptsxgp", you may use an alias like e.g. "import ptsxgp as g" though the author prefers no-alias for ptsxgp because I would like to decrease frequency of explicit use of ptsxgp in scripts.

Full list of auxiliary functions (ptsxpy version 0.0.11)

Code: Select all

getpymjrver()   # return Python major version 2 or 3
scrfname()      # return script full path file name
scrdir()        # return script directory name
memcpy_p2top1( p1,p2,sz ) # memory copy sz bytes from p2 to p1
msgbox_info( title,msg )   # create message box with an information icon
msgbox_excl( title,msg )   # create message box with an exclamation icon
sizeof_int()    # return sizeof( int ) of C++
sizeof_float()  # ( several sizeof_xxxxx() below are similar to above )
sizeof_long()
sizeof_short()
sizeof_pointer()
sizeof_struct_CtsxAxes3f() # return sizeof( struct_CtsxAxes3f() ) of C++
sizeof_struct_CtsxBBox3f() # ( several sizeof_xxxxx() below are similar to above )
sizeof_struct_CtsxBumpProps()
sizeof_struct_CtsxCollFaceReport()
sizeof_struct_CtsxCollisionReport()
sizeof_struct_CtsxCollVertexReport()
sizeof_struct_CtsxColor()
sizeof_struct_CtsxDerivCurves() # (ts5 or higher)
sizeof_struct_CtsxEdge()
sizeof_struct_CtsxFace()
sizeof_struct_CtsxFaceVx()
sizeof_struct_CtsxFloatColor()
sizeof_struct_CtsxGraniteProps()
sizeof_struct_CtsxHole()
sizeof_struct_CtsxLatticeFloor()
sizeof_struct_CtsxLatticeVector()
sizeof_struct_CtsxMarbleProps()
sizeof_struct_CtsxMatRectProps()
sizeof_struct_CtsxPhysEnvir() # (ts6.6)
sizeof_struct_CtsxProcTexture()
sizeof_struct_CtsxQuaternion()
sizeof_struct_CtsxRect()
sizeof_struct_CtsxSubDivEdge() # (ts5 or higher)
sizeof_struct_CtsxSubDivFace() # (ts6.6)
sizeof_struct_CtsxSurfaceProps()
sizeof_struct_CtsxTextureProps()
sizeof_struct_CtsxTxmx2f()
sizeof_struct_CtsxTxmx3f()
sizeof_struct_CtsxUV()
sizeof_struct_CtsxVector2f()
sizeof_struct_CtsxVector3f()
sizeof_struct_CtsxViewParam()
sizeof_struct_CtsxWDG_CALLBACKS()
sizeof_struct_CtsxWidgetReg()
sizeof_struct_CtsxWoodProps()
sizeof_struct_CtsxWoodProps()
sizeof_struct_tsxEventMouseData()
sizeof_struct_tsxEventRenderData()
sizeof_struct_tsxEventViewMsgData()
sizeof_struct_tsxImage()
sizeof_struct_tsxMousetool()
sizeof_struct_tsxObjectNotifyMessage()
sizeof_struct_tsxRenderData()
sizeof_struct_tsxRenderToFileData()
sizeof_struct_tsxTextureFromLightingData() # (ts6.0 or ts6.6)
alloc_vec3f( num, x, y, z ) # allocate memory area for array of CtsxVector3f
alloc_vec2f( num, x, y )    # allocate memory area for array of CtsxVector2f
alloc_txmx3f( (f,f,f,f)(f,f,f,f)(f,f,f,f) ) # allocate memory area for a CtsxTxmx3f
alloc_axes3f( (f,f,f)(f,f,f)(f,f,f) ) # ... for a CtsxAxes3f
alloc_bbox3f( (f,f,f)(f,f,f) )        # ... for a CtsxBBox3f
alloc_latvec( num, s, t, u ) # ... for array of CtsxLatticeVector
alloc_wdgreg( l,l,l,l,l )    # ... for a CtsxWidgetReg  (OBSOLETE)
alloc_colrpt( l,l,l,l,l )    # ... for a CtsxCollisionReport
alloc_quaternion( f,f,f,f )  # ... for a CtsxQuaternion
alloc_viewparam( f,f,f,f,f,f,f,f,f,f,f,f,i )  # ... for a CtsxViewParam
alloc_wdg_callbacks( p ) # ... for a CtsxWDG_CALLBACKS
alloc_color( num, r, g, b, a ) # ... for array of CtsxColor
alloc_surfaceprops( ka,ks,exp ) # ... for a CtsxSurfaceProps
alloc_protexgranite( b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,f,f,f,f,f,f,f,f,H ) # ... for a CtsxProcTexture of tsxTEXTURE_GRANITE
alloc_protexmarble( b,b,b,b,b,b,b,b,h,f,h,f,f,f,H )         # ... for a CtsxProcTexture of tsxTEXTURE_MARBLE
alloc_protexwood( b,b,b,b,b,b,b,b,f,f,f,f,f,f,f,h,f,f,f,H ) # ... for a CtsxProcTexture of tsxTEXTURE_WOOD
alloc_textureprops( f,f,f,f,H )  # ... for a CtsxTextureProps
alloc_bumpprops( f,f,f,f,f,H )   # ... for a CtsxBumpProps
alloc_txmx2f( (f,f,f)(f,f,f) ) # ... for a CtsxTxmx2f
alloc_rect( h,h,h,h )  # ... for a CtsxRect
alloc_facevx( num, i,i,i,b,b,b,b )  # ... for array of CtsxFaceVx
alloc_face( num, h,l,b,b,l,b,b,b,H )  # ... for array of CtsxFace
alloc_hole( h,l,b )  # ... for a CtsxHole
alloc_uv( u, v )  # ... for a CtsxUV
alloc_edge( num, i,i )  # ... for array of CtsxEdge
alloc_latticevector( s,t,u )  # ... for a CtsxLatticeVector
alloc_matrectprops( f,f,f,f )  # ... for a CtsxMatRectProps
alloc_derivcurves( i,i,i,i,k,k,k ) # (ts5 or higher) ... for a CtsxDerivCurves
alloc_subdivedge( num, i,i,f,i )  # ... for array of CtsxSubDivEdge
alloc_physenvir( k,f,f,f,f,f,f,f ) # (ts6.6) ... for a CtsxPhysEnvir
alloc_floatcolor( r,g,b,a )  # ... for a CtsxFloatColor
alloc_rendertofiledata( s,p,i,i,p,p,i,p,i,i,p,f,p,f,p,f,i,i,i )  # ... for a tsxRenderToFileData (Note: bool type "p" is "i" in Python 2)
alloc_renderdata( i,i,i,i,i,i,h,h,h,h,i,i,f,f,i,i,i,i,f,i,i,h,f ) # ... for a tsxRenderData
alloc_image( i,i,i,k )  # ... for a tsxImage
alloc_texturefromlightingdata( p,p,p,f,i,i,s,i ) # (ts6.0 or ts6.6) ... for a tsxTextureFromLightingData (Note: bool type "p" is "i" in Python 2)
alloc_char( num )   # allocate memory area for array of C++ char
alloc_short( num )      # ... for array of C++ short
alloc_int( num [,val] ) # ... for array of C++ int
alloc_long( num )            # ... for array of C++ long
alloc_float( num )           # ... for array of C++ float
alloc_double( num )          # ... for array of C++ double
alloc_str( str )  # allocate memory area and cooy specified string there
rand()      # return a value returned by C++ rand()
randomize() # do C++ srand( (unsigned)time( NULL ) )
loadfloat( p )       # load a C++ float from area pointed by p
storefloat( p,val )  # store specified value as C++ float to area pointed by p
loaddouble( p )      # ... double
storedouble()        # ... double
loadlong( p )        # ... long
storelong( p,val )   # ... long
loadulong( p )       # ... unsigned long
storeulong( p,val )  # ... unsigned long
loadint( p )         # ... int
storeint( p,val )    # ... int
loadshort( p )       # ... short
storeshort( p,val )  # ... short
loadushort( p )      # ... unsigned short
storeushort( p,val ) # ... unsigned short
loaduchar( p )       # ... unsigned char
storeuchar( p,val )  # ... unsigned char
loadptr( p )         # ... (same with unsigned long)
storeptr( p,val )    # ... (same with unsigned long)
loadstr( p )         # load a string from char * area pointed by p
storestr( p,val )    # store a string to area pointed by p
doosevents()         # do stacked all OS events
getdlldir()          # return the directory where the ptsxpy.tsx is
Some parameters in the list mean their name and others describe type. Ambiguously some "p" mean a pointer and others mean a bool type. Please don't take that seriously. The author just does not decide the specification. You might be able to get more specific information from error messages of these auxiliary functions.

Each function can be classified roughly in four;
  • To allocate (borrow) a memory area
  • To load from or store to a C++ specific length and type of memory area
  • To get size of struct defined in C++ layer
  • Others
Memory allocation
Though most of allocation functions were essential in the early ptsxpy version, users need not use most of them in the present versions. We had to write code with auxiliary functions back in the day as below;

Code: Select all

### OBSOLETE.  THIS OLD STYLE IS NOT RECOMMENDED
import ptsxpy as p
import ptsxgp

cb1 = p.CreateCube( 1, 2., 2., 2. )
p.SceneAddObject( cb1, e_tsxFALSE )
loc = ptsxgp.alloc_vec3f( 1, 3., 4., 5. )  ### OLD STYLE. NOT RECOMMENDED
p.GNodeSetLocation( cb1, loc ) ### OLD STYLE. NOT RECOMMENDED
p.Free( loc )  ### OLD STYLE. NOT RECOMMENDED
p.SceneDraw()
In comparison to the previous tutorial using predefined classes, user need to explicitly free memory areas allocated by ptsxgp.alloc_vec3f(). In present ptsxpy versions, classes predefined by ptsxpydef1.py encapsulate and automate the allocation and freeing process;

Code: Select all

vec1 = Vec3f( 3., 4., 5. )  ### RECOMMENDED
p.GNodeSetLocation( cb1, vec1.p )  ### RECOMMENDED
As I wrote in the previous tutorial, auxiliary functions are more convenient in case you would like to explicitly maintain (keep) allocated memory areas after a script ended. Of course you must free the area in later operation using another script in order to avoid memory-leaks.

You might notice there is one more difference between alloc_vec3f() and Vec3f(). The 1st paramerter to alloc_vec3f() (1 in this example) is "number of array element". This is used in order to allocate array of the vector. The parameter is used from Vec3fArray class and other similar classes in present ptsxpy version. Please read these classes in ptsxpydef1.py and sample scripts that uses xxxxArray classes if you are interested in.

Load/Store
Load and store have been also essential ever, but most of them can be replace by ptsxpy predefined classes (like Float, Ulong, Short, etc.) and their inherited classes (like Float_p, Ulong_p, Short_p, etc.). For example, the code below is fragment of a sample script.

Code: Select all

    p.SceneGetShaderParameterTypedValue( fgcls, i, ty1, wk1 )
    if   ty1 == tsxSHPARAM_FLOAT:
        val = ptsxgp.loadfloat( wk1 )
    elif ty1 == tsxSHPARAM_LONG  or \
         ty1 == tsxSHPARAM_BOOL:
        val = ptsxgp.loadlong( wk1 )
    elif ty1 == tsxSHPARAM_STRING:
        val = ptsxgp.loadstr( wk1 )
This should be able to rewrite without importing ptsxgp as below;

Code: Select all

    p.SceneGetShaderParameterTypedValue( fgcls, i, ty1, wk1 )
    if   ty1 == tsxSHPARAM_FLOAT:
        val = Float_p( wk1 ).get()
    elif ty1 == tsxSHPARAM_LONG  or \
         ty1 == tsxSHPARAM_BOOL:
        val = Long_p( wk1 ).get()
    elif ty1 == tsxSHPARAM_STRING:
        val = String_p( wk1 ).get()
The Float_p( wk1 ) regards the wk1 as a pointer to C++ float, and the .get() method convert its content (i.e. C++ float value) into Python float value and return it to the caller. The value is assigned to the variable val in the example as a result. In the sequence, the get() simply calls ptsxgp.loadfloat on behalf of user. The get() method is defined in Float class (parent class of Float_p) of ptsxpydef1.py;

Code: Select all

    def get( self ):
        return ptsxgp.loadfloat( self.p )
That's similar for other types above (Long and String in the example). These xxxx_p classes and get() method of them work like C++ cast.

Sizeof C++ struct
(Perhaps) all necessary sizes of struct are defined in ptsxpydef1.py. The ptsxpydef1.py uses these sizeof_xxxx auxiliary functions like;

Code: Select all

sizeof_CtsxVector3f = ptsxgp.sizeof_struct_CtsxVector3f()
In the example above, the value is a constant 12 (i.e. 3 * sizeof(float) ). But please note that some other C++ struct (with the same name) have different sizes between tS version like;

Code: Select all

sizeof_CtsxFaceVx = ptsxgp.sizeof_struct_CtsxFaceVx()  # 16 for tS4, 20 for higher version.
Others
There are other seceral auxiliary functions. The lines below are selected from the full list above. Please read brief comment per lines.

Code: Select all

getpymjrver()      # return Python major version 2 or 3
scrfname()         # return script full path file name
scrdir()           # return script directory name
memcpy_p2top1( p1,p2,sz )  # memory copy sz bytes from p2 to p1
msgbox_info( title,msg )   # create message box with an information icon
msgbox_excl( title,msg )   # create message box with an exclamation icon
rand()             # return a value returned by C++ rand()
randomize()        # do C++ srand( (unsigned)time( NULL ) )
doosevents()       # do stacked all OS events
getdlldir()        # return the directory where the ptsxpy.tsx is
Post Reply