163 lines
9.4 KiB
HTML
163 lines
9.4 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: Object handles to the application</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_obj_handle.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">Object handles to the application </div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><p>In AngelScript an object handle is a reference counted pointer to an object. In the scripts they are used to pass the objects around by reference instead of by value. Depending on how an application type is registered the type will support handles.</p>
|
||
|
|
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_register_type.html">Registering an object type</a>, <a class="el" href="doc_script_handle.html">Object handles</a> in the script language</dd></dl>
|
||
|
|
<h1><a class="anchor" id="doc_obj_handle_3"></a>
|
||
|
|
Managing the reference counter in functions</h1>
|
||
|
|
<p>Whenever the object handle is passed by value from the application to the script engine, or vice versa its reference should be accounted for. This means that the application must release any object handles it receives as parameters when it no longer needs them, it also means that the application must increase the reference counter for any object handle being returned to the script engine. This also applies to the <a class="el" href="doc_generic.html">generic calling convention</a>.</p>
|
||
|
|
<p>A function that creates an object and returns it to the script engine might look like this:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// Registered as "obj@ CreateObject()"</span></div>
|
||
|
|
<div class="line">obj *CreateObject()</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// The constructor already initializes the ref count to 1</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">return</span> <span class="keyword">new</span> obj();</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>A function that receives an object handle from the script and stores it in a global variable might look like this:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// Registered as "void StoreObject(obj@)"</span></div>
|
||
|
|
<div class="line">obj *o = 0;</div>
|
||
|
|
<div class="line"><span class="keywordtype">void</span> StoreObject(obj *newO)</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// Release the old object handle</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>( o ) o->Release();</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"> <span class="comment">// Store the new object handle</span></div>
|
||
|
|
<div class="line"> o = newO;</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>A function that retrieves a previously stored object handle might look like this:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// Registered as "obj@ RetrieveObject()"</span></div>
|
||
|
|
<div class="line">obj *RetrieveObject()</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// Increase the reference counter to account for the returned handle</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>( o ) o->AddRef();</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"> <span class="comment">// It is ok to return null if there is no previous handle stored</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">return</span> o;</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>A function that receives an object handle in the parameter, but doesn't store it looks like this:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// Registered as "void DoSomething(obj@)"</span></div>
|
||
|
|
<div class="line"><span class="keywordtype">void</span> DoSomething(obj *o)</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// When finished with the object it must be released</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>( o ) o->Release();</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><h1><a class="anchor" id="doc_obj_handle_4"></a>
|
||
|
|
Auto handles can make it easier</h1>
|
||
|
|
<p>The application can use auto handles (@+) to alleviate some of the work of managing the reference counter. When registering the function or method with AngelScript, add a plus sign to the object handles that AngelScript should automatically manage. For parameters AngelScript will then release the reference after the function returns, and for the return value AngelScript will increase the reference on the returned pointer. The reference for the returned value is increased before the parameters are released, so it is possible to have the function return one of the parameters.</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="comment">// Registered as "obj@+ ChooseObj(obj@+, obj@+)"</span></div>
|
||
|
|
<div class="line">obj *ChooseObj(obj *a, obj *b)</div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"> <span class="comment">// Because of the auto handles AngelScript will</span></div>
|
||
|
|
<div class="line"> <span class="comment">// automatically manage the reference counters</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">return</span> some_condition ? a : b;</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>The auto handles works the same way for the <a class="el" href="doc_generic.html">generic calling convention</a>. </p>
|
||
|
|
</div></div><!-- contents -->
|
||
|
|
</div><!-- PageDoc -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<!-- 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>
|