![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
The engine configuration interface defines the engine-specific settings which can be modified prior to starting the engine only, e.g.
IApp::Configure().
Get the const platform configuration object.
Murl.IPlatformConfiguration GetPlatformConfiguration()
Get the application configuration object.
Murl.IAppConfiguration GetAppConfiguration()
Check is any configuration setting has changed.
Boolean, Murl.ChangeInspector HasChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Get the constant set of default graph parameters.
Murl.IAttributes GetDefaultGraphParameters()
Get the const feature set object.
Murl.IFeatureSet GetFeatures()
Get the major revision of the engine.
Integer GetMajorRevision()
Get the minor revision of the engine.
Integer GetMinorRevision()
Get the build number of the engine.
Integer GetBuildNumber()
Get the release state string of the engine.
String GetReleaseState()
Get the version string of the engine.
String GetVersionString()
Get the copyright string of the engine.
String GetCopyrightString()
Get the licence key data object.
Murl.ConstData GetLicenseKey()
Set the log file name. If the log file name is set, all MURL_TRACE, MURL_ERROR and MURL_ASSERT messages are written into the file.
The default log file name is empty.
SetLogFileName(String logFileName)
logFileName | The log file name, see also SetLogFileFullPath(). |
Get the log file name.
String GetLogFileName()
Set the log file full path.
SetLogFileFullPath(String logFilePath)
logFilePath | The log file full path, see also SetLogFileName(). |
Get the log file full path.
String GetLogFileFullPath()
Set the engine's run loop mode.
SetRunLoopMode(Murl.IEnums.RunLoopMode runLoopMode)
runLoopMode | The run loop mode. |
Get the engine's run loop mode.
Murl.IEnums.RunLoopMode GetRunLoopMode()
Set the boot time.
SetBootTime(Murl.System.Time time)
time | The boot time in number of seconds since 00:00 hours, Jan 1, 1970 UTC. |
Get the boot time.
Murl.System.Time GetBootTime()
Check if the boot time has changed.
Boolean, Murl.ChangeInspector HasBootTimeChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the product name. The product name is used to create a subfolder for IEnums::FILE_CATEGORY_CACHE, IEnums::FILE_CATEGORY_PRIVATE, and IEnums::FILE_CATEGORY_TEMPORARY except on iOS.
The OSX platform uses the product name to replace "%@" in all interface builder's menu items.
On OSX and iOS the product name is set to the kCFBundleExecutableKey identifier.
On Android the product name is set to the application android:label from the manifest.
On Win32 the product name is set to the "ProductName" from version info resource.
SetProductName(String productName)
productName | The product name. |
Get the product name.
String GetProductName()
Check if the product name has changed.
Boolean, Murl.ChangeInspector HasProductNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the app version name. On OSX and iOS the app version name is set to the kCFBundleVersionKey identifier.
On Android the app version name is set to the android:versionName from the manifest.
On Win32 the app version name is set to the "ProductVersion" from version info resource.
SetVersionName(String versionName)
versionName | The app version name. |
Get the app version name.
String GetVersionName()
Check if the app version name has changed.
Boolean, Murl.ChangeInspector HasVersionNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the audio session category. Setting the audio session category effects the IMusicPlayerControl only.
If IEnums::AUDIO_SESSION_CATEGORY_MIX_AMBIENT_IF_PLAYING is set, the system's audio session is set to mix ambient if another audio is playing otherwise the system's audio session is not set (default category behaviour). After IApp::Configure() the IMusicPlayerControl::GetPlaybackState() returns IMusicPlayerControl::PLAYBACK_PLAYING if another audio was playing at app start until a IMusicPlayerControl::MusicPlayer is selected.
The default audio session category is IEnums::AUDIO_SESSION_CATEGORY_DEFAULT.
SetAudioSessionCategory(Murl.IEnums.AudioSessionCategory sessionCategory)
sessionCategory | The audio session category. |
Get the audio session category. The IMusicPlayerControl does not change this item.
Murl.IEnums.AudioSessionCategory GetAudioSessionCategory()
Check if the audio session category has changed.
Boolean, Murl.ChangeInspector HasAudioSessionCategoryChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the video api enumeration value. Typically the platform implementaition sets this to an appropriate value, see also SetVideoRendererClassName().
The default video api is IEnums::VIDEO_API_DEFAULT.
SetVideoApi(Murl.IEnums.VideoApi videoApi)
videoApi | The video api enumeration value. |
Get the video api enumeration value.
Murl.IEnums.VideoApi GetVideoApi()
Check if the video api is matching a specified value.
Boolean IsVideoApiMatching(Murl.IEnums.VideoApi videoApi)
videoApi | The video api enumeration value. |
Check if the video api enumeration value has changed.
Boolean, Murl.ChangeInspector HasVideoApiChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the audio api enumeration value. Typically the platform implementaition sets this to an appropriate value, see also SetAudioRendererClassName().
The default audio api is IEnums::AUDIO_API_DEFAULT.
SetAudioApi(Murl.IEnums.AudioApi audioApi)
audioApi | The audio api enumeration value. |
Get the audio api enumeration value.
Murl.IEnums.AudioApi GetAudioApi()
Check if the audio api is matching a specified value.
Boolean IsAudioApiMatching(Murl.IEnums.AudioApi audioApi)
audioApi | The audio api enumeration value. |
Check if the audio api enumeration value has changed.
Boolean, Murl.ChangeInspector HasAudioApiChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the video renderer class name. If the video renderer class name is empty the engine creates a renderer depending on the value set by SetVideoApi().
The default video renderer class name is empty.
SetVideoRendererClassName(String className)
className | The video renderer class name. |
Get the video renderer class name.
String GetVideoRendererClassName()
Check if the video renderer class name has changed.
Boolean, Murl.ChangeInspector HasVideoRendererClassNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the audio renderer class name. If the audio renderer class name is empty the engine creates a renderer depending on the value set by SetAudioApi().
The default audio renderer class name is empty.
SetAudioRendererClassName(String className)
className | The audio renderer class name. |
Get the audio renderer class name.
String GetAudioRendererClassName()
Check if the audio renderer class name has changed.
Boolean, Murl.ChangeInspector HasAudioRendererClassNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the physics simulator class name. If the physics simulator class name is empty the engine creates the built-in simulator.
The default physics simulator class name is empty.
SetPhysicsSimulatorClassName(String className)
className | The physics simulator class name. |
Get the physics simulator class name.
String GetPhysicsSimulatorClassName()
Check if the physics simulator class name has changed.
Boolean, Murl.ChangeInspector HasPhysicsSimulatorClassNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the resource collection class name. If the resource collection class name is empty the engine creates the built-in collection.
The default resource collection class name is empty.
SetResourceCollectionClassName(String className)
className | The resource collection class name. |
Get the resource collection class name.
String GetResourceCollectionClassName()
Check if the resource collection class name has changed.
Boolean, Murl.ChangeInspector HasResourceCollectionClassNameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the preferred resource package type. When a package is added to the loader in the App::Init() method without explicitly specifying a file suffix (.murlres/.murlpkg), the resource system loads the first appropriate package found in the folder specified by SetResourceFileCategory(); usually, this will be a .murlpkg file if present. During development it may be convenient to directly work from .murlres packages, so one does not need to run the resource packer tool every time the application is started. For this reason, this method can be used to manually specify a different preferred package type. By default, release builds on all platforms use the IEnums::PACKAGE_TYPE_NATIVE type, and IEnums::PACKAGE_TYPE_XML is used for debug builds on all available platforms except Android (where only native packages are supported). If a file suffix is specified, this setting has no effect.
SetPreferredResourcePackageType(Murl.IEnums.PackageType type)
type | The preferred resource package type. |
Get the preferred resource package type.
Murl.IEnums.PackageType GetPreferredResourcePackageType()
Check if the preferred resource package type has changed.
Boolean, Murl.ChangeInspector HasPreferredResourcePackageTypeChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the resource file category. The category specifies the working directory of the package loader. On desktop platforms the category is set to Murl::IEnums::FILE_CATEGORY_CURRENT in debug build, which allows easier development.
The default resource file category is IEnums::FILE_CATEGORY_RESOURCE.
SetResourceFileCategory(Murl.IEnums.FileCategory category)
category | The resource file category. |
Get the resource file category.
Murl.IEnums.FileCategory GetResourceFileCategory()
Check if the resource file category has changed.
Boolean, Murl.ChangeInspector HasResourceFileCategoryChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the deactivated application run state. Depending on this setting the platform implementation decides how to set the IAppConfiguration::SetAppRunState() if the application is activated or deactivated.
The application is deactivated:
The default deactivated application run state is IEnums::APP_RUN_STATE_DEFAULT which performs no action.
SetDeactivatedAppRunState(Murl.IEnums.AppRunState appRunState)
appRunState | The deactivated application run state. |
Get the deactivated application run state.
Murl.IEnums.AppRunState GetDeactivatedAppRunState()
Check if the deactivated application run state has changed.
Boolean, Murl.ChangeInspector HasDeactivatedAppRunStateChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the suspend unloads resources flag. If the suspend unloads resources flag is true the engine unloads all resource types specified by SetSuspendableResources() if the IAppConfiguration::SetAppRunState() is set to IEnums::APP_RUN_STATE_SUSPENDED.
The default suspend unloads resources flag is false.
SetSuspendUnloadsResources(Boolean unload)
unload | The suspend unloads resources flag. |
Get the suspend unloads resources flag.
Boolean GetSuspendUnloadsResources()
Check if the suspend unloads resources flag has changed.
Boolean, Murl.ChangeInspector HasSuspendUnloadsResourcesChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the suspendable resources type. See also SetSuspendUnloadsResources().
The default suspendable resources value is IEnums::SUSPENDABLE_RESOURCE_ALL.
SetSuspendableResources(Integer suspendableResources)
suspendableResources | The suspendable resources type. |
Get the suspendable resources type.
Integer GetSuspendableResources()
Check if the suspendable resources type has changed.
Boolean, Murl.ChangeInspector HasSuspendableResourcesChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the global unit size factor. The global unit size factor is multiplied to the camera's unit size.
The default global unit size factor is 1.0.
SetUnitSize(Number sizeX, Number sizeY)
sizeX | The horizontal unit size factor. |
sizeY | The vertical unit size factor. |
Get the horizontal unit size factor.
Number GetUnitSizeX()
Get the vertical unit size factor.
Number GetUnitSizeY()
Check if the global unit size factor has changed.
Boolean, Murl.ChangeInspector HasUnitSizeChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the pixel center position. The pixel center position is used by the camera, the range is [0 .. 1]. The pixel center is typically determined by the platform implementation depending on the graphic driver's properties.
The default pixel center position is 0 / 0.
SetPixelCenter(Number centerX, Number centerY)
centerX | The horizontal pixel center position. |
centerY | The vertical pixel center position. |
Get the horizontal pixel center position.
Number GetPixelCenterX()
Get the vertical pixel center position.
Number GetPixelCenterY()
Check if the global pixel center position has changed.
Boolean, Murl.ChangeInspector HasPixelCenterChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the synchronous resource initialization timeout. Is used only if SetAsyncLoadingEnabled() is set to false. The timeout specifies the maximum time to use for initializing multiple graphic objects before the next frame is rendered. At least one object is initialized each frame which can take more time than the timeout depending on the complexity of the object.
The default timeout is 0.005 seconds.
SetSyncLoadingTimeout(Number timeout)
timeout | The loading timeout in seconds. |
Get the synchronous resource initialization timeout.
Number GetSyncLoadingTimeout()
Check if the synchronous resource initialization timeout has changed.
Boolean, Murl.ChangeInspector HasSyncLoadingTimeoutChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Enable asynchronous resource initialization after loading. Setup how to initialize loaded graphic objects:
This feature is typically determined by the platform implementation depending on the graphic driver's capabilities.
The default value is true.
SetAsyncLoadingEnabled(Boolean enabled)
enabled | true to enable. |
Check if the asynchronous loading is enabled.
Boolean IsAsyncLoadingEnabled()
Check if the asynchronous loading setting has changed.
Boolean, Murl.ChangeInspector HasAsyncLoadingEnabledChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Enable synchronous vertical blank page flipping. The platform implementation is using this setting to enable vertical blank page flipping depending on the graphic driver capabilities.
The default value is true.
SetSyncToVBlankEnabled(Boolean enabled)
enabled | true to enable. |
Check if the synchronous vertical blank page flipping is enabled.
Boolean IsSyncToVBlankEnabled()
Check if the synchronous vertical blank page flipping setting has changed.
Boolean, Murl.ChangeInspector HasSyncToVBlankEnabledChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Enable checks to video api calls. Api checks are used for development purposes and are available in debug build only.
The default value is false.
SetVideoApiChecksEnabled(Boolean enabled)
enabled | true to enable. |
Check if the video api check feature is enabled.
Boolean AreVideoApiChecksEnabled()
Check if the video api check setting has changed.
Boolean, Murl.ChangeInspector HasVideoApiChecksEnabledChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Enable checks to audio api calls. Api checks are used for development purposes and are available in debug build only.
The default value is false.
SetAudioApiChecksEnabled(Boolean enabled)
enabled | true to enable. |
Check if the audio api check feature is enabled.
Boolean AreAudioApiChecksEnabled()
Check if the audio api check setting has changed.
Boolean, Murl.ChangeInspector HasAudioApiChecksEnabledChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the number of antialiasing samples. The platform implementation is using this setting depending on the graphic driver capabilities.
The default value is 1.
SetNumberOfAntialiasSamples(Integer numSamples)
numSamples | The number of antialiasing samples. |
Get the number of antialiasing samples.
Integer GetNumberOfAntialiasSamples()
Check if the number of antialiasing samples has changed.
Boolean, Murl.ChangeInspector HasNumberOfAntialiasSamplesChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the default maximum texture anisotropy for filtering. This value specifies the preferred maximum anisotropy used for texture filtering if not specified for a given texture. The actual value is clamped to hardware-specific limits. Higher values produce better visual results, but may result in degraded rendering performance. The default value is 1.0, i.e. isotropic filtering (fastest). The maximum anisotropy value supported by the hardware is typically around 16.0.
SetDefaultMaxTextureAnisotropy(Number maxAnisotropy)
maxAnisotropy | The default maximum texture filtering anisotropy. |
Get the default maximum texture anisotropy for filtering.
Number GetDefaultMaxTextureAnisotropy()
Check if the default maximum texture anisotropy has changed.
Boolean, Murl.ChangeInspector HasDefaultMaxTextureAnisotropyChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the texture prescale divisor. The texture prescale divisor is used to shrink textures before loading to the graphics memory. This allows reducing of memory usage on small equipped platforms.
The default texture prescale divisor is 1.
SetTexturePrescaleDivisor(Integer divisor)
divisor | The texture prescale divisor. |
Get the texture prescale divisor.
Integer GetTexturePrescaleDivisor()
Check if the texture prescale divisor matching a specified value.
Boolean IsTexturePrescaleDivisorMatching(Integer divisor)
divisor | The divisor value to check. |
Check if the texture prescale divisor has changed.
Boolean, Murl.ChangeInspector HasTexturePrescaleDivisorChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the exact logic tick duration. Set the duration bounds to the same value, see SetBoundsForLogicTickDuration().
SetExactLogicTickDuration(Number dt)
dt | The exact logic tick duration in seconds. |
Set the logic tick duration bounds. The logic tick duration allows exact tick cycles for e.g. physics simulation.
If the bounds have the same value, the SetBoundsForLogicTicksPerFrame() should be set to an appropriate range.
The default value is (0, 1).
SetBoundsForLogicTickDuration(Number dtMin, Number dtMax)
dtMin | The minimum logic tick duration in seconds. |
dtMax | The maximum logic tick duration in seconds. |
Get minimum logic tick duration in seconds.
Number GetMinimumLogicTickDuration()
Get maximum logic tick duration in seconds.
Number GetMaximumLogicTickDuration()
Check if the logic tick duration setting has changed.
Boolean, Murl.ChangeInspector HasLogicTickDurationChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Set the exact number of logic ticks per frame. Set the per frame bounds to the same value, see SetBoundsForLogicTicksPerFrame().
SetExactLogicTicksPerFrame(Integer numTicks)
numTicks | The exact number of logic ticks per frame. |
Set the number of logic ticks per frame bounds. If the bounds have the same value, the SetBoundsForLogicTickDuration() should be set to an appropriate range.
The default value is (1, 1).
SetBoundsForLogicTicksPerFrame(Integer numTicksMin, Integer numTicksMax)
numTicksMin | The minimum number of logic logic ticks per frame. |
numTicksMax | The maximum number of logic logic ticks per frame. |
Get minimum number of logic logic ticks per frame.
Integer GetMinimumLogicTicksPerFrame()
Get maximum number of logic logic ticks per frame.
Integer GetMaximumLogicTicksPerFrame()
Check if the number of logic logic ticks per frame setting has changed.
Boolean, Murl.ChangeInspector HasLogicTicksPerFrameChanged(Murl.ChangeInspector inspector)
inspector | The change inspector. |
Add a user-defined system font. This method can be used to define additional platform-specific system fonts used in conjunction with a Graph::IFlatTextTexture. If user-defined system fonts are required, this method must be called with different values for the "fontName" parameter depending on the platform. In addition, some platforms accept a "Bold" identifier as part of the font name, e.g. "Helvetica-Bold" on iOS and OSX. In this case, the weight parameter is ignored. On other platforms, it is required to specify the boldness of the font via the "weight" parameter (usually 400 for regular thickness and 800 for bold fonts), and only specify the font name without style.
AddSystemFont(String fontId, String fontName, Number weight, Number sizeFactor, Number ascent, Number descent, Number leading)
fontId | The unique font ID within the Murl Engine. |
fontName | The font name, as expected by the operating system. |
weight | The font weight (default 400), if supported by the operating system. |
sizeFactor | The scale factor to apply (default 1.0). |
ascent | The font ascent, i.e. height above the base line. Ascent and descent should sum up to 1.0. |
descent | The font descent. |
leading | The font leading, i.e. additional space between consecutive text lines. |
Get the number of user-defined system fonts.
Integer GetNumberOfSystemFonts()
Get the internal ID of the user-defined system font at a given index.
String GetSystemFontId(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the OS-specific name of the user-defined system font at a given index.
String GetSystemFontName(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the weight of the user-defined system font at a given index.
Number GetSystemFontWeight(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the size factor of the user-defined system font at a given index.
Number GetSystemFontSizeFactor(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the ascent of the user-defined system font at a given index.
Number GetSystemFontAscent(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the descent of the user-defined system font at a given index.
Number GetSystemFontDescent(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Get the leading value of the user-defined system font at a given index.
Number GetSystemFontLeading(Integer index)
index | The index of the font, in the range from 0 to GetNumberOfSystemFonts()-1. |
Enable the virtual mouse device. A virtual mouse is available on AppleTV Siri Remote device. The default value is true on AppleTV, otherwise false.
SetVirtualMouseEnable(Boolean isEnabled)
isEnabled | The enabled state. |
Check if the virtual mouse device is enabled.
Boolean IsVirtualMouseEnabled()
Enable the virtual raw-mouse device. A virtual raw-mouse is available on AppleTV Siri Remote device. The default value is true on AppleTV, otherwise false.
SetVirtualRawMouseEnable(Boolean isEnabled)
isEnabled | The enabled state. |
Check if the virtual raw-mouse device is enabled.
Boolean IsVirtualRawMouseEnabled()
Enable the cloud control. The cloud control is available on iOS/OSX/tvOS. The default value is false, if enabled an iCloud entitlement must be setup for the application,
SetCloudControlEnable(Boolean isEnabled)
isEnabled | The enabled state. |
Check if the cloud control is enabled.
Boolean IsCloudControlEnabled()
SetDefaultDepthBufferFormat(Murl.IEnums.DepthBufferFormat depthBufferFormat)
Murl.IEnums.DepthBufferFormat GetDefaultDepthBufferFormat()
Boolean, Murl.ChangeInspector HasDefaultDepthBufferFormatChanged(Murl.ChangeInspector inspector)
SetDefaultRgbPixelFormat(Murl.IEnums.RgbPixelFormat pixelFormat)
Murl.IEnums.RgbPixelFormat GetDefaultRgbPixelFormat()
Boolean, Murl.ChangeInspector HasDefaultRgbPixelFormatChanged(Murl.ChangeInspector inspector)
SetDefaultRgbaPixelFormat(Murl.IEnums.RgbaPixelFormat pixelFormat)
Murl.IEnums.RgbaPixelFormat GetDefaultRgbaPixelFormat()
Boolean, Murl.ChangeInspector HasDefaultRgbaPixelFormatChanged(Murl.ChangeInspector inspector)
Murl.IEnums.PixelFormat GetDefaultResourcePixelFormat(Boolean useAlpha)