Home

Resume

Blog

Teikitu


/* =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= */
/*  »Project«   Teikitu Gaming System (TgS) (∂)
    »File«      TgS Common - String MGR.h
    »Author«    Andrew Aye (EMail: mailto:andrew.aye@gmail.com, Web: http://www.andrewaye.com)
    »Version«   4.51 / »GUID« A9981407-3EC9-42AF-8B6F-8BE6DD919615                                                                                                        */
/*   -------------------------------------------------------------------------------------------------------------------------------------------------------------------- */
/*  Copyright: © 2002-2017, Andrew Aye.  All Rights Reserved.
    This software is free for non-commercial use.  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
      following conditions are met:
        Redistribution of source code must retain this copyright notice, this list of conditions and the following disclaimers.
        Redistribution in binary form must reproduce this copyright notice, this list of conditions and the following disclaimers in the documentation and other materials
          provided with the distribution.
    The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
    The intellectual property rights of the algorithms used reside with Andrew Aye.
    You may not use this software, in whole or in part, in support of any commercial product without the express written consent of the author.
    There is no warranty or other guarantee of fitness of this software for any purpose. It is provided solely "as is".                                                   */
/* =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= */
#if !defined(TGS_COMMON_STRING_MGR_H)
#define TGS_COMMON_STRING_MGR_H
#pragma once


/* == Common ============================================================================================================================================================ */

/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */
/*  Public Constants                                                                                                                                                      */
/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */

enum { KTgSM_NUM_STRING_TABLE_MAX           = 16 };
enum { KTgSM_MAX_NATIVE_ENTRIES             = 1024 };


/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */
/*  Public Types                                                                                                                                                          */
/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */

TgTYPE_STRUCT(STg2_String_Table,)
{
                                                /* Entry iD == Data Index:32, Used: 1, Unused:15, Size:16 */
    TgSINT32                                    m_niEntry_ID; /*« Count of strings in the table */
    TgSINT32                                    m_iPad0;
    P_TgSINT64                                  m_aiEntry_ID; /*« List of string ids in the table */
    TgSINT32                                    m_niData; /*« Amount of committed memory in m_pData */
    TgSINT32                                    m_iPad1;
    P_TgUINT08                                  m_pData; /*« Storage pool for the encoded strings */
};


/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */
/*  Public Functions                                                                                                                                                      */
/* -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-. */

TgEXTN TgRESULT                             tgSM_Init_MGR( TgVOID );
TgEXTN TgRESULT                             tgSM_Boot_MGR( TgVOID );
TgEXTN TgRESULT                             tgSM_Stop_MGR( TgVOID );
TgEXTN TgRESULT                             tgSM_Free_MGR( TgVOID );
TgEXTN TgRESULT                             tgSM_Update_MGR( C_TgFLOAT32 );

TgEXTN TgBOOL                               tgSM_Query_Init( TgVOID );
TgEXTN TgBOOL                               tgSM_Query_Boot( TgVOID );

TgEXTN TgSIZE                               tgSM_Query_Fixed_Memory( TgVOID );

#if TgS_STAT_COMMON
                                            /* Output stats on the current state of the system */
TgEXTN TgVOID                               tgSM_Stats( P_STg2_Output );
/*# TgS_STAT_COMMON */
#endif


/* ---- Native String List ---------------------------------------------------------------------------------------------------------------------------------------------- */

                                            /* Register a native string. These are inserted into a specific (enumerated) location and can never be removed. The parameter */
                                            /* string life time is expected to be for the duration of execution. (i.e. the string is not copied) It is illegal to attempt */
                                            /* multiple inits at the same index. */
                                            /* 1: String to be associated with the given index */
                                            /* 2: Index associated with the given string */
                                            /* R: Negative if an error occurs, otherwise the given index. */
TgEXTN TgSINT32                             tgSM_UID_Init_String( CPC_TgCHAR, C_TgSINT32 );

                                            /* Retrieve the string associated with the given hash */
                                            /* 1: Index: Index value being queried */
                                            /* R: Pointer to a string or nullptr */
TgEXTN CP_TgCHAR                            tgSM_UID_Query_String( C_TgSINT32 );


/* ---- Global Dictionary ----------------------------------------------------------------------------------------------------------------------------------------------- */

/*  The global dictionary is used during run time to create a common string pool.  The primary purpose is to eliminate the need to store redundant string data that is */
/* sourced from data files.  The strings are encoded (compressed) internally so as to keep the minimal memory foot print.  The expected usage pattern is that it is used */
/* for limited string lengths and entirely for system string data.  Since all game string data needs to be localized, that should come in through string tables. */
/* NOTE: Hash collisions are not handled! */

                                            /* Register a new string in the system.  If it already exists, increment the ref count */
                                            /* 1: String: pointer to the registering string */
                                            /* 2: Length of the string in parameter 1 */
                                            /* 3| Hash of the string */
                                            /* R: Dictionary identifier for the given string */
TgEXTN TgSTRING_DICT_ID                     tgSM_Dict_Insert_String_Hash( CPC_TgCHAR, C_TgSIZE, C_TgUINTXX );
TgEXTN TgSTRING_DICT_ID                     tgSM_Dict_Insert_String( CPC_TgCHAR, C_TgSIZE );

                                            /* NOTE: This does a search based on the hash. This should be executed at most once, and the ID cached */
                                            /* Return the dictionary id for the given string | hash or the invalid id */
                                            /* 1: String: pointer to the string */
                                            /* 2: Length of the string in parameter 1 */
                                            /* R: Dictionary identifier for the given string */
TgEXTN TgSTRING_DICT_ID                     tgSM_Dict_Find_Id_By_Hash( CPC_TgCHAR, C_TgUINTXX );
TgEXTN TgSTRING_DICT_ID                     tgSM_Dict_Find_Id_By_String( CPC_TgCHAR );

                                            /* Retrieve the string associated with the given hash */
                                            /* 1: String [Out]: Pointer to a string pointer - considered to be stable */
                                            /* 2: Length [Out]: Length of the string */
                                            /* 3: Dict Id: Dictionary Id that is being queried */
TgEXTN TgBOOL                               tgSM_Dict_Query_String( CPP_TgCHAR, PC_TgSIZE, C_TgSTRING_DICT_ID );


/* ---- String Tables --------------------------------------------------------------------------------------------------------------------------------------------------- */

/* A string table is a list of sets of a unique id (unique globally as enforced by tool generation), associated user data, and an encoded string.  Each table has its own */
/* dictionary and does not use the global dictionary. */

                                            /* All loads are assumed to be asynchronous - this function is completely thread safe. */
                                            /* This function itself is synchronous but is expected to be executed on a thread. */
TgEXTN TgSTRING_TABLE_ID                    tgSM_Table_Load( PC_STg2_Input, C_TgSIZE );

TgEXTN TgBOOL                               tgSM_Table_Free( C_TgSTRING_TABLE_ID );

                                            /* This is a polling method to determine if a requested load operation has completed. */
TgEXTN TgBOOL                               tgSM_Table_Is_Loaded( C_TgSTRING_TABLE_ID );

                                            /* Retrieve the string associated with the given hash */
                                            /* 1: String [Out]: Pointer to a string pointer */
                                            /* 2: Length [Out]: Length of the string */
                                            /* 3: Table Id: Table that is being queried */
                                            /* 4: Entry Index: Index in the table for the given string */
TgEXTN TgBOOL                               tgSM_Table_Query_String( CPP_TgCHAR, PC_TgSIZE, C_TgSTRING_TABLE_ID, C_TgSINT32 );


/* ====================================================================================================================================================================== */
#endif