/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_addon.h

   1/**
   2
   3\page doc_addon Add-ons
   4
   5This page gives a brief description of the add-ons that you'll find in the /sdk/add_on/ folder.
   6
   7 - \subpage doc_addon_application
   8 - \subpage doc_addon_script
   9
  10\page doc_addon_application Application modules
  11
  12 - \subpage doc_addon_build
  13 - \subpage doc_addon_ctxmgr
  14 - \subpage doc_addon_autowrap
  15 - \subpage doc_addon_helpers
  16 - \subpage doc_addon_clib
  17
  18\page doc_addon_script Script extensions
  19
  20 - \subpage doc_addon_std_string
  21 - \subpage doc_addon_string
  22 - \subpage doc_addon_array
  23 - \subpage doc_addon_any
  24 - \subpage doc_addon_dict
  25 - \subpage doc_addon_file
  26 - \subpage doc_addon_math
  27 - \subpage doc_addon_math3d
  28
  29
  30
  31\page doc_addon_ctxmgr Context manager
  32
  33<b>Path:</b> /sdk/add_on/contextmgr/
  34
  35The <code>CContextMgr</code> is a class designed to aid the management of multiple simultaneous 
  36scripts executing in parallel. It supports both \ref doc_adv_concurrent "concurrent script threads" and \ref doc_adv_coroutine "co-routines". 
  37
  38If the application doesn't need multiple contexts, i.e. all scripts that are executed 
  39always complete before the next script is executed, then this class is not necessary.
  40
  41Multiple context managers can be used, for example when you have a group of scripts controlling 
  42ingame objects, and another group of scripts controlling GUI elements, then each of these groups
  43may be managed by different context managers.
  44
  45Observe, that the context manager class hasn't been designed for multithreading, so you need to
  46be careful if your application needs to execute scripts from multiple threads.
  47
  48\see The samples \ref doc_samples_concurrent and \ref doc_samples_corout for uses
  49
  50\section doc_addon_ctxmgr_1 Public C++ interface
  51
  52\code
  53class CContextMgr
  54{
  55public:
  56  CContextMgr();
  57  ~CContextMgr();
  58
  59  // Set the function that the manager will use to obtain the time in milliseconds.
  60  void SetGetTimeCallback(TIMEFUNC_t func);
  61
  62  // Registers the script function
  63  //
  64  //  void sleep(uint milliseconds)
  65  //
  66  // The application must set the get time callback for this to work
  67  void RegisterThreadSupport(asIScriptEngine *engine);
  68
  69  // Registers the script functions
  70  //
  71  //  void createCoRoutine(const string &in functionName, any @arg)
  72  //  void yield()
  73  void RegisterCoRoutineSupport(asIScriptEngine *engine);
  74
  75  // Create a new context, prepare it with the function id, then return 
  76  // it so that the application can pass the argument values. The context
  77  // will be released by the manager after the execution has completed.
  78  asIScriptContext *AddContext(asIScriptEngine *engine, int funcId);
  79
  80  // Create a new context, prepare it with the function id, then return
  81  // it so that the application can pass the argument values. The context
  82  // will be added as a co-routine in the same thread as the currCtx.
  83  asIScriptContext *AddContextForCoRoutine(asIScriptContext *currCtx, int funcId);
  84
  85  // Execute each script that is not currently sleeping. The function returns after 
  86  // each script has been executed once. The application should call this function
  87  // for each iteration of the message pump, or game loop, or whatever.
  88  void ExecuteScripts();
  89
  90  // Put a script to sleep for a while
  91  void SetSleeping(asIScriptContext *ctx, asUINT milliSeconds);
  92
  93  // Switch the execution to the next co-routine in the group.
  94  // Returns true if the switch was successful.
  95  void NextCoRoutine();
  96
  97  // Abort all scripts
  98  void AbortAll();
  99};
 100\endcode
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112\page doc_addon_array array template object
 113
 114<b>Path:</b> /sdk/add_on/scriptarray/
 115
 116The <code>array</code> type is a \ref doc_adv_template "template object" that allow the scripts to declare arrays of any type.
 117Since it is a generic class it is not the most performatic due to the need to determine characteristics at 
 118runtime. For that reason it is recommended that the application registers a \ref doc_adv_template_2 "template specialization" for the
 119array types that are most commonly used.
 120
 121The type is registered with <code>RegisterScriptArray(asIScriptEngine*)</code>.
 122
 123\section doc_addon_array_1 Public C++ interface
 124
 125\code
 126class CScriptArray
 127{
 128public:
 129  // Constructor
 130  CScriptArray(asUINT length, asIObjectType *ot);
 131  virtual ~CScriptArray();
 132
 133  // Memory management
 134  void AddRef();
 135  void Release();
 136
 137  // Type information
 138  asIObjectType *GetArrayObjectType() const;
 139  int            GetArrayTypeId() const;
 140  int            GetElementTypeId() const;
 141
 142  // Get the current size
 143  asUINT GetSize();
 144
 145  // Resize the array
 146  void   Resize(asUINT numElements);
 147  
 148  // Get a pointer to an element. Returns 0 if out of bounds
 149  void  *At(asUINT index);
 150
 151  // Copy the contents of one array to another (only if the types are the same)
 152  CScriptArray &operator=(const CScriptArray&);
 153};
 154\endcode
 155
 156\section doc_addon_array_2 Public script interface
 157
 158<pre>
 159  class array<class T>
 160  {
 161    array();
 162    array(uint length);
 163    
 164    // Access elements
 165    // T & operator [] (uint)
 166    // const T & operator [] (uint) const
 167
 168    array<T> opAssign(const array<T> & in);
 169    
 170    uint length();
 171    void resize(uint);
 172  }
 173</pre>
 174
 175\section doc_addon_array_3 Script example
 176
 177<pre>
 178  int main()
 179  {
 180    array<int> arr(3);
 181    arr[0] = 1;
 182    arr[1] = 2;
 183    arr[2] = 3;
 184    
 185    int sum = 0;
 186    for( uint n = 0; n < arr.length(); n++ )
 187      sum += arr[n];
 188      
 189    return sum;
 190  }
 191</pre>
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201\page doc_addon_any any object
 202
 203<b>Path:</b> /sdk/add_on/scriptany/
 204
 205The <code>any</code> type is a generic container that can hold any value. It is a reference type.
 206
 207The type is registered with <code>RegisterScriptAny(asIScriptEngine*)</code>.
 208
 209\section doc_addon_any_1 Public C++ interface
 210
 211\code
 212class CScriptAny
 213{
 214public:
 215  // Constructors
 216  CScriptAny(asIScriptEngine *engine);
 217  CScriptAny(void *ref, int refTypeId, asIScriptEngine *engine);
 218
 219  // Memory management
 220  int AddRef();
 221  int Release();
 222
 223  // Copy the stored value from another any object
 224  CScriptAny &operator=(const CScriptAny&);
 225  int CopyFrom(const CScriptAny *other);
 226
 227  // Store the value, either as variable type, integer number, or real number
 228  void Store(void *ref, int refTypeId);
 229  void Store(asINT64 &value);
 230  void Store(double &value);
 231
 232  // Retrieve the stored value, either as variable type, integer number, or real number
 233  bool Retrieve(void *ref, int refTypeId) const;
 234  bool Retrieve(asINT64 &value) const;
 235  bool Retrieve(double &value) const;
 236
 237  // Get the type id of the stored value
 238  int GetTypeId() const;
 239};
 240\endcode
 241
 242\section doc_addon_any_2 Public script interface
 243
 244<pre>
 245  class any
 246  {
 247    any();
 248    any(? &in value);
 249  
 250    void store(? &in value);
 251    void store(int64 &in value);
 252    void store(double &in value);
 253  
 254    bool retrieve(? &out value) const;
 255    bool retrieve(int64 &out value) const;
 256    bool retrieve(double &out value) const;
 257  }
 258</pre>
 259
 260\section doc_addon_any_3 Example usage
 261
 262In the scripts it can be used as follows:
 263
 264<pre>
 265  int value;
 266  obj object;
 267  obj \@handle;
 268  any a,b,c;
 269  a.store(value);      // store the value
 270  b.store(\@handle);    // store an object handle
 271  c.store(object);     // store a copy of the object
 272  
 273  a.retrieve(value);   // retrieve the value
 274  b.retrieve(\@handle); // retrieve the object handle
 275  c.retrieve(object);  // retrieve a copy of the object
 276</pre>
 277
 278In C++ the type can be used as follows:
 279
 280\code
 281CScriptAny *myAny;
 282int typeId = engine->GetTypeIdByDecl("string@");
 283CScriptString *str = new CScriptString("hello world");
 284myAny->Store((void*)&str, typeId);
 285myAny->Retrieve((void*)&str, typeId);
 286\endcode
 287
 288
 289
 290\page doc_addon_std_string string object (STL)
 291
 292<b>Path:</b> /sdk/add_on/scriptstdstring/
 293
 294This add-on registers the <code>std::string</code> type as-is with AngelScript. This gives
 295perfect compatibility with C++ functions that use <code>std::string</code> in parameters or
 296as return type.
 297
 298A potential drawback is that the <code>std::string</code> type is a value type, thus may 
 299increase the number of copies taken when string values are being passed around
 300in the script code. However, this is most likely only a problem for scripts 
 301that perform a lot of string operations.
 302
 303Register the type with <code>RegisterStdString(asIScriptEngine*)</code>.
 304
 305\see \ref doc_addon_string
 306
 307\section doc_addon_std_string_1 Public C++ interface
 308
 309Refer to the <code>std::string</code> implementation for your compiler.
 310
 311\section doc_addon_std_string_2 Public script interface
 312
 313<pre>
 314  class string
 315  {
 316    // Constructors
 317    string();
 318    
 319    // Returns the length of the string
 320    uint length() const;
 321    
 322    // Assignment and concatenation
 323    string &opAssign(const string &in other);
 324    string &opAddAssign(const string &in other);
 325    string  opAdd(const string &in right) const;
 326    
 327    // Access individual characters
 328    // uint8 &operator [] (uint)
 329    // const uint8 &operator [] (uint) const
 330    
 331    // Comparison operators
 332    bool opEquals(const string &in right) const;
 333    int  opCmp(const string &in right) const;
 334    
 335    // Automatic conversion from number types to string type
 336    string &opAssign(double val);
 337    string &opAddAssign(double val);
 338    string  opAdd(double val) const;
 339    string  opAdd_r(double val) const;
 340    
 341    string &opAssign(int val);
 342    string &opAddAssign(int val);
 343    string  opAdd(int val) const;
 344    string  opAdd_r(int val) const;
 345    
 346    string &opAssign(uint val);
 347    string &opAddAssign(uint val);
 348    string  opAdd(uint val) const;
 349    string  opAdd_r(uint val) const;
 350  }
 351</pre>
 352
 353
 354
 355
 356\page doc_addon_string string object (reference counted)
 357
 358<b>Path:</b> /sdk/add_on/scriptstring/
 359
 360This add-on registers a string type that is in most situations compatible with the 
 361<code>std::string</code>, except that it uses reference counting. This means that if you have an
 362application function that takes a <code>std::string</code> by reference, you can register it 
 363with AngelScript to take a script string by reference. This works because the CScriptString
 364wraps the <code>std::string</code> type, with the std::string type at the first byte of the CScriptString
 365object.
 366
 367Register the type with <code>RegisterScriptString(asIScriptEngine*)</code>. Register the 
 368utility functions with <code>RegisterScriptStringUtils(asIScriptEngine*)</code>.
 369
 370\see \ref doc_addon_std_string
 371
 372\section doc_addon_string_1 Public C++ interface
 373
 374\code
 375class CScriptString
 376{
 377public:
 378  // Constructors
 379  CScriptString();
 380  CScriptString(const CScriptString &other);
 381  CScriptString(const char *s);
 382  CScriptString(const std::string &s);
 383
 384  // Memory management
 385  void AddRef();
 386  void Release();
 387
 388  // Assignment
 389  CScriptString &operator=(const CScriptString &other);
 390  
 391  // Concatenation
 392  CScriptString &operator+=(const CScriptString &other);
 393  friend CScriptString *operator+(const CScriptString &a, const CScriptString &b);
 394  
 395  // Memory buffer
 396  std::string buffer;
 397};
 398\endcode
 399
 400\section doc_addon_string_2 Public script interface
 401
 402<pre>
 403  class string
 404  {
 405    // Constructors
 406    string();
 407    string(const string &in other);
 408    
 409    // Returns the length of the string
 410    uint length() const;
 411    
 412    // Assignment and concatenation
 413    string &opAssign(const string &in other);
 414    string &opAddAssign(const string &in other);
 415    string \@opAdd(const string &in right) const;
 416    
 417    // Access individual characters
 418    // uint8 &operator [] (uint)
 419    // const uint8 &operator [] (uint) const
 420    
 421    // Comparison operators
 422    bool opEquals(const string &in right) const;
 423    int  opCmp(const string &in right) const;
 424    
 425    // Automatic conversion from number types to string type
 426    string &opAssign(double val);
 427    string &opAddAssign(double val);
 428    string \@opAdd(double val) const;
 429    string \@opAdd_r(double val) const;
 430 
 431    string &opAssign(float val);
 432    string &opAddAssign(float val);
 433    string \@opAdd(float val) const;
 434    string \@opAdd_r(float val) const;
 435 
 436    string &opAssign(int val);
 437    string &opAddAssign(int val);
 438    string \@opAdd(int val) const;
 439    string \@opAdd_r(int val) const;
 440    
 441    string &opAssign(uint val);
 442    string &opAddAssign(uint val);
 443    string \@opAdd(uint val) const;
 444    string \@opAdd_r(uint val) const;
 445  }
 446
 447  // Get a substring of a string
 448  string @ substring(const string &in str, int start, int length);
 449
 450  // Find the first occurrance of the substring
 451  int findFirst(const string &in str, const string &in sub);
 452  int findFirst(const string &in str, const string &in sub, int startAt)
 453  
 454  // Find the last occurrance of the substring
 455  int findLast(const string &in str, const string &in sub);
 456  int findLast(const string &in str, const string &in sub, int startAt);
 457  
 458  // Find the first character from the set 
 459  int findFirstOf(const string &in str, const string &in set);
 460  int findFirstOf(const string &in str, const string &in set, int startAt);
 461  
 462  // Find the first character not in the set
 463  int findFirstNotOf(const string &in str, const string &in set);
 464  int findFirstNotOf(const string &in str, const string &in set, int startAt);
 465  
 466  // Find the last character from the set
 467  int findLastOf(const string &in str, const string &in set);
 468  int findLastOf(const string &in str, const string &in set, int startAt);
 469  
 470  // Find the last character not in the set
 471  int findLastNotOf(const string &in str, const string &in set);
 472  int findLastNotOf(const string &in str, const string &in set, int startAt);
 473  
 474  // Split the string into an array of substrings
 475  string@[]@ split(const string &in str, const string &in delimiter);
 476  
 477  // Join an array of strings into a larger string separated by a delimiter
 478  string@ join(const string@[] &in str, const string &in delimiter);
 479</pre>
 480
 481
 482
 483
 484\page doc_addon_dict dictionary object 
 485
 486<b>Path:</b> /sdk/add_on/scriptdictionary/
 487
 488The dictionary object maps string values to values or objects of other types. 
 489
 490Register with <code>RegisterScriptDictionary(asIScriptEngine*)</code>.
 491
 492\section doc_addon_dict_1 Public C++ interface
 493
 494\code
 495class CScriptDictionary
 496{
 497public:
 498  // Memory management
 499  CScriptDictionary(asIScriptEngine *engine);
 500  void AddRef();
 501  void Release();
 502
 503  // Sets/Gets a variable type value for a key
 504  void Set(const std::string &key, void *value, int typeId);
 505  bool Get(const std::string &key, void *value, int typeId) const;
 506
 507  // Sets/Gets an integer number value for a key
 508  void Set(const std::string &key, asINT64 &value);
 509  bool Get(const std::string &key, asINT64 &value) const;
 510
 511  // Sets/Gets a real number value for a key
 512  void Set(const std::string &key, double &value);
 513  bool Get(const std::string &key, double &value) const;
 514
 515  // Returns true if the key is set
 516  bool Exists(const std::string &key) const;
 517  
 518  // Deletes the key
 519  void Delete(const std::string &key);
 520  
 521  // Deletes all keys
 522  void DeleteAll();
 523};
 524\endcode
 525
 526\section doc_addon_dict_2 Public script interface
 527
 528<pre>
 529  class dictionary
 530  {
 531    void set(const string &in key, ? &in value);
 532    bool get(const string &in value, ? &out value) const;
 533    
 534    void set(const string &in key, int64 &in value);
 535    bool get(const string &in key, int64 &out value) const;
 536    
 537    void set(const string &in key, double &in value);
 538    bool get(const string &in key, double &out value) const;
 539    
 540    bool exists(const string &in key) const;
 541    void delete(const string &in key);
 542    void deleteAll();
 543  }
 544</pre>
 545
 546\section doc_addon_dict_3 Script example
 547
 548<pre>
 549  dictionary dict;
 550  obj object;
 551  obj \@handle;
 552  
 553  dict.set("one", 1);
 554  dict.set("object", object);
 555  dict.set("handle", \@handle);
 556  
 557  if( dict.exists("one") )
 558  {
 559    bool found = dict.get("handle", \@handle);
 560    if( found )
 561    {
 562      dict.delete("object");
 563    }
 564  }
 565  
 566  dict.deleteAll();
 567</pre>
 568
 569
 570
 571
 572
 573\page doc_addon_file file object 
 574
 575<b>Path:</b> /sdk/add_on/scriptfile/
 576
 577This object provides support for reading and writing files.
 578
 579Register with <code>RegisterScriptFile(asIScriptEngine*)</code>.
 580
 581If you do not want to provide write access for scripts then you can compile 
 582the add on with the define AS_WRITE_OPS 0, which will disable support for writing. 
 583This define can be made in the project settings or directly in the header.
 584
 585
 586\section doc_addon_file_1 Public C++ interface
 587
 588\code
 589class CScriptFile
 590{
 591public:
 592  // Constructor
 593  CScriptFile();
 594
 595  // Memory management
 596  void AddRef();
 597  void Release();
 598
 599  // Opening and closing file handles
 600  // mode = "r" -> open the file for reading
 601  // mode = "w" -> open the file for writing (overwrites existing files)
 602  // mode = "a" -> open the file for appending
 603  int Open(const std::string &filename, const std::string &mode);
 604  int Close();
 605  
 606  // Returns the size of the file
 607  int GetSize() const;
 608  
 609  // Returns true if the end of the file has been reached
 610  bool IsEOF() const;
 611
 612  // Reads a specified number of bytes into the string
 613  int ReadString(unsigned int length, std::string &str);
 614  
 615  // Reads to the next new-line character
 616  int ReadLine(std::string &str);
 617  
 618  // Writes a string to the file
 619  int WriteString(const std::string &str);
 620  
 621  // File cursor manipulation
 622  int GetPos() const;
 623  int SetPos(int pos);
 624  int MovePos(int delta);
 625};
 626\endcode
 627
 628\section doc_addon_file_2 Public script interface
 629
 630<pre>
 631  class file
 632  {
 633    int      open(const string &in filename, const string &in mode);
 634    int      close();
 635    int      getSize() const;
 636    bool     isEndOfFile() const;
 637    int      readString(uint length, string &out str);
 638    int      readLine(string &out str);
 639    int      writeString(const string &in string);
 640    int      getPos() const;
 641    int      setPos(int pos);
 642    int      movePos(int delta);
 643  }
 644</pre>
 645
 646\section doc_addon_file_3 Script example
 647
 648<pre>
 649  file f;
 650  // Open the file in 'read' mode
 651  if( f.open("file.txt", "r") >= 0 ) 
 652  {
 653      // Read the whole file into the string buffer
 654      string str;
 655      f.readString(f.getSize(), str); 
 656      f.close();
 657  }
 658</pre>
 659
 660
 661
 662
 663
 664\page doc_addon_math math functions
 665
 666<b>Path:</b> /sdk/add_on/scriptmath/
 667
 668This add-on registers the math functions from the standard C runtime library with the script 
 669engine. Use <code>RegisterScriptMath(asIScriptEngine*)</code> to perform the registration.
 670
 671By defining the preprocessor word AS_USE_FLOAT=0, the functions will be registered to take 
 672and return doubles instead of floats.
 673
 674\section doc_addon_math_1 Public script interface
 675
 676<pre>
 677  float cos(float rad);
 678  float sin(float rad);
 679  float tan(float rad);
 680  float acos(float val);
 681  float asin(float val);
 682  float atan(float val);
 683  float atan2(float y, float x);
 684  float cosh(float rad);
 685  float sinh(float rad);
 686  float tanh(float rad);
 687  float log(float val);
 688  float log10(float val);
 689  float pow(float val, float exp);
 690  float sqrt(float val);
 691  float ceil(float val);
 692  float abs(float val);
 693  float floor(float val);
 694  float fraction(float val);
 695</pre>
 696 
 697
 698
 699 
 700 
 701\page doc_addon_math3d 3D math functions
 702
 703<b>Path:</b> /sdk/add_on/scriptmath3d/
 704
 705This add-on registers some value types and functions that permit the scripts to perform 
 7063D mathematical operations. Use <code>RegisterScriptMath3D(asIScriptEngine*)</code> to
 707perform the registration.
 708
 709Currently the only thing registered is the <code>vector3</code> type, representing a 3D vector, 
 710with basic math operators, such as add, subtract, scalar multiply, equality comparison, etc.
 711
 712This add-on serves mostly as a sample on how to register a value type. Application
 713developers will most likely want to register their own math library rather than use 
 714this add-on as-is. 
 715
 716
 717
 718
 719
 720
 721
 722\page doc_addon_build Script builder helper
 723
 724<b>Path:</b> /sdk/add_on/scriptbuilder/
 725
 726This class is a helper class for loading and building scripts, with a basic pre-processor 
 727that supports conditional compilation, include directives, and metadata declarations.
 728
 729By default the script builder resolves include directives by loading the included file 
 730from the relative directory of the file it is included from. If you want to do this in another
 731way, then you should implement the \ref doc_addon_build_1_1 "include callback" which will
 732let you process the include directive in a custom way, e.g. to load the included file from 
 733memory, or to support multiple search paths. The include callback should call the AddSectionFromFile or
 734AddSectionFromMemory to include the section in the current build.
 735
 736If you do not want process metadata then you can compile the add-on with the define 
 737AS_PROCESS_METADATA 0, which will exclude the code for processing this. This define
 738can be made in the project settings or directly in the header.
 739
 740
 741\section doc_addon_build_1 Public C++ interface
 742
 743\code
 744class CScriptBuilder
 745{
 746public:
 747  // Start a new module
 748  int StartNewModule(asIScriptEngine *engine, const char *moduleName);
 749
 750  // Load a script section from a file on disk
 751  int AddSectionFromFile(const char *filename);
 752
 753  // Load a script section from memory
 754  int AddSectionFromMemory(const char *scriptCode, 
 755                           const char *sectionName = "");
 756
 757  // Build the added script sections
 758  int BuildModule();
 759
 760  // Register the callback for resolving include directive
 761  void SetIncludeCallback(INCLUDECALLBACK_t callback, void *userParam);
 762
 763  // Add a pre-processor define for conditional compilation
 764  void DefineWord(const char *word);
 765
 766  // Get metadata declared for class types and interfaces
 767  const char *GetMetadataStringForType(int typeId);
 768
 769  // Get metadata declared for functions
 770  const char *GetMetadataStringForFunc(int funcId);
 771
 772  // Get metadata declared for global variables
 773  const char *GetMetadataStringForVar(int varIdx);
 774};
 775\endcode
 776
 777\subsection doc_addon_build_1_1 The include callback signature
 778
 779\code
 780// This callback will be called for each #include directive encountered by the
 781// builder. The callback should call the AddSectionFromFile or AddSectionFromMemory
 782// to add the included section to the script. If the include cannot be resolved
 783// then the function should return a negative value to abort the compilation.
 784typedef int (*INCLUDECALLBACK_t)(const char *include, const char *from, CScriptBuilder *builder, void *userParam);
 785\endcode
 786
 787\section doc_addon_build_2 Include directives
 788
 789Example script with include directive:
 790
 791<pre>
 792  \#include "commonfuncs.as"
 793  
 794  void main()
 795  {
 796    // Call a function from the included file
 797    CommonFunc();
 798  }
 799</pre>
 800
 801
 802\section doc_addon_build_condition Conditional programming
 803
 804The builder supports conditional programming through the \#if/\#endif preprocessor directives.
 805The application may define a word with a call to DefineWord(), then the scripts may check
 806for this definition in the code in order to include/exclude parts of the code.
 807
 808This is especially useful when scripts are shared between different binaries, for example, in a 
 809client/server application.
 810
 811Example script with conditional compilation:
 812
 813<pre>
 814  class CObject
 815  {
 816    void Process()
 817    {
 818  \#if SERVER
 819      // Do some server specific processing
 820  \#endif
 821
 822  \#if CLIENT
 823      // Do some client specific processing
 824  \#endif 
 825
 826      // Do some common processing
 827    }
 828  }
 829</pre>
 830
 831
 832
 833
 834
 835\section doc_addon_build_metadata Metadata in scripts
 836
 837Metadata can be added before script class, interface, function, and global variable 
 838declarations. The metadata is removed from the script by the builder class and stored
 839for post build lookup by the type id, function id, or variable index.
 840
 841Exactly what the metadata looks like is up to the application. The builder class doesn't
 842impose any rules, except that the metadata should be added between brackets []. After 
 843the script has been built the application can obtain the metadata strings and interpret
 844them as it sees fit.
 845
 846Example script with metadata:
 847
 848<pre>
 849  [factory func = CreateOgre,
 850   editable: myPosition,
 851   editable: myStrength [10, 100]]
 852  class COgre
 853  {
 854    vector3 myPosition;
 855    int     myStrength;
 856  }
 857  
 858  [factory]
 859  COgre \@CreateOgre()
 860  {
 861    return \@COgre();
 862  }
 863</pre>
 864
 865Example usage:
 866
 867\code
 868CScriptBuilder builder;
 869int r = builder.StartNewModule(engine, "my module");
 870if( r >= 0 )
 871  r = builder.AddSectionFromMemory(script);
 872if( r >= 0 )
 873  r = builder.BuildModule();
 874if( r >= 0 )
 875{
 876  // Find global variables that have been marked as editable by user
 877  asIScriptModule *mod = engine->GetModule("my module");
 878  int count = mod->GetGlobalVarCount();
 879  for( int n = 0; n < count; n++ )
 880  {
 881    string metadata = builder.GetMetadataStringForVar(n);
 882    if( metadata == "editable" )
 883    {
 884      // Show the global variable in a GUI
 885      ...
 886    }
 887  }
 888}
 889\endcode
 890
 891
 892
 893
 894\page doc_addon_autowrap Automatic wrapper functions
 895
 896<b>Path:</b> /sdk/add_on/autowrapper/aswrappedcall.h
 897
 898This header file declares some macros and template functions that will let the application developer
 899automatically generate wrapper functions using the \ref doc_generic "generic calling convention" with 
 900a simple call to a preprocessor macro. This is useful for those platforms where the native calling 
 901conventions are not yet supported.
 902
 903The macros are defined as
 904
 905\code
 906#define asDECLARE_FUNCTION_WRAPPER(wrapper_name,func)
 907#define asDECLARE_FUNCTION_WRAPPERPR(wrapper_name,func,params,rettype)
 908#define asDECLARE_METHOD_WRAPPER(wrapper_name,cl,func)
 909#define asDECLARE_METHOD_WRAPPERPR(wrapper_name,cl,func,params,rettype)
 910\endcode
 911
 912where wrapper_name is the name of the function that you want to generate, and func is a function pointer 
 913to the function you want to wrap, cl is the class name, params is the parameter list, and rettype is the return type. 
 914
 915Unfortunately the template functions needed to perform this generation are quite complex and older
 916compilers may not be able to handle them. One such example is Microsoft Visual C++ 6, though luckily 
 917it has no need for them as AngelScript already supports native calling conventions for it.
 918
 919\section doc_addon_autowrap_1 Example usage
 920
 921\code
 922#include "aswrappedcall.h"
 923
 924// The application function that we want to register
 925void DoSomething(std::string param1, int param2);
 926
 927// Generate the wrapper for the function
 928asDECLARE_FUNCTION_WRAPPER(DoSomething_Generic, DoSomething);
 929
 930// Registering the wrapper with AngelScript
 931void RegisterWrapper(asIScriptEngine *engine)
 932{
 933  int r;
 934
 935  r = engine->RegisterGlobalFunction("void DoSomething(string, int)", asFUNCTION(DoSomething_Generic), asCALL_GENERIC); assert( r >= 0 );
 936}
 937\endcode
 938
 939
 940
 941
 942
 943
 944\page doc_addon_clib ANSI C library interface
 945
 946<b>Path:</b> /sdk/add_on/clib/
 947
 948This add-on defines a pure C interface, that can be used in those applications that do not
 949understand C++ code but do understand C, e.g. Delphi, Java, and D.
 950
 951To compile the AngelScript C library, you need to compile the library source files in sdk/angelscript/source together 
 952with the source files in sdk/add-on/clib, and link them as a shared dynamic library. In the application that will use 
 953the AngelScript C library, you'll include the <code>angelscript_c.h</code> header file, instead of the ordinary 
 954<code>%angelscript.h</code> header file. After that you can use the library much the same way that it's used in C++. 
 955
 956To find the name of the C functions to call, you normally take the corresponding interface method
 957and give a prefix according to the following table:
 958
 959<table border=0 cellspacing=0 cellpadding=0>
 960<tr><td><b>interface      &nbsp;</b></td><td><b>prefix&nbsp;</b></td></tr>
 961<tr><td>asIScriptEngine   &nbsp;</td>    <td>asEngine_</td></tr>
 962<tr><td>asIScriptModule   &nbsp;</td>    <td>asModule_</td></tr>
 963<tr><td>asIScriptContext  &nbsp;</td>    <td>asContext_</td></tr>
 964<tr><td>asIScriptGeneric  &nbsp;</td>    <td>asGeneric_</td></tr>
 965<tr><td>asIScriptArray    &nbsp;</td>    <td>asArray_</td></tr>
 966<tr><td>asIScriptObject   &nbsp;</td>    <td>asObject_</td></tr>
 967<tr><td>asIObjectType     &nbsp;</td>    <td>asObjectType_</td></tr>
 968<tr><td>asIScriptFunction &nbsp;</td>    <td>asScriptFunction_</td></tr>
 969</table>
 970
 971All interface methods take the interface pointer as the first parameter when in the C function format, the rest
 972of the parameters are the same as in the C++ interface. There are a few exceptions though, e.g. all parameters that
 973take an <code>asSFuncPtr</code> take a normal function pointer in the C function format. 
 974
 975Example:
 976
 977\code
 978#include <stdio.h>
 979#include <assert.h>
 980#include "angelscript_c.h"
 981
 982void MessageCallback(asSMessageInfo *msg, void *);
 983void PrintSomething();
 984
 985int main(int argc, char **argv)
 986{
 987  int r = 0;
 988
 989  // Create and initialize the script engine
 990  asIScriptEngine *engine = asCreateScriptEngine(ANGELSCRIPT_VERSION);
 991  r = asEngine_SetMessageCallback(engine, (asFUNCTION_t)MessageCallback, 0, asCALL_CDECL); assert( r >= 0 );
 992  r = asEngine_RegisterGlobalFunction(engine, "void print()", (asFUNCTION_t)PrintSomething, asCALL_CDECL); assert( r >= 0 );
 993
 994  // Execute a simple script
 995  r = asEngine_ExecuteString(engine, 0, "print()", 0, 0);
 996  if( r != asEXECUTION_FINISHED )
 997  {
 998      printf("Something wen't wrong with the execution\n");
 999  }
1000  else
1001  {
1002      printf("The script was executed successfully\n");
1003  }
1004
1005  // Release the script engine
1006  asEngine_Release(engine);
1007  
1008  return r;
1009}
1010
1011void MessageCallback(asSMessageInfo *msg, void *)
1012{
1013  const char *msgType = 0;
1014  if( msg->type == 0 ) msgType = "Error  ";
1015  if( msg->type == 1 ) msgType = "Warning";
1016  if( msg->type == 2 ) msgType = "Info   ";
1017
1018  printf("%s (%d, %d) : %s : %s\n", msg->section, msg->row, msg->col, msgType, msg->message);
1019}
1020
1021void PrintSomething()
1022{
1023  printf("Called from the script\n");
1024}
1025\endcode
1026
1027
1028
1029\page doc_addon_helpers Helper functions
1030
1031<b>Path:</b> /sdk/add_on/scripthelper/
1032
1033These helper functions simplify the implemention of common tasks. They can be used as is
1034or can serve as the starting point for your own framework.
1035
1036\section doc_addon_helpers_1 Public C++ interface
1037
1038\code
1039// Compare relation between two objects of the same type.
1040// Uses the object's opCmp method to perform the comparison.
1041// Returns a negative value if the comparison couldn't be performed.
1042int CompareRelation(asIScriptEngine *engine, void *leftObj, void *rightObj, int typeId, int &result);
1043
1044// Compare equality between two objects of the same type.
1045// Uses the object's opEquals method to perform the comparison, or if that doesn't exist the opCmp method.
1046// Returns a negative value if the comparison couldn't be performed.
1047int CompareEquality(asIScriptEngine *engine, void *leftObj, void *rightObj, int typeId, bool &result);
1048
1049// Compile and execute simple statements.
1050// The module is optional. If given the statements can access the entities compiled in the module.
1051// The caller can optionally provide its own context, for example if a context should be reused.
1052int ExecuteString(asIScriptEngine *engine, const char *code, asIScriptModule *mod = 0, asIScriptContext *ctx = 0);
1053\endcode
1054
1055\section doc_addon_helpers_2 Example
1056
1057To compare two script objects the application can execute the following code:
1058
1059\code
1060void Compare(asIScriptObject *a, asIScriptObject *b)
1061{
1062  asIScriptEngine *engine = a->GetEngine();
1063  int typeId = a->GetTypeId();
1064
1065  int cmp;
1066  int r = CompareRelation(engine, a, b, typeId, cmp);
1067  if( r < 0 )
1068  {
1069    cout << "The relation between a and b cannot be established b" << endl;
1070  }
1071  else
1072  {
1073    if( cmp < 0 )
1074      cout << "a is smaller than b" << endl;
1075    else if( cmp == 0 )
1076      cout << "a is equal to b" << endl;
1077    else
1078      cout << "a is greater than b" << endl;
1079  }
1080}
1081\endcode
1082
1083*/