[Yake-svn] SF.net SVN: yake: [1640] trunk/yake/documentation/manual/yake-manual.txt

[<psy...@us...>]

Revision: 1640
          http://svn.sourceforge.net/yake/?rev=1640&view=rev
Author:   psyclonist
Date:     2007-03-12 17:11:45 -0700 (Mon, 12 Mar 2007)

Log Message:
-----------


Modified Paths:
--------------
    trunk/yake/documentation/manual/yake-manual.txt

Modified: trunk/yake/documentation/manual/yake-manual.txt
===================================================================
--- trunk/yake/documentation/manual/yake-manual.txt	2007-03-13 00:11:34 UTC (rev 1639)
+++ trunk/yake/documentation/manual/yake-manual.txt	2007-03-13 00:11:45 UTC (rev 1640)
@@ -39,10 +39,9 @@
 
 This manual is licensed under the Attribution-NonCommercial-ShareAlike 2.0 Germany License.
 
-You can read the more complete human-readable summary of the license at this URL in several languages:
+You can read the more complete human-readable summary of the license at this URL:
 
-http://creativecommons.org/licenses/by-nc-sa/2.0/de/ (in German)
-http://creativecommons.org/licenses/by-nc-sa/2.0/de/deed.en (in English)
+http://creativecommons.org/licenses/by-nc-sa/2.0/de/
 
 The full license text is available here:
 
@@ -359,8 +358,8 @@
 
 Basic management of scripting states is handled by the 'scripting' component.
 
-It does not handle binding. This is implemented in specialized plugins
-(e.g. "entLua", "modelLua" ..).
+It does not handle binding. This is implemented in one or more specialized binding plugins
+(e.g. "binding.lua" ..).
 
 Interfaces
 ~~~~~~~~~~
@@ -381,6 +380,71 @@
 At the time of writing one official scripting plugin as well as a set of binding
 modules are available for Lua.
 
+Lua Scripting Bindings
+----------------------
+
+Official script language bindings are implemented for Lua 5. The library which
+implements the bindings is *bindings.lua*.
+
+Examples
+~~~~~~~~
+
+C++ pseudocode::
+
+		#include <yake/scripting/yakeScriptingSystem.h>
+		#include <yake/bindings.lua/bindings.lua.h>
+		
+		// ... setup VM
+		yake::scripting::IVM* vm = ..
+		
+		// bind everything there is
+		yake::bind_all(vm)
+
+Alternatively you can set up the bindings directly for a *lua_State*::
+
+		// setup VM
+		lua_State* L = lua_open();
+		luabind::open(L);
+
+		// bind everything
+		yake::bind_all(L);
+		
+You can bind a subset of available functionality, either by calling an explicit bind_X function
+or by instantiating a binder object.
+
+Either using bind_X()::
+
+		yake::bind_base(vm);  // binds basic functionality (math etc)
+		yake::bind_model(vm); // binds functionality of yake::model (Model, ModelComponent etc)
+		..
+		
+Or using binder objects::
+
+		yake::SharedPtr<scripting::IBinder> binder = yake::create<scripting::IBinder>("base");
+		binder->bind(vm);
+		
+The bind_X() approach is slightly more efficient as it avoids allocation of an IBinder instance.
+If you keep the binder object around the difference is negligible.
+
+.. note::
+	The binder approach can prove to be useful when data-driven concepts come into play, i.e. if
+	you need to specify which components to bind to at runtime (for example, by reading the binder
+	ids from a configuration file). 
+
+Choosing which binders to build
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can select which script bindings are actually built by editing ``scripts/premake/config.lua``. Use
+the ``ENABLE_LUA_*`` settings. (Remember to recreate the build scripts by running the appropriate script.
+See `Building Yake (libraries and demos)`_ for more information.)
+
+If you disable a binding on the code basis in ``config.lua`` then neither bind_X() function nor the binder
+object for this feature will be available.
+
+You can compile all binders and select which binders to use at a later time. Disabling binders
+on the build level can make sense when you definitely know that you do not need or want to use a certain
+feature at all. This way you can avoid dependencies and reduce compilation time.
+
 Data
 ----
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.