luaBinder.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file luaBinder.h
//! \brief Provides functionality for binding C++ classes to Lua
//!
//! Adapted from Game Programming Gems 6: Section 4.2
 
#pragma once
 
#include "vreUtil/export.h"
 
#include <string>
 
// forward defs
struct lua_State;
struct luaL_Reg;
 
namespace makVre
{
class DtLuaValue;
class DtLuaObject;
 
//! \brief Class for binding C++ classes to Lua
//!
//! This class provides utilities for exposing C++ classes to Lua scripts,
//! allowing Lua code to create and interact with C++ objects. It manages
//! the registration of classes, object lifetime, and inheritance relationships.
class UTIL_DLL DtLuaBinder
{
public:
   //! \brief Constructor
   //!
   //! \param L The Lua state to bind to
   DtLuaBinder(lua_State& L);
 
   //! \brief Destructor
   ~DtLuaBinder();
 
   //! \brief Registers a C++ class with Lua
   //!
   //! This method exposes a C++ class to Lua, defining its name, inheritance,
   //! and available methods. It creates the necessary metatables and registration
   //! structures for the class.
   //!
   //! \param className The name to use for this class in Lua
   //! \param baseClass The name of the parent class (empty string if none)
   //! \param memberFuncList Array of member functions that instances can call
   //! \param publicFuncList Array of static functions accessible through the class table
   void registerClass(const std::string& className, const std::string& baseClass, const luaL_Reg* memberFuncList,
      const luaL_Reg* publicFuncList);
 
   //! \brief Creates and pushes a Lua representation of a C++ object onto the stack
   //!
   //! This method takes a C++ object pointer and pushes a Lua userdata
   //! representing that object onto the Lua stack. The userdata will have
   //! the appropriate metatable for the object's class.
   //!
   //! \note This should only be used in binding/glue functions
   //!
   //! \param ptr Pointer to the C++ object
   //! \param className The class name of the object
   void pushClassInstance(void* ptr, const std::string& className);
 
   //! \brief Validates and extracts a C++ object pointer from a Lua value
   //!
   //! Checks if the Lua value at the specified stack index is a userdata
   //! with a metatable matching the given class name (or a derived class).
   //! If it is, returns the pointer to the C++ object.
   //!
   //! \note This should only be used in binding/glue functions
   //!
   //! \param index The stack index of the Lua value to check
   //! \param className The expected class name of the object
   //! \return Pointer to the C++ object or NULL if validation fails
   void* checkClassInstance(int index, const std::string& className);
 
   //! \brief Validates and extracts a C++ object pointer from a Lua object
   //!
   //! \note This should only be used in binding/glue functions
   //!
   //! \param obj The Lua object to check
   //! \param className The expected class name of the object
   //! \return Pointer to the C++ object or NULL if validation fails
   void* checkClassInstance(DtLuaObject& obj, const std::string& className);
 
   //! \brief Stores a C++ object as a global Lua variable
   //!
   //! Creates a Lua userdata for the specified C++ object and
   //! assigns it to a global variable with the given name.
   //!
   //! \param ptr Pointer to the C++ object
   //! \param className The class name of the object
   //! \param variableName The name of the global variable to create
   void storeClassInstance(void* ptr, const std::string& className, const std::string& variableName);
 
   //! \brief Converts a relative stack index to an absolute index
   //!
   //! \param index The stack index to convert (positive or negative)
   //! \return The absolute (positive) stack index
   int absIndex(int index);
 
protected:
   //! \brief The Lua state this binder is associated with
   lua_State* myState;
};
 
} // namespace makVre