Eiyeron
/
luwra


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
							<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  
  
  <title>Wrapping - Luwra</title>
  

  <link rel="shortcut icon" href="../img/favicon.ico">

  
  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

  <link rel="stylesheet" href="../css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
  <link rel="stylesheet" href="../css/highlight.css">

  
  <script>
    // Current page data
    var mkdocs_page_name = "Wrapping";
    var mkdocs_page_input_path = "wrapping.md";
    var mkdocs_page_url = "/wrapping/";
  </script>
  
  <script src="../js/jquery-2.1.1.min.js"></script>
  <script src="../js/modernizr-2.8.3.min.js"></script>
  <script type="text/javascript" src="../js/highlight.pack.js"></script>
  <script src="../js/theme.js"></script> 

  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
      <div class="wy-side-nav-search">
        <a href=".." class="icon icon-home"> Luwra</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        <ul class="current">
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="..">Home</a>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="../stack-interaction/">Stack Interaction</a>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="../advanced/">Advanced Stack Interaction</a>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 current">
        <a class="current" href="./">Wrapping</a>
        
            <ul>
            
                <li class="toctree-l3"><a href="#wrapping">Wrapping</a></li>
                
                    <li><a class="toctree-l4" href="#functions">Functions</a></li>
                
                    <li><a class="toctree-l4" href="#class-members">Class members</a></li>
                
            
            </ul>
        
    </li>
<li>
          
            <li>
    <li class="toctree-l1 ">
        <a class="" href="../user-types/">User Types</a>
        
    </li>
<li>
          
        </ul>
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="..">Luwra</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="..">Docs</a> &raquo;</li>
    
      
    
    <li>Wrapping</li>
    <li class="wy-breadcrumbs-aside">
      
        
          <a href="https://github.com/vapourismo/luwra" class="icon icon-github"> Edit on GitHub</a>
        
      
    </li>
  </ul>
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1 id="wrapping">Wrapping</h1>
<p>Luwra provides a simple way to generate Lua <a href="http://www.lua.org/manual/5.3/manual.html#lua_CFunction">C functions</a> from functions and class
members like methods and accessors using the <code>LUWRA_WRAP</code> macro. These kind of C functions are
useful, because they work just like regular Lua functions within the Lua virtual machine.
Registering these functions is the most straightforward way of providing the functionality of your
application to Lua.</p>
<h2 id="functions">Functions</h2>
<p>When wrapping functions, one must consider that all parameter types must be read from the
stack and the return type must be pushed onto the stack.</p>
<h3 id="example">Example</h3>
<p>Lets assume you want to make the following function available in Lua.</p>
<pre><code class="c++">int my_function(const char* a, int b) {
    return /* magic */;
}
</code></pre>

<p>First, you must generate a Lua <a href="http://www.lua.org/manual/5.3/manual.html#lua_CFunction">C function</a>. One utilizes the <code>LUWRA_WRAP</code> macro for
this.</p>
<pre><code class="c++">lua_CFunction cfun = LUWRA_WRAP(my_function);
</code></pre>

<p><strong>Note:</strong> Do not provide the address of your function (e.g. <code>&amp;my_function</code>) to any wrapping macro.
The macro will take care of this itself. You must provide only the name of the function.</p>
<p>Once you have the C function, you can register it in the global namespace.</p>
<pre><code class="c++">luwra::setGlobal(lua, &quot;my_function&quot;, cfun);
</code></pre>

<p>Invoking the function in Lua is fairly straightforward.</p>
<pre><code class="lua">print(my_function(&quot;Hello World&quot;, 1337))
</code></pre>

<h3 id="performance">Performance</h3>
<p><a href="http://www.lua.org/manual/5.3/manual.html#lua_CFunction">C functions</a> are dynamically created at compile-time. All of the functions involved
in wrapping are marked as <code>inline</code>, which means modern compilers produce wrapper functions with zero
overhead, when optimization is turned on.</p>
<p>For the example above, the resulting code would look similiar to the following.</p>
<pre><code class="c++">static int cfun(lua_State* state) {
    lua_pushinteger(
        state,
        my_function(
            luaL_checkstring(state, 1),
            luaL_checkinteger(state, 1)
        )
    );
    return 1;
}
</code></pre>

<h2 id="class-members">Class members</h2>
<p>Although a little trickier, it is also possible to turn C++ field accessors and methods into Lua
<a href="http://www.lua.org/manual/5.3/manual.html#lua_CFunction">C functions</a>. The resulting Lua functions expect the first (or <code>self</code>) parameter to
be an instance of the type which the wrapped field or method belongs to.</p>
<p><strong>Note:</strong> Before you wrap fields and methods manually, you might want to take a look at the
<a href="../user-types/">User Types</a> section.</p>
<h3 id="example_1">Example</h3>
<p>This example will operate on the following structure.</p>
<pre><code class="c++">struct Point {
    double x, y;

    // ...

    void scale(double f) {
        x *= f;
        y *= f;
    }
};
</code></pre>

<p>Wrapping field accessors and methods works identical to wrapping functions.</p>
<pre><code class="c++">lua_CFunction cfun_x     = LUWRA_WRAP(Point::x),
              cfun_y     = LUWRA_WRAP(Point::y),
              cfun_scale = LUWRA_WRAP(Point::scale);

// Register in global namespace
luwra::setGlobal(lua, &quot;x&quot;, cfun_x);
luwra::setGlobal(lua, &quot;y&quot;, cfun_y);
luwra::setGlobal(lua, &quot;scale&quot;, cfun_scale);
</code></pre>

<p>Usage in Lua is analogous to function usage.</p>
<pre><code class="lua">-- Instantiate 'Point' here, have a look at the User Types section to find out how to do this
local my_point = ...

-- Access 'x' and 'y' field
print(x(my_point), y(my_point))

-- Set 'x' and 'y' field
x(my_point, 13.37)
y(my_point, 73.31)

-- Invoke 'scale' method
scale(my_point, 2)
</code></pre>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="../user-types/" class="btn btn-neutral float-right" title="User Types">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
        <a href="../advanced/" class="btn btn-neutral" title="Advanced Stack Interaction"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
	  
        </div>
      </div>

    </section>

  </div>

<div class="rst-versions" role="note" style="cursor: pointer">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
          <a href="https://github.com/vapourismo/luwra" class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>
      
      
        <span><a href="../advanced/" style="color: #fcfcfc;">&laquo; Previous</a></span>
      
      
        <span style="margin-left: 15px"><a href="../user-types/" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>

</body>
</html>