PageRenderTime 26ms CodeModel.GetById 17ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

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

http://github.com/xbmc/xbmc
HTML | 31 lines | 30 code | 0 blank | 1 comment | 0 complexity | 94cf6dac9fd5311c285190714761774e MD5 | raw file
 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
 3<title>AngelScript: The generic calling convention</title>
 4<link href="tabs.css" rel="stylesheet" type="text/css">
 5<link href="doxygen.css" rel="stylesheet" type="text/css">
 6</head><body>
 7<!-- Generated by Doxygen 1.5.9 -->
 8<div class="contents">
 9<h1><a class="anchor" name="doc_generic">The generic calling convention </a></h1>The generic calling convention is available for those situations where the application's native calling convention doesn't work, for example on platforms where support for native calling conventions haven't been added yet. You can detect if native calling conventions isn't supported on your target platform by calling the <a class="el" href="angelscript_8h.html#ba86cba765a7148e2a306b4305ba48f9">asGetLibraryOptions</a> function and checking the returned string for "AS_MAX_PORTABILITY". If the identifier is in the returned string, then native calling conventions is not supported.<p>
10Functions implementing the generic calling conventions are always global functions (or static class methods), that take as parameter a pointer to an <a class="el" href="classas_i_script_generic.html" title="The interface for the generic calling convention.">asIScriptGeneric</a> interface and returns void.<p>
11<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> MyGenericFunction(<a class="code" href="classas_i_script_generic.html" title="The interface for the generic calling convention.">asIScriptGeneric</a> *gen)
12{
13  <span class="comment">// Code to extract arguments from the generic </span>
14  <span class="comment">// interface and to execute the real function</span>
15  ...
16}
17</pre></div><p>
18Functions using the generic calling convention can be registered anywhere the script engine is expecting global functions or class methods (except where explicitly written otherwise).<p>
19Writing the functions for the generic calling convention requires extracting each argument from the AngelScript stack, and then manually giving the return value back. For that reason it may be a desired to use the <a class="el" href="doc_addon_autowrap.html">automatic wrapper functions</a> rather than writing the functions yourself.<h2><a class="anchor" name="doc_generic_1">
20Extracting function arguments</a></h2>
21To extract functions arguments from the generic interface you should call one of the GetArg methods that will return the value of the argument, or the <a class="el" href="classas_i_script_generic.html#08f922bc97867e1e97e923a5bdee4dbc">GetAddressOfArg</a> method. The GetAddressOfArg method returns a pointer to the actual value. The application should then cast this pointer to a pointer of the correct type so that the value can be read from the address.<p>
22If the function you're implementing represents a class method, the pointer to the object instance should be obtained with a call to <a class="el" href="classas_i_script_generic.html#b9e6627ec3920b1e1576d82586cac84d">GetObject</a>.<p>
23Note that the <a class="el" href="classas_i_script_generic.html" title="The interface for the generic calling convention.">asIScriptGeneric</a> interface is the owner of any references it returns with these calls, so you should not release these references manually. If you want to store a reference to an object received from the generic interface, you need to call AddRef on that object to avoid invalidating the reference when the function returns.<h2><a class="anchor" name="doc_generic_2">
24Returning values</a></h2>
25To return a value from the function one of the SetReturn methods can be called to pass the value to the generic interface. Returning primitive values is straight forward, but care must be taken when returning object types, either by value, reference, or as object handle. Depending on the type and the function used it may be necessary to increment the reference count, or even make a copy of the object first. Carefully read the instructions for <a class="el" href="classas_i_script_generic.html#fd8ead96f17d6e77f3a26c70c3a1d80c">SetReturnAddress</a> and <a class="el" href="classas_i_script_generic.html#94c9ca32722cb44b09211e51fa906e6e">SetReturnObject</a> to determine what needs to be done to get the expected result.<p>
26It is also possible to use the <a class="el" href="classas_i_script_generic.html#103a91f081ec894a116cd3db06b0d8d1">GetAddressOfReturnLocation</a> method to obtain the address of the memory where the return value will be stored. The memory is not initialized, so you should use the placement new operator to initialize this memory with a call to the constructor. This also works for primitive types, which makes this ideal for template implementations, such as that in the <a class="el" href="doc_addon_autowrap.html">automatic wrapper functions</a>. </div>
27<hr size="1"><address style="text-align: right;"><small>Generated on Wed Dec 16 19:34:50 2009 for AngelScript by&nbsp;
28<a href="http://www.doxygen.org/index.html">
29<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
30</body>
31</html>