147 lines
12 KiB
HTML
147 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<meta name="generator" content="Doxygen 1.8.18"/>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
|
|
<title>AngelScript: The generic calling convention</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="resize.js"></script>
|
||
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
||
|
|
<script type="text/javascript" src="navtree.js"></script>
|
||
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
|
|
<script type="text/javascript" src="search/search.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function() { init_search(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
|
||
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">AngelScript
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
<td> <div id="MSearchBox" class="MSearchBoxInactive">
|
||
|
|
<span class="left">
|
||
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
alt=""/>
|
||
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
||
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
||
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
||
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
||
|
|
</span><span class="right">
|
||
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
||
|
|
</span>
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<!-- Generated by Doxygen 1.8.18 -->
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
|
|
<div id="nav-tree">
|
||
|
|
<div id="nav-tree-contents">
|
||
|
|
<div id="nav-sync" class="sync"></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
||
|
|
class="ui-resizable-handle">
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function(){initNavTree('doc_generic.html',''); initResizable(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<div id="doc-content">
|
||
|
|
<!-- window showing the filter options -->
|
||
|
|
<div id="MSearchSelectWindow"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<!-- iframe showing the search results (closed by default) -->
|
||
|
|
<div id="MSearchResultsWindow">
|
||
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
||
|
|
name="MSearchResults" id="MSearchResults">
|
||
|
|
</iframe>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="PageDoc"><div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">The generic calling convention </div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><p>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="group__api__auxiliary__functions.html#gaba86cba765a7148e2a306b4305ba48f9">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>
|
||
|
|
<p>Functions 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>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// The function has been registered with signature:</span></div>
|
||
|
|
<div class="line"><span class="comment">// MyIntf @func(int, float, MyIntf @+)</span></div>
|
||
|
|
<div class="line"><span class="keywordtype">void</span> MyGenericFunction(<a class="code" href="classas_i_script_generic.html">asIScriptGeneric</a> *gen)</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// Extract the arguments</span></div>
|
||
|
|
<div class="line"> <span class="keywordtype">int</span> arg0 = gen-><a class="code" href="classas_i_script_generic.html#aab74bcbe4be32fc423b21b75a3f4d57a">GetArgDWord</a>(0);</div>
|
||
|
|
<div class="line"> <span class="keywordtype">float</span> arg1 = gen-><a class="code" href="classas_i_script_generic.html#a487a68e409d79e61fcc624337c4ac991">GetArgFloat</a>(1);</div>
|
||
|
|
<div class="line"> <a class="code" href="classas_i_script_object.html">asIScriptObject</a> *arg2 = <span class="keyword">reinterpret_cast<</span><a class="code" href="classas_i_script_object.html">asIScriptObject</a>*<span class="keyword">></span>(gen-><a class="code" href="classas_i_script_generic.html#a6732b01132cd58e81cd0354ac274039a">GetArgObject</a>(2));</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"> <span class="comment">// Call the real function</span></div>
|
||
|
|
<div class="line"> <a class="code" href="classas_i_script_object.html">asIScriptObject</a> *ret = MyFunction(arg0, arg1, arg2);</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"> <span class="comment">// Set the return value</span></div>
|
||
|
|
<div class="line"> gen-><a class="code" href="classas_i_script_generic.html#a94c9ca32722cb44b09211e51fa906e6e">SetReturnObject</a>(ret);</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>Functions 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>
|
||
|
|
<p>Writing 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 desired to use the <a class="el" href="doc_addon_autowrap.html">automatic wrapper functions</a> rather than writing the functions yourself.</p>
|
||
|
|
<h1><a class="anchor" id="doc_generic_1"></a>
|
||
|
|
Extracting function arguments</h1>
|
||
|
|
<p>To 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#a08f922bc97867e1e97e923a5bdee4dbc">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>
|
||
|
|
<p>If 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#ab9e6627ec3920b1e1576d82586cac84d">GetObject</a>.</p>
|
||
|
|
<p>The <a class="el" href="classas_i_script_generic.html" title="The interface for the generic calling convention.">asIScriptGeneric</a> interfaces treats the ref count the same way as in native calling conventions, i.e. the application function is responsible to releasing any handle received as a handle (or <a class="el" href="doc_obj_handle.html#doc_obj_handle_4">register the function with +</a>).</p>
|
||
|
|
<h1><a class="anchor" id="doc_generic_2"></a>
|
||
|
|
Returning values</h1>
|
||
|
|
<p>To 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#afd8ead96f17d6e77f3a26c70c3a1d80c">SetReturnAddress</a> and <a class="el" href="classas_i_script_generic.html#a94c9ca32722cb44b09211e51fa906e6e">SetReturnObject</a> to determine what needs to be done to get the expected result.</p>
|
||
|
|
<p>It is also possible to use the <a class="el" href="classas_i_script_generic.html#a103a91f081ec894a116cd3db06b0d8d1">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>.</p>
|
||
|
|
<p>If the function is registered to return a +, then the script engine will <a class="el" href="doc_obj_handle.html#doc_obj_handle_4">automatically increment the ref count</a>, just as is done for native calling conventions. </p>
|
||
|
|
</div></div><!-- contents -->
|
||
|
|
</div><!-- PageDoc -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<div class="ttc" id="aclassas_i_script_generic_html_a94c9ca32722cb44b09211e51fa906e6e"><div class="ttname"><a href="classas_i_script_generic.html#a94c9ca32722cb44b09211e51fa906e6e">asIScriptGeneric::SetReturnObject</a></div><div class="ttdeci">virtual int SetReturnObject(void *obj)=0</div><div class="ttdoc">Sets the object return value.</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_script_generic_html_a487a68e409d79e61fcc624337c4ac991"><div class="ttname"><a href="classas_i_script_generic.html#a487a68e409d79e61fcc624337c4ac991">asIScriptGeneric::GetArgFloat</a></div><div class="ttdeci">virtual float GetArgFloat(asUINT arg)=0</div><div class="ttdoc">Returns the value of a float argument.</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_script_generic_html_a6732b01132cd58e81cd0354ac274039a"><div class="ttname"><a href="classas_i_script_generic.html#a6732b01132cd58e81cd0354ac274039a">asIScriptGeneric::GetArgObject</a></div><div class="ttdeci">virtual void * GetArgObject(asUINT arg)=0</div><div class="ttdoc">Returns a pointer to the object in a object argument.</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_script_generic_html"><div class="ttname"><a href="classas_i_script_generic.html">asIScriptGeneric</a></div><div class="ttdoc">The interface for the generic calling convention.</div><div class="ttdef"><b>Definition:</b> angelscript.h:3242</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_script_generic_html_aab74bcbe4be32fc423b21b75a3f4d57a"><div class="ttname"><a href="classas_i_script_generic.html#aab74bcbe4be32fc423b21b75a3f4d57a">asIScriptGeneric::GetArgDWord</a></div><div class="ttdeci">virtual asDWORD GetArgDWord(asUINT arg)=0</div><div class="ttdoc">Returns the value of a 32-bit integer argument.</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_script_object_html"><div class="ttname"><a href="classas_i_script_object.html">asIScriptObject</a></div><div class="ttdoc">The interface for an instance of a script object.</div><div class="ttdef"><b>Definition:</b> angelscript.h:3413</div></div>
|
||
|
|
<!-- start footer part -->
|
||
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
|
|
<ul>
|
||
|
|
<li class="footer">Generated on Sat Dec 5 2020 23:20:24 for AngelScript by
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|