/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/angelscript.h
C++ Header | 3862 lines | 1244 code | 265 blank | 2353 comment | 5 complexity | 41f23e90b623c1f5a6974d5bb9d8929e MD5 | raw file
Possible License(s): GPL-3.0, CC-BY-SA-3.0, LGPL-2.0, 0BSD, Unlicense, GPL-2.0, AGPL-1.0, BSD-3-Clause, LGPL-2.1, LGPL-3.0
Large files files are truncated, but you can click here to view the full file
- /*
- AngelCode Scripting Library
- Copyright (c) 2003-2009 Andreas Jonsson
- This software is provided 'as-is', without any express or implied
- warranty. In no event will the authors be held liable for any
- damages arising from the use of this software.
- Permission is granted to anyone to use this software for any
- purpose, including commercial applications, and to alter it and
- redistribute it freely, subject to the following restrictions:
- 1. The origin of this software must not be misrepresented; you
- must not claim that you wrote the original software. If you use
- this software in a product, an acknowledgment in the product
- documentation would be appreciated but is not required.
- 2. Altered source versions must be plainly marked as such, and
- must not be misrepresented as being the original software.
- 3. This notice may not be removed or altered from any source
- distribution.
- The original version of this library can be located at:
- http://www.angelcode.com/angelscript/
- Andreas Jonsson
- andreas@angelcode.com
- */
- //
- // angelscript.h
- //
- // The script engine interface
- //
- //! \file angelscript.h
- //! \brief The API definition for AngelScript.
- //!
- //! This header file describes the complete application programming interface for AngelScript.
- #ifndef ANGELSCRIPT_H
- #define ANGELSCRIPT_H
- #include <stddef.h>
- #ifdef AS_USE_NAMESPACE
- #define BEGIN_AS_NAMESPACE namespace AngelScript {
- #define END_AS_NAMESPACE }
- #else
- #define BEGIN_AS_NAMESPACE
- #define END_AS_NAMESPACE
- #endif
- BEGIN_AS_NAMESPACE
- // AngelScript version
- //! \details Version 2.18.0
- #define ANGELSCRIPT_VERSION 21800
- #define ANGELSCRIPT_VERSION_STRING "2.18.0"
- // Data types
- class asIScriptEngine;
- class asIScriptModule;
- class asIScriptContext;
- class asIScriptGeneric;
- class asIScriptObject;
- class asIScriptArray;
- class asIObjectType;
- class asIScriptFunction;
- class asIBinaryStream;
- class asIJITCompiler;
- // Enumerations and constants
- // Engine properties
- //! Engine properties
- enum asEEngineProp
- {
- //! Allow unsafe references. Default: false.
- asEP_ALLOW_UNSAFE_REFERENCES = 1,
- //! Optimize byte code. Default: true.
- asEP_OPTIMIZE_BYTECODE = 2,
- //! Copy script section memory. Default: true.
- asEP_COPY_SCRIPT_SECTIONS = 3,
- //! Maximum stack size for script contexts. Default: 0 (no limit).
- asEP_MAX_STACK_SIZE = 4,
- //! Interpret single quoted strings as character literals. Default: false.
- asEP_USE_CHARACTER_LITERALS = 5,
- //! Allow linebreaks in string constants. Default: false.
- asEP_ALLOW_MULTILINE_STRINGS = 6,
- //! Allow script to declare implicit handle types. Default: false.
- asEP_ALLOW_IMPLICIT_HANDLE_TYPES = 7,
- //! Remove SUSPEND instructions between each statement. Default: false.
- asEP_BUILD_WITHOUT_LINE_CUES = 8,
- //! Initialize global variables after a build. Default: true.
- asEP_INIT_GLOBAL_VARS_AFTER_BUILD = 9,
- //! When set the enum values must be prefixed with the enum type. Default: false.
- asEP_REQUIRE_ENUM_SCOPE = 10,
- //! Select scanning method: 0 - ASCII, 1 - UTF8. Default: 1 (UTF8).
- asEP_SCRIPT_SCANNER = 11,
- //! When set extra bytecode instructions needed for JIT compiled funcions will be included. Default: false.
- asEP_INCLUDE_JIT_INSTRUCTIONS = 12,
- //! Select string encoding for literals: 0 - UTF8/ASCII, 1 - UTF16. Default: 0 (UTF8)
- asEP_STRING_ENCODING = 13
- };
- // Calling conventions
- //! Calling conventions
- enum asECallConvTypes
- {
- //! A cdecl function.
- asCALL_CDECL = 0,
- //! A stdcall function.
- asCALL_STDCALL = 1,
- //! A thiscall class method.
- asCALL_THISCALL = 2,
- //! A cdecl function that takes the object pointer as the last parameter.
- asCALL_CDECL_OBJLAST = 3,
- //! A cdecl function that takes the object pointer as the first parameter.
- asCALL_CDECL_OBJFIRST = 4,
- //! A function using the generic calling convention.
- asCALL_GENERIC = 5
- };
- // Object type flags
- //! Object type flags
- enum asEObjTypeFlags
- {
- //! A reference type.
- asOBJ_REF = 0x01,
- //! A value type.
- asOBJ_VALUE = 0x02,
- //! A garbage collected type. Only valid for reference types.
- asOBJ_GC = 0x04,
- //! A plain-old-data type. Only valid for value types.
- asOBJ_POD = 0x08,
- //! This reference type doesn't allow handles to be held. Only valid for reference types.
- asOBJ_NOHANDLE = 0x10,
- //! The life time of objects of this type are controlled by the scope of the variable. Only valid for reference types.
- asOBJ_SCOPED = 0x20,
- //! A template type.
- asOBJ_TEMPLATE = 0x40,
- //! The C++ type is a class type. Only valid for value types.
- asOBJ_APP_CLASS = 0x100,
- //! The C++ class has an explicit constructor. Only valid for value types.
- asOBJ_APP_CLASS_CONSTRUCTOR = 0x200,
- //! The C++ class has an explicit destructor. Only valid for value types.
- asOBJ_APP_CLASS_DESTRUCTOR = 0x400,
- //! The C++ class has an explicit assignment operator. Only valid for value types.
- asOBJ_APP_CLASS_ASSIGNMENT = 0x800,
- //! The C++ type is a class with a constructor, but no destructor or assignment operator.
- asOBJ_APP_CLASS_C = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_CONSTRUCTOR),
- //! The C++ type is a class with a constructor and destructor, but no assignment operator.
- asOBJ_APP_CLASS_CD = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_CONSTRUCTOR + asOBJ_APP_CLASS_DESTRUCTOR),
- //! The C++ type is a class with a constructor and assignment operator, but no destructor.
- asOBJ_APP_CLASS_CA = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_CONSTRUCTOR + asOBJ_APP_CLASS_ASSIGNMENT),
- //! The C++ type is a class with a constructor, destructor, and assignment operator.
- asOBJ_APP_CLASS_CDA = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_CONSTRUCTOR + asOBJ_APP_CLASS_DESTRUCTOR + asOBJ_APP_CLASS_ASSIGNMENT),
- //! The C++ type is a class with a destructor, but no constructor or assignment operator.
- asOBJ_APP_CLASS_D = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_DESTRUCTOR),
- //! The C++ type is a class with an assignment operator, but no constructor or destructor.
- asOBJ_APP_CLASS_A = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_ASSIGNMENT),
- //! The C++ type is a class with a destructor and assignment operator, but no constructor.
- asOBJ_APP_CLASS_DA = (asOBJ_APP_CLASS + asOBJ_APP_CLASS_DESTRUCTOR + asOBJ_APP_CLASS_ASSIGNMENT),
- //! The C++ type is a primitive type. Only valid for value types.
- asOBJ_APP_PRIMITIVE = 0x1000,
- //! The C++ type is a float or double. Only valid for value types.
- asOBJ_APP_FLOAT = 0x2000,
- asOBJ_MASK_VALID_FLAGS = 0x3F7F,
- //! The object is a script class or an interface.
- asOBJ_SCRIPT_OBJECT = 0x10000
- };
- // Behaviours
- //! Behaviours
- enum asEBehaviours
- {
- // Value object memory management
- //! \brief Constructor
- asBEHAVE_CONSTRUCT,
- //! \brief Destructor
- asBEHAVE_DESTRUCT,
- // Reference object memory management
- //! \brief Factory
- asBEHAVE_FACTORY,
- //! \brief AddRef
- asBEHAVE_ADDREF,
- //! \brief Release
- asBEHAVE_RELEASE,
- // Object operators
- //! \brief Explicit value cast operator
- asBEHAVE_VALUE_CAST,
- //! \brief Implicit value cast operator
- asBEHAVE_IMPLICIT_VALUE_CAST,
- //! \brief Explicit reference cast operator
- asBEHAVE_REF_CAST,
- //! \brief Implicit reference cast operator
- asBEHAVE_IMPLICIT_REF_CAST,
- //! \brief operator []
- asBEHAVE_INDEX,
- //! \brief Callback for validating template instances
- asBEHAVE_TEMPLATE_CALLBACK,
- // Garbage collection behaviours
- asBEHAVE_FIRST_GC,
- //! \brief (GC) Get reference count
- asBEHAVE_GETREFCOUNT = asBEHAVE_FIRST_GC,
- //! \brief (GC) Set GC flag
- asBEHAVE_SETGCFLAG,
- //! \brief (GC) Get GC flag
- asBEHAVE_GETGCFLAG,
- //! \brief (GC) Enumerate held references
- asBEHAVE_ENUMREFS,
- //! \brief (GC) Release all references
- asBEHAVE_RELEASEREFS,
- asBEHAVE_LAST_GC = asBEHAVE_RELEASEREFS,
- asBEHAVE_MAX
- };
- // Return codes
- //! Return codes
- enum asERetCodes
- {
- //! Success
- asSUCCESS = 0,
- //! Failure
- asERROR = -1,
- //! The context is active
- asCONTEXT_ACTIVE = -2,
- //! The context is not finished
- asCONTEXT_NOT_FINISHED = -3,
- //! The context is not prepared
- asCONTEXT_NOT_PREPARED = -4,
- //! Invalid argument
- asINVALID_ARG = -5,
- //! The function was not found
- asNO_FUNCTION = -6,
- //! Not supported
- asNOT_SUPPORTED = -7,
- //! Invalid name
- asINVALID_NAME = -8,
- //! The name is already taken
- asNAME_TAKEN = -9,
- //! Invalid declaration
- asINVALID_DECLARATION = -10,
- //! Invalid object
- asINVALID_OBJECT = -11,
- //! Invalid type
- asINVALID_TYPE = -12,
- //! Already registered
- asALREADY_REGISTERED = -13,
- //! Multiple matching functions
- asMULTIPLE_FUNCTIONS = -14,
- //! The module was not found
- asNO_MODULE = -15,
- //! The global variable was not found
- asNO_GLOBAL_VAR = -16,
- //! Invalid configuration
- asINVALID_CONFIGURATION = -17,
- //! Invalid interface
- asINVALID_INTERFACE = -18,
- //! All imported functions couldn't be bound
- asCANT_BIND_ALL_FUNCTIONS = -19,
- //! The array sub type has not been registered yet
- asLOWER_ARRAY_DIMENSION_NOT_REGISTERED = -20,
- //! Wrong configuration group
- asWRONG_CONFIG_GROUP = -21,
- //! The configuration group is in use
- asCONFIG_GROUP_IS_IN_USE = -22,
- //! Illegal behaviour for the type
- asILLEGAL_BEHAVIOUR_FOR_TYPE = -23,
- //! The specified calling convention doesn't match the function/method pointer
- asWRONG_CALLING_CONV = -24,
- //! A build is currently in progress
- asBUILD_IN_PROGRESS = -25,
- //! The initialization of global variables failed
- asINIT_GLOBAL_VARS_FAILED = -26
- };
- // Context states
- //! \brief Context states.
- enum asEContextState
- {
- //! The context has successfully completed the execution.
- asEXECUTION_FINISHED = 0,
- //! The execution is suspended and can be resumed.
- asEXECUTION_SUSPENDED = 1,
- //! The execution was aborted by the application.
- asEXECUTION_ABORTED = 2,
- //! The execution was terminated by an unhandled script exception.
- asEXECUTION_EXCEPTION = 3,
- //! The context has been prepared for a new execution.
- asEXECUTION_PREPARED = 4,
- //! The context is not initialized.
- asEXECUTION_UNINITIALIZED = 5,
- //! The context is currently executing a function call.
- asEXECUTION_ACTIVE = 6,
- //! The context has encountered an error and must be reinitialized.
- asEXECUTION_ERROR = 7
- };
- #ifdef AS_DEPRECATED
- // Deprecated since 2.18.0, 2009-12-08
- // ExecuteString flags
- //! \brief ExecuteString flags.
- //! \deprecated since 2.18.0
- enum asEExecStrFlags
- {
- //! Only prepare the context
- asEXECSTRING_ONLY_PREPARE = 1,
- //! Use the pre-allocated context
- asEXECSTRING_USE_MY_CONTEXT = 2
- };
- #endif
- // Message types
- //! \brief Compiler message types.
- enum asEMsgType
- {
- //! The message is an error.
- asMSGTYPE_ERROR = 0,
- //! The message is a warning.
- asMSGTYPE_WARNING = 1,
- //! The message is informational only.
- asMSGTYPE_INFORMATION = 2
- };
- // Garbage collector flags
- //! \brief Garbage collector flags.
- enum asEGCFlags
- {
- //! Execute a full cycle.
- asGC_FULL_CYCLE = 1,
- //! Execute only one step
- asGC_ONE_STEP = 2,
- //! Destroy known garbage
- asGC_DESTROY_GARBAGE = 4,
- //! Detect garbage with circular references
- asGC_DETECT_GARBAGE = 8
- };
- // Token classes
- //! \brief Token classes.
- enum asETokenClass
- {
- //! Unknown token.
- asTC_UNKNOWN = 0,
- //! Keyword token.
- asTC_KEYWORD = 1,
- //! Literal value token.
- asTC_VALUE = 2,
- //! Identifier token.
- asTC_IDENTIFIER = 3,
- //! Comment token.
- asTC_COMMENT = 4,
- //! White space token.
- asTC_WHITESPACE = 5
- };
- // Prepare flags
- const int asPREPARE_PREVIOUS = -1;
- // Config groups
- const char * const asALL_MODULES = (const char * const)-1;
- // Type id flags
- //! \brief Type id flags
- enum asETypeIdFlags
- {
- //! The type id for void
- asTYPEID_VOID = 0,
- //! The type id for bool
- asTYPEID_BOOL = 1,
- //! The type id for int8
- asTYPEID_INT8 = 2,
- //! The type id for int16
- asTYPEID_INT16 = 3,
- //! The type id for int
- asTYPEID_INT32 = 4,
- //! The type id for int64
- asTYPEID_INT64 = 5,
- //! The type id for uint8
- asTYPEID_UINT8 = 6,
- //! The type id for uint16
- asTYPEID_UINT16 = 7,
- //! The type id for uint
- asTYPEID_UINT32 = 8,
- //! The type id for uint64
- asTYPEID_UINT64 = 9,
- //! The type id for float
- asTYPEID_FLOAT = 10,
- //! The type id for double
- asTYPEID_DOUBLE = 11,
- //! The bit that shows if the type is a handle
- asTYPEID_OBJHANDLE = 0x40000000,
- //! The bit that shows if the type is a handle to a const
- asTYPEID_HANDLETOCONST = 0x20000000,
- //! If any of these bits are set, then the type is an object
- asTYPEID_MASK_OBJECT = 0x1C000000,
- //! The bit that shows if the type is an application registered type
- asTYPEID_APPOBJECT = 0x04000000,
- //! The bit that shows if the type is a script class
- asTYPEID_SCRIPTOBJECT = 0x08000000,
- //! The bit that shows if the type is a script array
- asTYPEID_SCRIPTARRAY = 0x10000000,
- //! The mask for the type id sequence number
- asTYPEID_MASK_SEQNBR = 0x03FFFFFF
- };
- // Type modifiers
- //! \brief Type modifiers
- enum asETypeModifiers
- {
- //! No modification
- asTM_NONE = 0,
- //! Input reference
- asTM_INREF = 1,
- //! Output reference
- asTM_OUTREF = 2,
- //! In/out reference
- asTM_INOUTREF = 3
- };
- // GetModule flags
- //! \brief Flags for GetModule.
- enum asEGMFlags
- {
- //! \brief Don't return any module if it is not found.
- asGM_ONLY_IF_EXISTS = 0,
- //! \brief Create the module if it doesn't exist.
- asGM_CREATE_IF_NOT_EXISTS = 1,
- //! \brief Always create a new module, discarding the existing one.
- asGM_ALWAYS_CREATE = 2
- };
- // Compile flags
- //! \brief Flags for compilation
- enum asECompileFlags
- {
- //! \brief The compiled function should be added to the scope of the module.
- asCOMP_ADD_TO_MODULE = 1
- };
- //! \typedef asBYTE
- //! \brief 8 bit unsigned integer
- //! \typedef asWORD
- //! \brief 16 bit unsigned integer
- //! \typedef asDWORD
- //! \brief 32 bit unsigned integer
- //! \typedef asQWORD
- //! \brief 64 bit unsigned integer
- //! \typedef asUINT
- //! \brief 32 bit unsigned integer
- //! \typedef asINT64
- //! \brief 64 bit integer
- //! \typedef asPWORD
- //! \brief Unsigned integer with the size of a pointer.
- //
- // asBYTE = 8 bits
- // asWORD = 16 bits
- // asDWORD = 32 bits
- // asQWORD = 64 bits
- // asPWORD = size of pointer
- //
- typedef unsigned char asBYTE;
- typedef unsigned short asWORD;
- typedef unsigned int asUINT;
- typedef size_t asPWORD;
- #ifdef __LP64__
- typedef unsigned int asDWORD;
- typedef unsigned long asQWORD;
- typedef long asINT64;
- #else
- typedef unsigned long asDWORD;
- #if defined(__GNUC__) || defined(__MWERKS__)
- typedef unsigned long long asQWORD;
- typedef long long asINT64;
- #else
- typedef unsigned __int64 asQWORD;
- typedef __int64 asINT64;
- #endif
- #endif
- typedef void (*asFUNCTION_t)();
- typedef void (*asGENFUNC_t)(asIScriptGeneric *);
- //! The function signature for the custom memory allocation function
- typedef void *(*asALLOCFUNC_t)(size_t);
- //! The function signature for the custom memory deallocation function
- typedef void (*asFREEFUNC_t)(void *);
- //! \ingroup funcs
- //! \brief Returns an asSFuncPtr representing the function specified by the name
- #define asFUNCTION(f) asFunctionPtr(f)
- //! \ingroup funcs
- //! \brief Returns an asSFuncPtr representing the function specified by the name, parameter list, and return type
- #if defined(_MSC_VER) && _MSC_VER <= 1200
- // MSVC 6 has a bug that prevents it from properly compiling using the correct asFUNCTIONPR with operator >
- // so we need to use ordinary C style cast instead of static_cast. The drawback is that the compiler can't
- // check that the cast is really valid.
- #define asFUNCTIONPR(f,p,r) asFunctionPtr((void (*)())((r (*)p)(f)))
- #else
- #define asFUNCTIONPR(f,p,r) asFunctionPtr((void (*)())(static_cast<r (*)p>(f)))
- #endif
- #ifndef AS_NO_CLASS_METHODS
- class asCUnknownClass;
- typedef void (asCUnknownClass::*asMETHOD_t)();
- //! \brief Represents a function or method pointer.
- struct asSFuncPtr
- {
- union
- {
- // The largest known method point is 20 bytes (MSVC 64bit),
- // but with 8byte alignment this becomes 24 bytes. So we need
- // to be able to store at least that much.
- char dummy[25];
- struct {asMETHOD_t mthd; char dummy[25-sizeof(asMETHOD_t)];} m;
- struct {asFUNCTION_t func; char dummy[25-sizeof(asFUNCTION_t)];} f;
- } ptr;
- asBYTE flag; // 1 = generic, 2 = global func, 3 = method
- };
- //! \ingroup funcs
- //! \brief Returns an asSFuncPtr representing the class method specified by class and method name.
- #define asMETHOD(c,m) asSMethodPtr<sizeof(void (c::*)())>::Convert((void (c::*)())(&c::m))
- //! \ingroup funcs
- //! \brief Returns an asSFuncPtr representing the class method specified by class, method name, parameter list, return type.
- #define asMETHODPR(c,m,p,r) asSMethodPtr<sizeof(void (c::*)())>::Convert(static_cast<r (c::*)p>(&c::m))
- #else // Class methods are disabled
- struct asSFuncPtr
- {
- union
- {
- char dummy[25]; // largest known class method pointer
- struct {asFUNCTION_t func; char dummy[25-sizeof(asFUNCTION_t)];} f;
- } ptr;
- asBYTE flag; // 1 = generic, 2 = global func
- };
- #endif
- //! \brief Represents a compiler message
- struct asSMessageInfo
- {
- //! The script section where the message is raised
- const char *section;
- //! The row number
- int row;
- //! The column
- int col;
- //! The type of message
- asEMsgType type;
- //! The message text
- const char *message;
- };
- // API functions
- // ANGELSCRIPT_EXPORT is defined when compiling the dll or lib
- // ANGELSCRIPT_DLL_LIBRARY_IMPORT is defined when dynamically linking to the
- // dll through the link lib automatically generated by MSVC++
- // ANGELSCRIPT_DLL_MANUAL_IMPORT is defined when manually loading the dll
- // Don't define anything when linking statically to the lib
- //! \def AS_API
- //! \brief A define that specifies how the function should be imported
- #ifdef WIN32
- #ifdef ANGELSCRIPT_EXPORT
- #define AS_API __declspec(dllexport)
- #elif defined ANGELSCRIPT_DLL_LIBRARY_IMPORT
- #define AS_API __declspec(dllimport)
- #else // statically linked library
- #define AS_API
- #endif
- #else
- #define AS_API
- #endif
- #ifndef ANGELSCRIPT_DLL_MANUAL_IMPORT
- extern "C"
- {
- // Engine
- //! \brief Creates the script engine.
- //!
- //! \param[in] version The library version. Should always be \ref ANGELSCRIPT_VERSION.
- //! \return A pointer to the script engine interface.
- //!
- //! Call this function to create a new script engine. When you're done with the
- //! script engine, i.e. after you've executed all your scripts, you should call
- //! \ref asIScriptEngine::Release "Release" on the pointer to free the engine object.
- AS_API asIScriptEngine * asCreateScriptEngine(asDWORD version);
- //! \brief Returns the version of the compiled library.
- //!
- //! \return A null terminated string with the library version.
- //!
- //! The returned string can be used for presenting the library version in a log file, or in the GUI.
- AS_API const char * asGetLibraryVersion();
- //! \brief Returns the options used to compile the library.
- //!
- //! \return A null terminated string with indicators that identify the options
- //! used to compile the script library.
- //!
- //! This can be used to identify at run-time different ways to configure the engine.
- //! For example, if the returned string contain the identifier AS_MAX_PORTABILITY then
- //! functions and methods must be registered with the \ref asCALL_GENERIC calling convention.
- AS_API const char * asGetLibraryOptions();
- // Context
- //! \brief Returns the currently active context.
- //!
- //! \return A pointer to the currently executing context, or null if no context is executing.
- //!
- //! This function is most useful for registered functions, as it will allow them to obtain
- //! a pointer to the context that is calling the function, and through that get the engine,
- //! or custom user data.
- //!
- //! If the script library is compiled with multithread support, this function will return
- //! the context that is currently active in the thread that is being executed. It will thus
- //! work even if there are multiple threads executing scripts at the same time.
- AS_API asIScriptContext * asGetActiveContext();
- // Thread support
- //! \brief Cleans up memory allocated for the current thread.
- //!
- //! \return A negative value on error.
- //! \retval asCONTEXT_ACTIVE A context is still active.
- //!
- //! Call this method before terminating a thread that has
- //! accessed the engine to clean up memory allocated for that thread.
- //!
- //! It's not necessary to call this if only a single thread accesses the engine.
- AS_API int asThreadCleanup();
- // Memory management
- //! \brief Set the memory management functions that AngelScript should use.
- //!
- //! \param[in] allocFunc The function that will be used to allocate memory.
- //! \param[in] freeFunc The function that will be used to free the memory.
- //! \return A negative value on error.
- //!
- //! Call this method to register the global memory allocation and deallocation
- //! functions that AngelScript should use for memory management. This function
- //! Should be called before \ref asCreateScriptEngine.
- //!
- //! If not called, AngelScript will use the malloc and free functions from the
- //! standard C library.
- AS_API int asSetGlobalMemoryFunctions(asALLOCFUNC_t allocFunc, asFREEFUNC_t freeFunc);
- //! \brief Remove previously registered memory management functions.
- //!
- //! \return A negative value on error.
- //!
- //! Call this method to restore the default memory management functions.
- AS_API int asResetGlobalMemoryFunctions();
- }
- #endif // ANGELSCRIPT_DLL_MANUAL_IMPORT
- // Interface declarations
- //! \brief The engine interface
- class asIScriptEngine
- {
- public:
- // Memory management
- //! \name Memory management
- //! \{
- //! \brief Increase reference counter.
- //!
- //! \return The number of references to this object.
- //!
- //! Call this method when storing an additional reference to the object.
- //! Remember that the first reference that is received from \ref asCreateScriptEngine
- //! is already accounted for.
- virtual int AddRef() = 0;
- //! \brief Decrease reference counter.
- //!
- //! \return The number of references to this object.
- //!
- //! Call this method when you will no longer use the references that you own.
- virtual int Release() = 0;
- //! \}
- // Engine properties
- //! \name Engine properties
- //! \{
- //! \brief Dynamically change some engine properties.
- //!
- //! \param[in] property One of the \ref asEEngineProp values.
- //! \param[in] value The new value of the property.
- //! \return Negative value on error.
- //! \retval asINVALID_ARG Invalid property.
- //!
- //! With this method you can change the way the script engine works in some regards.
- virtual int SetEngineProperty(asEEngineProp property, asPWORD value) = 0;
- //! \brief Retrieve current engine property settings.
- //!
- //! \param[in] property One of the \ref asEEngineProp values.
- //! \return The value of the property, or 0 if it is an invalid property.
- //!
- //! Calling this method lets you determine the current value of the engine properties.
- virtual asPWORD GetEngineProperty(asEEngineProp property) = 0;
- //! \}
- // Compiler messages
- //! \name Compiler messages
- //! \{
- //! \brief Sets a message callback that will receive compiler messages.
- //!
- //! \param[in] callback A function or class method pointer.
- //! \param[in] obj The object for methods, or an optional parameter for functions.
- //! \param[in] callConv The calling convention.
- //! \return A negative value for an error.
- //! \retval asINVALID_ARG One of the arguments is incorrect, e.g. obj is null for a class method.
- //! \retval asNOT_SUPPORTED The arguments are not supported, e.g. asCALL_GENERIC.
- //!
- //! This method sets the callback routine that will receive compiler messages.
- //! The callback routine can be either a class method, e.g:
- //! \code
- //! void MyClass::MessageCallback(const asSMessageInfo *msg);
- //! r = engine->SetMessageCallback(asMETHOD(MyClass,MessageCallback), &obj, asCALL_THISCALL);
- //! \endcode
- //! or a global function, e.g:
- //! \code
- //! void MessageCallback(const asSMessageInfo *msg, void *param);
- //! r = engine->SetMessageCallback(asFUNCTION(MessageCallback), param, asCALL_CDECL);
- //! \endcode
- //! It is recommended to register the message callback routine right after creating the engine,
- //! as some of the registration functions can provide useful information to better explain errors.
- virtual int SetMessageCallback(const asSFuncPtr &callback, void *obj, asDWORD callConv) = 0;
- //! \brief Clears the registered message callback routine.
- //!
- //! \return A negative value on error.
- //!
- //! Call this method to remove the message callback.
- virtual int ClearMessageCallback() = 0;
- //! \brief Writes a message to the message callback.
- //!
- //! \param[in] section The name of the script section.
- //! \param[in] row The row number.
- //! \param[in] col The column number.
- //! \param[in] type The message type.
- //! \param[in] message The message text.
- //! \return A negative value on error.
- //! \retval asINVALID_ARG The section or message is null.
- //!
- //! This method can be used by the application to write messages
- //! to the same message callback that the script compiler uses. This
- //! is useful for example if a preprocessor is used.
- virtual int WriteMessage(const char *section, int row, int col, asEMsgType type, const char *message) = 0;
- //! \}
- // JIT Compiler
- //! \name JIT compiler
- //! \{
- //! \brief Sets the JIT compiler
- virtual int SetJITCompiler(asIJITCompiler *compiler) = 0;
- //! \brief Returns the JIT compiler
- virtual asIJITCompiler *GetJITCompiler() = 0;
- //! \}
- // Global functions
- //! \name Global functions
- //! \{
- //! \brief Registers a global function.
- //!
- //! \param[in] declaration The declaration of the global function in script syntax.
- //! \param[in] funcPointer The function pointer.
- //! \param[in] callConv The calling convention for the function.
- //! \return A negative value on error, or the function id if successful.
- //! \retval asNOT_SUPPORTED The calling convention is not supported.
- //! \retval asWRONG_CALLING_CONV The function's calling convention doesn't match \a callConv.
- //! \retval asINVALID_DECLARATION The function declaration is invalid.
- //! \retval asNAME_TAKEN The function name is already used elsewhere.
- //!
- //! This method registers system functions that the scripts may use to communicate with the host application.
- //!
- //! \see \ref doc_register_func
- virtual int RegisterGlobalFunction(const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv) = 0;
- //! \brief Returns the number of registered functions.
- //! \return The number of registered functions.
- virtual int GetGlobalFunctionCount() = 0;
- //! \brief Returns the function id of the registered function.
- //! \param[in] index The index of the registered global function.
- //! \return The id of the function, or a negative value on error.
- //! \retval asINVALID_ARG \a index is too large.
- virtual int GetGlobalFunctionIdByIndex(asUINT index) = 0;
- //! \}
- // Global properties
- //! \name Global properties
- //! \{
- //! \brief Registers a global property.
- //!
- //! \param[in] declaration The declaration of the global property in script syntax.
- //! \param[in] pointer The address of the property that will be used to access the property value.
- //! \return A negative value on error.
- //! \retval asINVALID_DECLARATION The declaration has invalid syntax.
- //! \retval asINVALID_TYPE The declaration is a reference.
- //! \retval asNAME_TAKEN The name is already taken.
- //!
- //! Use this method to register a global property that the scripts will be
- //! able to access as global variables. The property may optionally be registered
- //! as const, if the scripts shouldn't be allowed to modify it.
- //!
- //! When registering the property, the application must pass the address to
- //! the actual value. The application must also make sure that this address
- //! remains valid throughout the life time of this registration, i.e. until
- //! the engine is released or the dynamic configuration group is removed.
- virtual int RegisterGlobalProperty(const char *declaration, void *pointer) = 0;
- //! \brief Returns the number of registered global properties.
- //! \return The number of registered global properties.
- virtual int GetGlobalPropertyCount() = 0;
- //! \brief Returns the detail on the registered global property.
- //! \param[in] index The index of the global variable.
- //! \param[out] name Receives the name of the property.
- //! \param[out] typeId Receives the typeId of the property.
- //! \param[out] isConst Receives the constness indicator of the property.
- //! \param[out] configGroup Receives the config group in which the property was registered.
- //! \param[out] pointer Receives the pointer of the property.
- //! \return A negative value on error.
- //! \retval asINVALID_ARG \a index is too large.
- virtual int GetGlobalPropertyByIndex(asUINT index, const char **name, int *typeId = 0, bool *isConst = 0, const char **configGroup = 0, void **pointer = 0) = 0;
- //! \}
- // Object types
- //! \name Object types
- //! \{
- //! \brief Registers a new object type.
- //!
- //! \param[in] obj The name of the type.
- //! \param[in] byteSize The size of the type in bytes. Only necessary for value types.
- //! \param[in] flags One or more of the asEObjTypeFlags.
- //! \return A negative value on error.
- //! \retval asINVALID_ARG The flags are invalid.
- //! \retval asINVALID_NAME The name is invalid.
- //! \retval asALREADY_REGISTERED Another type of the same name already exists.
- //! \retval asNAME_TAKEN The name conflicts with other symbol names.
- //! \retval asLOWER_ARRAY_DIMENSION_NOT_REGISTERED When registering an array type the array element must be a primitive or a registered type.
- //! \retval asINVALID_TYPE The array type was not properly formed.
- //! \retval asNOT_SUPPORTED The array type is not supported, or already in use preventing it from being overloaded.
- //!
- //! Use this method to register new types that should be available to the scripts.
- //! Reference types, which have their memory managed by the application, should be registered with \ref asOBJ_REF.
- //! Value types, which have their memory managed by the engine, should be registered with \ref asOBJ_VALUE.
- //!
- //! \see \ref doc_register_type
- virtual int RegisterObjectType(const char *obj, int byteSize, asDWORD flags) = 0;
- //! \brief Registers a property for the object type.
- //!
- //! \param[in] obj The name of the type.
- //! \param[in] declaration The property declaration in script syntax.
- //! \param[in] byteOffset The offset into the memory block where this property is found.
- //! \return A negative value on error.
- //! \retval asWRONG_CONFIG_GROUP The object type was registered in a different configuration group.
- //! \retval asINVALID_OBJECT The \a obj does not specify an object type.
- //! \retval asINVALID_TYPE The \a obj parameter has invalid syntax.
- //! \retval asINVALID_DECLARATION The \a declaration is invalid.
- //! \retval asNAME_TAKEN The name conflicts with other members.
- //!
- //! Use this method to register a member property of a class. The property must
- //! be local to the object, i.e. not a global variable or a static member. The
- //! easiest way to get the offset of the property is to use the offsetof macro
- //! from stddef.h.
- //!
- //! \code
- //! struct MyType {float prop;};
- //! r = engine->RegisterObjectProperty("MyType", "float prop", offsetof(MyType, prop)));
- //! \endcode
- virtual int RegisterObjectProperty(const char *obj, const char *declaration, int byteOffset) = 0;
- //! \brief Registers a method for the object type.
- //!
- //! \param[in] obj The name of the type.
- //! \param[in] declaration The declaration of the method in script syntax.
- //! \param[in] funcPointer The method or function pointer.
- //! \param[in] callConv The calling convention for the method or function.
- //! \return A negative value on error, or the function id if successful.
- //! \retval asWRONG_CONFIG_GROUP The object type was registered in a different configuration group.
- //! \retval asNOT_SUPPORTED The calling convention is not supported.
- //! \retval asINVALID_TYPE The \a obj parameter is not a valid object name.
- //! \retval asINVALID_DECLARATION The \a declaration is invalid.
- //! \retval asNAME_TAKEN The name conflicts with other members.
- //! \retval asWRONG_CALLING_CONV The function's calling convention isn't compatible with \a callConv.
- //!
- //! Use this method to register a member method for the type. The method
- //! that is registered may be an actual class method, or a global function
- //! that takes the object pointer as either the first or last parameter. Or
- //! it may be a global function implemented with the generic calling convention.
- //!
- //! \see \ref doc_register_func
- virtual int RegisterObjectMethod(const char *obj, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv) = 0;
- //! \brief Registers a behaviour for the object type.
- //!
- //! \param[in] obj The name of the type.
- //! \param[in] behaviour One of the object behaviours from \ref asEBehaviours.
- //! \param[in] declaration The declaration of the method in script syntax.
- //! \param[in] funcPointer The method or function pointer.
- //! \param[in] callConv The calling convention for the method or function.
- //! \return A negative value on error, or the function id is successful.
- //! \retval asWRONG_CONFIG_GROUP The object type was registered in a different configuration group.
- //! \retval asINVALID_ARG \a obj is not set, or a global behaviour is given in \a behaviour.
- //! \retval asWRONG_CALLING_CONV The function's calling convention isn't compatible with \a callConv.
- //! \retval asNOT_SUPPORTED The calling convention or the behaviour signature is not supported.
- //! \retval asINVALID_TYPE The \a obj parameter is not a valid object name.
- //! \retval asINVALID_DECLARATION The \a declaration is invalid.
- //! \retval asILLEGAL_BEHAVIOUR_FOR_TYPE The \a behaviour is not allowed for this type.
- //! \retval asALREADY_REGISTERED The behaviour is already registered with the same signature.
- //!
- //! Use this method to register behaviour functions that will be called by
- //! the virtual machine to perform certain operations, such as memory management,
- //! math operations, comparisons, etc.
- //!
- //! \see \ref doc_register_func, \ref doc_reg_opbeh
- virtual int RegisterObjectBehaviour(const char *obj, asEBehaviours behaviour, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv) = 0;
- //! \brief Registers an interface.
- //!
- //! \param[in] name The name of the interface.
- //! \return A negative value on error.
- //! \retval asINVALID_NAME The \a name is null, or a reserved keyword.
- //! \retval asALREADY_REGISTERED An object type with this name already exists.
- //! \retval asERROR The \a name is not a proper identifier.
- //! \retval asNAME_TAKEN The \a name is already used elsewhere.
- //!
- //! This registers an interface that script classes can implement. By doing this the application
- //! can register functions and methods that receives an \ref asIScriptObject and still be sure that the
- //! class implements certain methods needed by the application.
- virtual int RegisterInterface(const char *name) = 0;
- //! \brief Registers an interface method.
- //!
- //! \param[in] intf The name of the interface.
- //! \param[in] declaration The method declaration.
- //! \return A negative value on error.
- //! \retval asWRONG_CONFIG_GROUP The interface was registered in another configuration group.
- //! \retval asINVALID_TYPE \a intf is not an interface type.
- //! \retval asINVALID_DECLARATION The \a declaration is invalid.
- //! \retval asNAME_TAKEN The method name is already taken.
- //!
- //! This registers a method that the class that implements the interface must have.
- virtual int RegisterInterfaceMethod(const char *intf, const char *declaration) = 0;
- //! \brief Returns the number of registered object types.
- //! \return The number of object types registered by the application.
- virtual int GetObjectTypeCount() = 0;
- //! \brief Returns the object type interface by index.
- //! \param[in] index The index of the type.
- //! \return The registered object type interface for the type, or null if not found.
- virtual asIObjectType *GetObjectTypeByIndex(asUINT index) = 0;
- //! \}
- // String factory
- //! \name String factory
- //! \{
- //! \brief Registers the string factory.
- //!
- //! \param[in] datatype The datatype that the string factory returns
- //! \param[in] factoryFunc The pointer to the factory function
- //! \param[in] callConv The calling convention of the factory function
- //! \return A negative value on error, or the function id if successful.
- //! \retval asNOT_SUPPORTED The calling convention is not supported.
- //! \retval asWRONG_CALLING_CONV The function's calling convention doesn't match \a callConv.
- //! \retval asINVALID_TYPE The \a datatype is not a valid type.
- //!
- //! Use this function to register a string factory that will be called when the
- //! virtual machine finds a string constant in an expression. The string factory
- //! function will receive two parameters, the length of the string constant in bytes and a
- //! pointer to the character data. The factory should return a value to a previously
- //! registered type that will represent the string. Example:
- //!
- //! \code
- //! // Our string factory implementation
- //! std::string StringFactory(unsigned int byteLength, const char *s)
- //! {
- //! return std::string(s, byteLength);
- //! }
- //!
- //! // Registering the string factory
- //! int r = engine->RegisterStringFactory("string", asFUNCTION(StringFactory), asCALL_CDECL); assert( r >= 0 );
- //! \endcode
- //!
- //! The example assumes that the std::string type has been registered as the string type, with \ref RegisterObjectType.
- virtual int RegisterStringFactory(const char *datatype, const asSFuncPtr &factoryFunc, asDWORD callConv) = 0;
- //! \brief Returns the type id of the type that the string factory returns.
- //! \return The type id of the type that the string type returns, or a negative value on error.
- //! \retval asNO_FUNCTION The string factory has not been registered.
- virtual int GetStringFactoryReturnTypeId() = 0;
- //! \}
- // Enums
- //! \name Enums
- //! \{
- //! \brief Registers an enum type.
- //!
- //! \param[in] type The name of the enum type.
- //! \return A negative value on error.
- //! \retval asINVALID_NAME \a type is null.
- //! \retval asALREADY_REGISTERED Another type with this name already exists.
- //! \retval asERROR The \a type couldn't be parsed.
- //! \retval asINVALID_NAME The \a type is not an identifier, or it is a reserved keyword.
- //! \retval asNAME_TAKEN The type name is already taken.
- //!
- //! This method registers an enum type in the engine. The enum values should then be registered
- //! with \ref RegisterEnumValue.
- virtual int RegisterEnum(const char *type) = 0;
- //! \brief Registers an enum value.
- //!
- //! \param[in] type The name of the enum type.
- //! \param[in] name The name of the enum value.
- //! \param[in] value The integer value of the enum value.
- //! \return A negative value on error.
- //! \retval asWRONG_CONFIG_GROUP The enum \a type was registered in a different configuration group.
- //! \retval asINVALID_TYPE The \a type is invalid.
- //! \retval asALREADY_REGISTERED The \a name is already registered for this enum.
- //!
- //! This method registers an enum value for a previously registered enum type.
- virtual int RegisterEnumValue(const char *type, const char *name, int value) = 0;
- //! \brief Returns the number of registered enum types.
- //! \return The number of registered enum types.
- virtual int GetEnumCount() = 0;
- //! \brief Returns the registered enum type.
- //! \param[in] index The index of the enum type.
- //! \param[out] enumTypeId Receives the type if of the enum type.
- //! \param[out] configGroup Receives the config group in which the enum was registered.
- //! \return The name of the registered enum type, or null on error.
- virtual const char *GetEnumByIndex(asUINT index, int *enumTypeId, const char **configGroup = 0) = 0;
- //! \brief Returns the number of enum values for the enum type.
- //! \param[in] enumTypeId The type id of the enum type.
- //! \return The number of enum values for the enum type.
- virtual int GetEnumValueCount(int enumTypeId) = 0;
- //! \brief Returns the name and value of the enum value for the enum type.
- //! \param[in] enumTypeId The type id of the enum type.
- //! \param[in] index The index of the enum value.
- //! \param[out] outValue Receives the value of the enum value.
- //! \return The name of the enum value.
- virtual const char *GetEnumValueByIndex(int enumTypeId, asUINT index, int *outValue) = 0;
- //! \}
- // Typedefs
- //! \name Typedefs
- //! \{
- //! \brief Registers a typedef.
- //!
- //! \param[in] type The name of the new typedef
- //! \param[in] decl The datatype that the typedef represents
- //! \return A negative value on error.
- //! \retval asINVALID_NAME The \a type is null.
- //! \retval asALREADY_REGISTERED A type with the same name already exists.
- //! \retval asINVALID_TYPE The \a decl is not a primitive type.
- //! \retval asINVALID_NAME The \a type is not an identifier, or it is a reserved keyword.
- //! \retval asNAME_TAKEN The name is already used elsewhere.
- //!
- //! This method registers an alias for a data type.
- //!
- //! Currently typedefs can only be registered for built-in primitive types.
- virtual int RegisterTypedef(const char *type, const char *decl) = 0;
- //! \brief Returns the number of registered typedefs.
- //! \return The number of registered typedefs.
- virtual int GetTypedefCount() = 0;
- //! \brief Returns a registered typedef.
- //! \param[in] index The index of the typedef.
- //! \param[out] typeId The type that the typedef aliases.
- //! \param[out] configGroup Receives the config group in which the type def was registered.
- //! \return The name of the typedef.
- virtual const char *GetTypedefByIndex(asUINT index, int *typeId, const char **configGroup = 0) = 0;
- //! \}
- // Configuration groups
- //! \name Configuration groups
- //! \{
- //! \brief Starts a new dynamic configuration group.
- //!
- //! \param[in] groupName The name of the configuration group
- //! \return A negative value on error
- //! \retval asNAME_TAKEN Another group with the same name already exists.
- //! \retval asNOT_SUPPORTED Nesting configuration groups is not supported.
- //!
- //! Starts a new dynamic configuration group. This group can be setup so that it is only
- //! visible to specific modules, and it can also be removed when it is no longer used.
- virtual int BeginConfigGroup(const char *groupName) = 0;
- //! \brief Ends the configuration group.
- //!
- //! \return A negative value on error
- //! \retval asNOT_SUPPORTED Can't end a group that hasn't been begun.
- //!
- //! Ends the current configuration group. Once finished a config group cannot be changed,
- //! but it can be removed when it is no longer used.
- virtual int EndConfigGroup() = 0;
- //! \brief Removes a previously registered configuration group.
- //!
- //! \param[in] groupName The name of the configuration group
- //! \return A negative value on error
- //! \retval asCONFIG_GROUP_IS_IN_USE The group is in use and cannot be removed.
- //!
- //! Remove the configuration group. If something in the configuration group is currently in
- //! use, the function will return with an error code. Examples of uses are compiled modules
- //! that have function calls to functions in the group and global variables of types registered
- //! in the group.
- virtual int RemoveConfigGroup(const char *groupName) = 0;
- //! \brief Tell AngelScript which modules have access to which configuration groups.
- //!
- //! \param[in] groupName The name of the configuration group
- //! \param[in] module The module name
- //! \param[in] hasAccess Whether the module has access or not to the group members
- //! \return A negative value on error
- //! \retval asWRONG_CONFIG_GROUP No group with the \a groupName was found.
- //!
- //! With this method the application can give modules access to individual configuration groups.
- //! This is useful when exposing more than one script interface for various parts of the application,
- //! e.g. one interface for GUI handling, another for in-game events, etc.
- //!
- //! The default module access is granted. The default for a group can be changed by specifying
- //! the modulename asALL_MODULES.
- virtual int SetConfigGroupModuleAccess(const char *groupName, const char *module, bool hasAccess) = 0;
- //! \}
- // Script modules
- //! \name Script modules
- //! \{
- //! \brief Return an interface pointer to the module.
- //!
- //! \param[in] module The name of the module
- //! \param[in] flag One of the \ref asEGMFlags flags
- //! \return A pointer to the module interface
- //!
- //! Use this method to get access to the module interface, which will
- //! let you build new scripts, and enumerate functions and types in
- //! existing modules.
- //!
- //! If \ref asGM_ALWAYS_CREATE is informed as the flag the previous
- //! module with the same name will be discarded, thus any pointers that
- //! the engine holds to it will be invalid after the call.
- virtual asIScriptModule *GetModule(const char *module, asEGMFlags flag = asGM_ONLY_IF_EXISTS) = 0;
- //! \brief Discard a module.
- //!
- //! \param[in] module The name of the module
- //! \return A negative value on error
- //! \retval asNO_MODULE The module was not found.
- //!
- //! Discards a module and frees its memory. Any pointers that the application holds
- //! to this module will be invalid after this call.
- virtual int DiscardModule(const char *module) = 0;
- //! \}
- // Script functions
- //! \name Script functions
- //! \{
- //! \brief Returns the function descriptor for the script function
- //! \param[in] funcId The id of the function or method.
- //! \return A pointer to the function description interface, or null if not found.
- virtual asIScriptFunction *GetFunctionDescriptorById(int funcId) = 0;
- //! \}
- // Type identification
- //! \name Type identification
- //! \{
- //! \brief Returns the object type interface for type.
- //! \param[in] typeId The type id of the type.
- //! \return The object type interface for the type, or null if not found.
- virtual asIObjectType *GetObjectTypeById(int typeId) = 0;
- //! \brief Returns a type id by declaration.
- //! \param[in] decl The declaration of the type.
- //! \return A negative value on error, or the type id of the type.
- //! \retval asINVALID_TYPE \a decl is not a valid type.
- //!
- //! Translates a type declaration into a type id. The returned type id is valid for as long as
- //! the type is valid, so you can safely store it for later use to avoid potential overhead by
- //! calling this function each time. Just remember to update the type id, any time the type is
- //! changed within the engine, e.g. when recompiling script declared classes, or changing the
- //! engine configuration.
- //!
- //! The type id is based on a sequence number and depends on the order in which the type ids are
- //! queried, thus is not guaranteed to always be the same for each execution of the application.
- //! The \ref asETypeIdFlags can be used to obtain some information about the type directly from the id.
- //!
- //! A base type yields the same type id whether the declaration is const or not, however if the
- //! const is for the subtype then the type id is different, e.g. string@ isn't the same as const
- //! string@ but string is the same as const string.
- //!
- //! This method is only able to return the type id that are not specific for a script module, i.e.
- //! built-in types and application registered types. Type ids for script declared types should
- //! be obtained through the script module's \ref asIScriptModule::GetTypeIdByDecl "GetTypeIdByDecl".
- virtual int GetTypeIdByDecl(const char *decl) = 0;
- //! \brief Returns a type declaration.
- //! \param[in] typeId The type id of the type.
- //! \return A null terminated string with the type declaration, or null if not found.
- virtual const char *GetTypeDeclaration(int t…
Large files files are truncated, but you can click here to view the full file