• Entity data signature

    TBGL provides the programmer with entity system, which allows definition of multiple kinds of types of entities. Sometimes we need to work with just group of entities and cast on them context specific action.

    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
    
    Code 1: Listing for elemental signature provider

    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()
    
    Code 2: Assigning signatures

    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
    
    Code 3: Example user defined type without data signature

    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
    
    Code 4: User defined data type with signature defined

    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
    
    Code 5: Alternative approach in data signing

    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
    
    Code 6: Creation of data signed entity of apple storage box

    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
    
    Code 7: Enumerating entity IDs of apple boxes

    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.
    Comments 3 Comments
    1. D.J.Peters's Avatar
      D.J.Peters -
      If all Entity ID's are system/scene wide unique why we need a signature ID also ?

      Joshy
    1. Petr Schreiber's Avatar
      Petr Schreiber -
      Quote Originally Posted by D.J.Peters View Post
      If all Entity ID's are system/scene wide unique why we need a signature ID also ?

      Joshy
      We don't need them, but we can use them. It is good way to sign multiple entities - in one scene, you can have:
      %eOrange, %eApple, %eBanana, %eCarrot, %ePotato

      The %eOrange, %eApple, %eBanana have different entitiy IDs, but you could supply them the same signatureID, which would represent "fruit".
      The %eCarrot, %ePotato have different entitiy IDs, but you could supply them the same signatureID, which would represent "vegetable".

      The signature can be used for filtering out entities, which have something in common.
    1. D.J.Peters's Avatar
      D.J.Peters -
      Thank you Petr for this good description.

      Now it makes sence for me.

      Joshy