Sections
Categories
As the scene in TBGL can be composed of completely heterogeneous elements, this can become quite complicated task. We will take advantage of the fact any entity in TBGL can hold its custom user data, defined by programmer. By marking the user data with custom signature, we can easily determine which entities have something in common.
This article explains what data signature is, how to specify it and how to use it for comfortable handling of objects in the scene.
What is data signature
The data signature is any programmer defined value, which helps to identify the entity in program specific way. The value is represented as long integer, which means possibility to define 232 unique data signatures.
How to generate the signatures? This is completely up to the programmer. You could generate some random number, analyze text descriptor of the data and convert it to numeric value… the possibilities are almost endless.
This paper will provide one possible hint, which costs almost no effort and avoids any possible collisions in most cases.
The most straightforward approach is to design signature provider as generator of raising number sequence as shown in Code 1. This can be easily done using simple function with one static variable.
FUNCTION Signature_Provider() AS LONG STATIC lastSignature AS LONG lastSignature += 1 RETURN lastSignature END FUNCTION
To store the signature somewhere, we might consider using equates. Each call to Signature_Provider provides us with unique number, so we can generate the signatures as simple as Code 2 does.
%signatureBoxOfApples = Signature_Provider() %signatureBoxOfOranges = Signature_Provider()
Now %signatureBoxOfApples contains value of 1 and %signatureBoxOfOranges value of 2. In the code of program we can use the more descriptive equate names to keep the code easy to read, instead of numeric values.
How to specify data signature
To add data signature to your data, just specify the first member of UDT as signature of type LONG. To illustrate it on the example, let’s presume having user defined type as on Code 3.
TYPE StockBox Capacity AS SINGLE Occupied AS SINGLE END TYPE
To add data signature we have at least two options. The first one is demonstrated on Code 4. It is very important to have the signature as the first member in the UDT!
TYPE StockBox Signature AS LONG Capacity AS SINGLE Occupied AS SINGLE END TYPE
Sometimes you might prefer to not ”damage” your data with additional member, so you can go the route of wrapper UDT, as shown on Code 5.
TYPE StockBox Capacity AS SINGLE Occupied AS SINGLE END TYPE TYPE Signed_StockBox Signature AS LONG Data AS StockBox END TYPE
With the data signed, you can assign them to entity as you are used to, via TBGL_EntitySetUserData.
Example usage
To give data signing some more concrete shape, let’s continue with the idea of stock handling for some fruit company, which has stock boxes for storage of oranges and apples.
For such a case, you can define your custom entity creation routines, where do you bake the signature in without any problem. The code for apple box storage is shown on Code 6. The code for oranges would be analogous.
Thanks to the signed data, you will be able to find the entities later, so it is safe to create the entities on the fly, by creating entity ID using TBGL_EntityGetFreeID, as the code shows. This approach also does enable easier creation of entities as it comes to need, without necessity of grouping entities of same type tightly one by another, as was common before the introduction of data signing principle.
FUNCTION AppleBox_Create( sScene AS LONG, Capacity AS SINGLE, Occupied AS SINGLE)AS LONG
DIM entity AS LONG = TBGL_EntityGetFreeID(sScene)
DIM tempData AS StockBox
tempData.signature = %signatureBoxOfApples
tempData.Capacity = Capacity
tempData.Occupied = Occupied
TBGL_EntityCreateFuncSlot(sScene, entity, 0, "AppleBox_Render")
TBGL_EntitySetUserData(sScene, entity, tempData)
RETURN entity
END FUNCTION
Now we are finally getting to the enumeration itself. Let’s imagine scene full of various entities representing the environment of 3D stock and stock boxes inside. Filtering just the apple boxes from this heterogeneous setup is very easy and can be done in two steps:
- Declare array to hold entity IDs and variable to hold their count
- Call TBGL_EntityEnumByDataSignature
One thing to notice – ThinBASIC SDK does not allow passing undimensioned arrays at the moment, so you have to specify at least one element to the receiving array, as seen on Code 7. The TBGL_EntityEnumByDataSignature will then correctly dimension the array to make sure all found entitiy IDs with specified signature fit in.
DIM AppleBoxes(1) AS LONG DIM AppleBoxes_Count AS LONG AppleBoxes_Count = TBGL_EntityEnumByDataSignature(%sScene, AppleBoxes, %signatureBoxOfApples) FOR i = 1 TO AppleBoxes_Count MSGBOX 0, "Entity #"+AppleBoxes(i) +" is apple box" NEXT
Programmer can manipulate the retrieved IDs as usual, in this case we could for example empty all apple boxes, sum the total space occupied by fruits or do any other task necessary.
Enumeration of entities by data is not task specific, and programmer can use it for any action he needs.
Conclusion
This article introduced the topic of identifying and enumerating TBGL entities by data signature on the example of stock boxes. It did not went too deep with the design of stock box monitoring application, to let the data signing related mechanisms as clear as possible.
Data signing approach is not limited just to this case of course, and can prove to be valuable tool in games, serious applications and scientific visualizations.
The mechanism of entity enumeration is available since ThinBASIC 1.8.5.0 release, so for further experiments make sure you have this, or any latest version installed on your PC.
Tag Cloud
Message