157 lines
14 KiB
HTML
157 lines
14 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: Registering a scoped reference type</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_adv_scoped_type.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">Registering a scoped reference type </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>Some C++ value types have special requirements for the memory where they are located, e.g. specific alignment needs, or memory pooling. Since AngelScript doesn't provide that much control over where and how value types are allocated, they must be registered as reference types. In this case you'd register the type as a scoped reference type.</p>
|
|
<p>A scoped reference type will have the life time controlled by the scope of the variable that instanciate it, i.e. as soon as the variable goes out of scope the instance is destroyed. This means that the type doesn't permit handles to be taken for the type.</p>
|
|
<p>A scoped reference type requires only that the release behaviour is registered. The addref behaviour is not permitted. If the factory behaviour is not registered the script will not be able to instanciate objects of this type, but it can still receive them as parameters from the application.</p>
|
|
<p>Since no handles can be taken for the object type, there is no need to keep track of the number of references held to the object. This means that the release behaviour should simply destroy and deallocate the object as soon as it's called.</p>
|
|
<div class="fragment"><div class="line">scoped *Scoped_Factory()</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">new</span> scoped;</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordtype">void</span> Scoped_Release(scoped *s)</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="keywordflow">if</span>( s ) <span class="keyword">delete</span> s;</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Registering a scoped reference type</span></div>
|
|
<div class="line">r = engine-><a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6">RegisterObjectType</a>(<span class="stringliteral">"scoped"</span>, 0, <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861">asOBJ_REF</a> | <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aaaae92b24e278976320f19d9dc75fe6db">asOBJ_SCOPED</a>); assert( r >= 0 );</div>
|
|
<div class="line">r = engine-><a class="code" href="classas_i_script_engine.html#a9f122dd87394f3a83ac766ea19f37317">RegisterObjectBehaviour</a>(<span class="stringliteral">"scoped"</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a0b3db16eea35213b6f41f8d19dc1bd4c">asBEHAVE_FACTORY</a>, <span class="stringliteral">"scoped @f()"</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a>(Scoped_Factory), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4">asCALL_CDECL</a>); assert( r >= 0 );</div>
|
|
<div class="line">r = engine-><a class="code" href="classas_i_script_engine.html#a9f122dd87394f3a83ac766ea19f37317">RegisterObjectBehaviour</a>(<span class="stringliteral">"scoped"</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c">asBEHAVE_RELEASE</a>, <span class="stringliteral">"void f()"</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a>(Scoped_Release), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253">asCALL_CDECL_OBJLAST</a>); assert( r >= 0 );</div>
|
|
</div><!-- fragment --><p>Unfortunately any function that either takes or returns the type by value in C++ must be wrapped in order to permit AngelScript to manage the life time of the values.</p>
|
|
<p>Here's an example of a function that takes a value and returns another and the corresponding wrapper.</p>
|
|
<div class="fragment"><div class="line">scoped Foo(scoped a)</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> scoped b;</div>
|
|
<div class="line"> <span class="keywordflow">return</span> b;</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line">scoped *Foo_wrapper(<span class="keyword">const</span> scoped &a)</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">new</span> scoped(Foo(a));</div>
|
|
<div class="line">}</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Registering the function</span></div>
|
|
<div class="line">r = engine-><a class="code" href="classas_i_script_engine.html#a2f84b9b51733f22c68b8448b02c2f1c7">RegisterGlobalFunction</a>(<span class="stringliteral">"scoped @Foo(const scoped &in)"</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a>(Foo_wrapper), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4">asCALL_CDECL</a>); assert( r >= 0 );</div>
|
|
</div><!-- fragment --><p>Observe how the function is registered to return the scoped value by handle even though the scoped types really don't support handles. This is done because AngelScript will call Release on the returned instance after it is done with the value it received.</p>
|
|
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_reg_basicref.html">Registering a reference type</a> </dd></dl>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<div class="ttc" id="aangelscript_8h_html_a855d86fa9ee15b9f75e553ee376b5c7aaaae92b24e278976320f19d9dc75fe6db"><div class="ttname"><a href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aaaae92b24e278976320f19d9dc75fe6db">asOBJ_SCOPED</a></div><div class="ttdeci">@ asOBJ_SCOPED</div><div class="ttdoc">The life time of objects of this type are controlled by the scope of the variable....</div><div class="ttdef"><b>Definition:</b> angelscript.h:260</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7e38df5b10ec8cbf2a688f1d114097c5a0b3db16eea35213b6f41f8d19dc1bd4c"><div class="ttname"><a href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a0b3db16eea35213b6f41f8d19dc1bd4c">asBEHAVE_FACTORY</a></div><div class="ttdeci">@ asBEHAVE_FACTORY</div><div class="ttdoc">Factory.</div><div class="ttdef"><b>Definition:</b> angelscript.h:362</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c"><div class="ttname"><a href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a7134ce13c81967191af401a1e5170a0c">asBEHAVE_RELEASE</a></div><div class="ttdeci">@ asBEHAVE_RELEASE</div><div class="ttdoc">Release.</div><div class="ttdef"><b>Definition:</b> angelscript.h:368</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253"><div class="ttname"><a href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253">asCALL_CDECL_OBJLAST</a></div><div class="ttdeci">@ asCALL_CDECL_OBJLAST</div><div class="ttdoc">A cdecl function that takes the object pointer as the last parameter.</div><div class="ttdef"><b>Definition:</b> angelscript.h:234</div></div>
|
|
<div class="ttc" id="aclassas_i_script_engine_html_a29c6c087c8c5b5cdb6271cfd161cc5a6"><div class="ttname"><a href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6">asIScriptEngine::RegisterObjectType</a></div><div class="ttdeci">virtual int RegisterObjectType(const char *obj, int byteSize, asDWORD flags)=0</div><div class="ttdoc">Registers a new object type.</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861"><div class="ttname"><a href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9450e038342b36c745858d2e5ae4b861">asOBJ_REF</a></div><div class="ttdeci">@ asOBJ_REF</div><div class="ttdoc">A reference type.</div><div class="ttdef"><b>Definition:</b> angelscript.h:250</div></div>
|
|
<div class="ttc" id="aclassas_i_script_engine_html_a9f122dd87394f3a83ac766ea19f37317"><div class="ttname"><a href="classas_i_script_engine.html#a9f122dd87394f3a83ac766ea19f37317">asIScriptEngine::RegisterObjectBehaviour</a></div><div class="ttdeci">virtual int RegisterObjectBehaviour(const char *obj, asEBehaviours behaviour, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0, int compositeOffset=0, bool isCompositeIndirect=false)=0</div><div class="ttdoc">Registers a behaviour for the object type.</div></div>
|
|
<div class="ttc" id="aclassas_i_script_engine_html_a2f84b9b51733f22c68b8448b02c2f1c7"><div class="ttname"><a href="classas_i_script_engine.html#a2f84b9b51733f22c68b8448b02c2f1c7">asIScriptEngine::RegisterGlobalFunction</a></div><div class="ttdeci">virtual int RegisterGlobalFunction(const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0)=0</div><div class="ttdoc">Registers a global function.</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a78f8f2c7f1c88b12e74a5ac47b4184ae"><div class="ttname"><a href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a></div><div class="ttdeci">#define asFUNCTION(f)</div><div class="ttdoc">Returns an asSFuncPtr representing the function specified by the name.</div><div class="ttdef"><b>Definition:</b> angelscript.h:675</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html_a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4"><div class="ttname"><a href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4">asCALL_CDECL</a></div><div class="ttdeci">@ asCALL_CDECL</div><div class="ttdoc">A cdecl function.</div><div class="ttdef"><b>Definition:</b> angelscript.h:226</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>
|