/xbmc/visualizations/Vortex/angelscript/docs/manual/doc_register_val_type.html

http://github.com/xbmc/xbmc · HTML · 66 lines · 62 code · 3 blank · 1 comment · 0 complexity · 1f65b7f1ce70d8ef990e9ce267ac27c1 MD5 · raw file 

    

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2. 

  2. <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
    3. 

  3. <title>AngelScript: Registering a value type</title>
    4. 

  4. <link href="tabs.css" rel="stylesheet" type="text/css">
    5. 

  5. <link href="doxygen.css" rel="stylesheet" type="text/css">
    6. 

  6. </head><body>
    7. 

  7. <!-- Generated by Doxygen 1.5.9 -->
    8. 

  8. <div class="contents">
    9. 

  9. <h1><a class="anchor" name="doc_register_val_type">Registering a value type </a></h1>When registering a value type, the size of the type must be given so that AngelScript knows how much space is needed for it. If the type doesn't require any special treatment, i.e. doesn't contain any pointers or other resource references that must be maintained, then the type can be registered with the flag <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a8ad017ddf25368870b28ee0fba96495a">asOBJ_POD</a>. In this case AngelScript doesn't require the default constructor, assignment behaviour, or destructor as it will be able to automatically handle these cases the same way it handles built-in primitives.<p>
    10. 

  10. If you plan on passing the or returning the type by value to registered functions that uses native calling convention, you also need to inform <a class="el" href="doc_register_val_type.html#doc_reg_val_2">how the type is implemented in the application</a>, but if you only plan on using generic calling conventions, or don't pass these types by value then you don't need to worry about that.<p>
    11. 

  11. <div class="fragment"><pre class="fragment"><span class="comment">// Register a primitive type, that doesn't need any special management of the content</span>
    12. 

  12. r = engine-&gt;<a class="code" href="classas_i_script_engine.html#29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">"pod"</span>, <span class="keyword">sizeof</span>(pod), <a class="code" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a> | <a class="code" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a8ad017ddf25368870b28ee0fba96495a" title="A plain-old-data type. Only valid for value types.">asOBJ_POD</a>); assert( r &gt;= 0 );
    13. 

  13. 

  14. <span class="comment">// Register a class that must be properly initialized and uninitialized</span>
    15. 

  15. r = engine-&gt;<a class="code" href="classas_i_script_engine.html#29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">"val"</span>, <span class="keyword">sizeof</span>(val), <a class="code" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a>); assert( r &gt;= 0 );
    16. 

  16. </pre></div><p>
    17. 

  17. <dl class="see" compact><dt><b>See also:</b></dt><dd>The <a class="el" href="doc_addon_std_string.html">string object (STL)</a> or <a class="el" href="doc_addon_math3d.html">vector3</a> add-on for examples of value types</dd></dl>
    18. 

  18. <h2><a class="anchor" name="doc_reg_val_1">
    19. 

  19. Constructor and destructor</a></h2>
    20. 

  20. If a constructor or destructor is needed they shall be registered the following way:<p>
    21. 

  21. <div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> Constructor(<span class="keywordtype">void</span> *memory)
    22. 

  22. {
    23. 

  23.   <span class="comment">// Initialize the pre-allocated memory by calling the</span>
    24. 

  24.   <span class="comment">// object constructor with the placement-new operator</span>
    25. 

  25.   <span class="keyword">new</span>(memory) Object();
    26. 

  26. }
    27. 

  27. 

  28. <span class="keywordtype">void</span> Destructor(<span class="keywordtype">void</span> *memory)
    29. 

  29. {
    30. 

  30.   <span class="comment">// Uninitialize the memory by calling the object destructor</span>
    31. 

  31.   ((Object*)memory)-&gt;~Object();
    32. 

  32. }
    33. 

  33. 

  34. <span class="comment">// Register the behaviours</span>
    35. 

  35. r = engine-&gt;<a class="code" href="classas_i_script_engine.html#7ea3c93dea338b0287027de0e4895dcb" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">"val"</span>, <a class="code" href="angelscript_8h.html#7e38df5b10ec8cbf2a688f1d114097c5a4cf235bfbf72ec03d0f651cea324101" title="Constructor.">asBEHAVE_CONSTRUCT</a>, <span class="stringliteral">"void f()"</span>, <a class="code" href="angelscript_8h.html#78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(Constructor), <a class="code" href="angelscript_8h.html#3ec92ea3c4762e44c2df788ceccdd1e4c08652c72f1cc0dc81c37812fab0e253" title="A cdecl function that takes the object pointer as the last parameter.">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );
    36. 

  36. r = engine-&gt;<a class="code" href="classas_i_script_engine.html#7ea3c93dea338b0287027de0e4895dcb" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">"val"</span>, <a class="code" href="angelscript_8h.html#7e38df5b10ec8cbf2a688f1d114097c50748a0f3a559354761ce15c2d1de2e51" title="Destructor.">asBEHAVE_DESTRUCT</a>, <span class="stringliteral">"void f()"</span>, <a class="code" href="angelscript_8h.html#78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(Destructor), <a class="code" href="angelscript_8h.html#3ec92ea3c4762e44c2df788ceccdd1e4c08652c72f1cc0dc81c37812fab0e253" title="A cdecl function that takes the object pointer as the last parameter.">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );
    37. 

  37. </pre></div><h2><a class="anchor" name="doc_reg_val_2">
    38. 

  38. Value types and native calling conventions</a></h2>
    39. 

  39. If the type will be passed to and from the application by value using native calling conventions, it is important to inform AngelScript of its real type in C++, otherwise AngelScript won't be able to determine exactly how C++ is treating the type in a parameter or return value.<p>
    40. 

  40. There are a few different flags for this:<p>
    41. 

  41. <table border="0" cellspacing="0" cellpadding="0">
    42. 

  42. <tr>
    43. 

  43. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a> &nbsp; </td><td>The C++ type is a class, struct, or union </td></tr>
    44. 

  44. <tr>
    45. 

  45. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7afd799c0705cee720a12ceb2838796024">asOBJ_APP_CLASS_CONSTRUCTOR</a> &nbsp; </td><td>The C++ type has a defined constructor </td></tr>
    46. 

  46. <tr>
    47. 

  47. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a18d80c6d92e4bc104955da393c966917">asOBJ_APP_CLASS_DESTRUCTOR</a> &nbsp; </td><td>The C++ type has a defined destructor </td></tr>
    48. 

  48. <tr>
    49. 

  49. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a6bf9b7bead31a40e7983538d8cecc3a4">asOBJ_APP_CLASS_ASSIGNMENT</a> &nbsp; </td><td>The C++ type has a defined assignment operator </td></tr>
    50. 

  50. <tr>
    51. 

  51. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a539ede421d313b03464c88cb15f08c75">asOBJ_APP_PRIMITIVE</a> &nbsp; </td><td>The C++ type is a C++ primitive, but not a float or double </td></tr>
    52. 

  52. <tr>
    53. 

  53. <td><a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a7f7690d53d9bfc580e09ac7bf5868175">asOBJ_APP_FLOAT</a> &nbsp; </td><td>The C++ type is a float or double </td></tr>
    54. 

  54. </table>
    55. 

  55. <p>
    56. 

  56. Note that these don't represent how the type will behave in the script language, only what the real type is in the host application. So if you want to register a C++ class that you want to behave as a primitive type in the script language you should still use the flag <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a>. The same thing for the flags to identify that the class has a constructor, destructor, or assignment. These flags tell AngelScript that the class has the respective function, but not that the type in the script language should have these behaviours.<p>
    57. 

  57. For class types there are also a shorter form of the flags for each combination of the 4 flags. They are of the form <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7ae13159e3ea949d52803cb635538a77f2">asOBJ_APP_CLASS_CDA</a>, where the existance of the last letters determine if the constructor, destructor, and/or assignment behaviour are available. For example <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7ae13159e3ea949d52803cb635538a77f2">asOBJ_APP_CLASS_CDA</a> is defined as <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a> | <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7afd799c0705cee720a12ceb2838796024">asOBJ_APP_CLASS_CONSTRUCTOR</a> | <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a18d80c6d92e4bc104955da393c966917">asOBJ_APP_CLASS_DESTRUCTOR</a> | <a class="el" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a6bf9b7bead31a40e7983538d8cecc3a4">asOBJ_APP_CLASS_ASSIGNMENT</a>.<p>
    58. 

  58. <div class="fragment"><pre class="fragment"><span class="comment">// Register a complex type that will be passed by value to the application</span>
    59. 

  59. r = engine-&gt;<a class="code" href="classas_i_script_engine.html#29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">"complex"</span>, <span class="keyword">sizeof</span>(complex), <a class="code" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7a9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a> | <a class="code" href="angelscript_8h.html#855d86fa9ee15b9f75e553ee376b5c7ae13159e3ea949d52803cb635538a77f2" title="The C++ type is a class with a constructor, destructor, and assignment operator.">asOBJ_APP_CLASS_CDA</a>); assert( r &gt;= 0 );
    60. 

  60. </pre></div><p>
    61. 

  61. Make sure you inform these flags correctly, because if you do not you may get various errors when executing the scripts. Common problems are stack corruptions, and invalid memory accesses. In some cases you may face more silent errors that may be difficult to detect, e.g. the function is not returning the expected values. </div>
    62. 

  62. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Dec 16 19:34:51 2009 for AngelScript by&nbsp;
    63. 

  63. <a href="http://www.doxygen.org/index.html">
    64. 

  64. <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
    65. 

  65. </body>
    66. 

  66. </html>
    67.