![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
The IMaterial graph node interface.
Material nodes hold common rendering parameters that cannot be controlled via GPU shader programs or fixed function programs, such as e.g. depth and stencil buffer access modes and actions, or different blend modes and blend equations.
A material must always refer to exactly one Graph::IProgram, which is used to calculate actual per-pixel color values.
Use the Graph::IStateSlot base interface to set or get the material slot index this material is temporarily attached to if any children are present.
See sceneGraphStatesSlotsUnits for an overview of state handling during scene graph traversal.
See Graph::IMaterialState for activating a material for rendering. See Graph::IProgram for defining GPU programs to refer to. See Graph::IParameters for defining actual program parameters.
Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.
Murl.Graph.INode GetNodeInterface()
Get the constant container holding the optional child materials. This method returns a constant pointer to the node's Graph::IMaterialNodeTarget sub container, which is used to store multiple sub-materials.
Murl.Graph.IGenericNodeTarget.GraphIMaterial GetSubMaterialNodeTarget()
Get the constant Graph::IProgramNodeTarget container. This method returns a constant pointer to the node's Graph::IProgramNodeTarget container, which allows to query the program object used with this material.
Murl.Graph.IGenericNodeTarget.GraphIProgram GetProgramNodeTarget()
Set which faces of a triangle are visible for rendering.
Boolean SetVisibleFaces(Murl.IEnums.PolygonFaces faces)
faces | One of the available IEnums::PolygonFaces enumeration values. |
Check which faces of a triangle are visible for rendering.
Murl.IEnums.PolygonFaces GetVisibleFaces()
Set the material's color buffer access mode. The color buffer access mode can be set to either IEnums::COLOR_BUFFER_MODE_WRITE_ONLY to enable writing to the color buffer, or IEnums::COLOR_BUFFER_MODE_NONE to disable color output. Use SetColorBufferMask() to enable/disable specific color channels when writing is enabled.
Boolean SetColorBufferMode(Murl.IEnums.ColorBufferMode mode)
mode | The color buffer access mode. |
Get the material's color buffer access mode.
Murl.IEnums.ColorBufferMode GetColorBufferMode()
Set the material's color buffer mask. If color buffer writes are enabled, and a specific bit is set in the given mask, the respective color channel is enabled for writing, otherwise that channel is not written to the output pixels. To generally enable/disable color buffer writes, use SetColorBufferMode().
Boolean SetColorBufferMask(Integer mask)
mask | The color buffer write mask. |
Get the material's color buffer mask.
Integer GetColorBufferMask()
Set the material's depth buffer access mode. The depth buffer access mode can be set to enable/disable both depth buffer reads and writes, through one of the available IEnums::DepthBufferMode values.
Boolean SetDepthBufferMode(Murl.IEnums.DepthBufferMode mode)
mode | The depth buffer access mode. |
Get the material's depth buffer access mode.
Murl.IEnums.DepthBufferMode GetDepthBufferMode()
Set the material's depth buffer mask. This method can be used to independently enable/disable depth buffer writes in addition to the general depth buffer access mode set via SetDepthBufferMode().
Boolean SetDepthBufferMask(Integer mask)
mask | The depth buffer write mask. |
Get the material's depth buffer mask.
Integer GetDepthBufferMask()
Set the material's depth test function. If the material's depth buffer access mode is set to either IEnums::DEPTH_BUFFER_MODE_READ_ONLY or IEnums::DEPTH_BUFFER_MODE_READ_AND_WRITE, the given function is used for all depth buffer comparisons using this material. The output pixel is only written if the result of its depth comparison is true using the given function.
Boolean SetDepthTestFunction(Murl.IEnums.DepthTestFunction function)
function | The depth test function. |
Get the material's depth test function.
Murl.IEnums.DepthTestFunction GetDepthTestFunction()
Set the material's stencil buffer access mode. The stencil buffer access mode can be set to enable/disable both stencil buffer reads and writes, through one of the available IEnums::StencilBufferMode values.
Boolean SetStencilBufferMode(Murl.IEnums.StencilBufferMode mode)
mode | The stencil buffer access mode. |
Get the material's stencil buffer access mode.
Murl.IEnums.StencilBufferMode GetStencilBufferMode()
Set the material's stencil buffer mask. If stencil buffer writes are enabled, and a specific bit is set in the given mask, the respective stencil bit is enabled for writing, otherwise that bit is not written to the output pixels. To generally enable/disable stencil buffer writes, use SetStencilBufferMode().
Boolean SetStencilBufferMask(Integer mask)
mask | The stencil buffer write mask. |
Get the material's stencil buffer mask.
Integer GetStencilBufferMask()
Set the material's stencil test functions. If the material's stencil buffer access mode is set to either IEnums::STENCIL_BUFFER_MODE_READ_ONLY or IEnums::STENCIL_BUFFER_MODE_READ_AND_WRITE, the given functions are used for all stencil buffer comparisons using this material. The output pixel is only written if the result of its stencil comparison is true using the given function.
Boolean SetStencilTestFunction(Murl.IEnums.StencilTestFunction frontFunction, Murl.IEnums.StencilTestFunction backFunction)
frontFunction | The stencil test function used for front-facing primitives. |
backFunction | The stencil test function used for back-facing primitives. |
Set the material's stencil test function for front-facing primitives.
Murl.IEnums.StencilTestFunction GetFrontStencilTestFunction()
Set the material's stencil test function for back-facing primitives.
Murl.IEnums.StencilTestFunction GetBackStencilTestFunction()
Set the material's stencil test reference values. If stencil test is enabled (see SetStencilBufferMode()), the values given represent the actual reference values used for the per-pixel stencil test with the respective functions specified via SetStencilTestFunction(). In addition, before each comparison, both test value and reference value are ANDed with the test mask given via SetStencilTestMask().
Boolean SetStencilTestReferenceValue(Integer frontValue, Integer backValue)
frontValue | The reference value used for comparing pixels of front-facing primitives. |
backValue | The reference value used for comparing pixels of back-facing primitives. |
Get the material's stencil test reference value for testing front-facing primitives.
Integer GetFrontStencilTestReferenceValue()
Get the material's stencil test reference value for testing back-facing primitives.
Integer GetBackStencilTestReferenceValue()
Set the material's stencil test masks. See SetStencilTestReferenceValue().
Boolean SetStencilTestMask(Integer frontMask, Integer backMask)
frontMask | The comparison mask for front-facing primitives. |
backMask | The comparison mask for back-facing primitives. |
Get the material's stencil test mask for front-facing primitives.
Integer GetFrontStencilTestMask()
Get the material's stencil test mask for back-facing primitives.
Integer GetBackStencilTestMask()
Set the actions to be performed if the stencil test fails. If stencil test is enabled (see SetStencilBufferMode()), the given actions specify how the stencil buffer is modified whenever the stencil test fails for a pixel.
Boolean SetStencilBufferActionForFailedStencilTest(Murl.IEnums.StencilBufferAction frontAction, Murl.IEnums.StencilBufferAction backAction)
frontAction | The action to perform for front-facing primitives. |
backAction | The action to perform for back-facing primitives. |
Get the front-facing primitive stencil buffer action for failed stencil tests.
Murl.IEnums.StencilBufferAction GetFrontStencilBufferActionForFailedStencilTest()
Get the back-facing primitive stencil buffer action for failed stencil tests.
Murl.IEnums.StencilBufferAction GetBackStencilBufferActionForFailedStencilTest()
Set the actions to be performed if the stencil test passes, but the depth test fails. If stencil test is enabled (see SetStencilBufferMode()), the given actions specify how the stencil buffer is modified whenever the depth test fails for a pixel (after successfully passing the stencil test).
Boolean SetStencilBufferActionForFailedDepthTest(Murl.IEnums.StencilBufferAction frontAction, Murl.IEnums.StencilBufferAction backAction)
frontAction | The action to perform for front-facing primitives. |
backAction | The action to perform for back-facing primitives. |
Get the front-facing primitive stencil buffer action for failed depth tests.
Murl.IEnums.StencilBufferAction GetFrontStencilBufferActionForFailedDepthTest()
Get the back-facing primitive stencil buffer action for failed depth tests.
Murl.IEnums.StencilBufferAction GetBackStencilBufferActionForFailedDepthTest()
Set the actions to be performed if both the stencil test and the depth test pass. If stencil test is enabled (see SetStencilBufferMode()), the given actions specify how the stencil buffer is modified whenever both stencil and depth test succeed for a pixel.
Boolean SetStencilBufferActionForPassedDepthTest(Murl.IEnums.StencilBufferAction frontAction, Murl.IEnums.StencilBufferAction backAction)
frontAction | The action to perform for front-facing primitives. |
backAction | The action to perform for back-facing primitives. |
Get the front-facing primitive stencil buffer action for passed depth tests.
Murl.IEnums.StencilBufferAction GetFrontStencilBufferActionForPassedDepthTest()
Get the back-facing primitive stencil buffer action for passed depth tests.
Murl.IEnums.StencilBufferAction GetBackStencilBufferActionForPassedDepthTest()
Set the material's blend mode.
Boolean SetBlendMode(Murl.IEnums.BlendMode mode)
mode | The blend mode. |
Get the material's blend mode.
Murl.IEnums.BlendMode GetBlendMode()
Set the material's blending functions. If alpha blending is enabled (SetBlendMode() with a parameter of IEnums::BLEND_MODE_ALPHA), this method sets the combiner factors used for calculating the actual output pixel RGBA values depending on the source and destination pixel's color and alpha values. The values resulting from evaluating these functions are then combined using the blending equations set via SetBlendEquation().
Boolean SetBlendFunction(Murl.IEnums.BlendFunction srcColorFunction, Murl.IEnums.BlendFunction srcAlphaFunction, Murl.IEnums.BlendFunction dstColorFunction, Murl.IEnums.BlendFunction dstAlphaFunction)
srcColorFunction | The combiner function for the source pixel's RGB values. |
srcAlphaFunction | The combiner function for the source pixel's alpha value. |
dstColorFunction | The combiner function for the destination pixel's RGB values. |
dstAlphaFunction | The combiner function for the destination pixel's alpha value. |
Get the material's blending function used for the source pixels' RGB values.
Murl.IEnums.BlendFunction GetSrcColorBlendFunction()
Get the material's blending function used for the source pixels' alpha value.
Murl.IEnums.BlendFunction GetSrcAlphaBlendFunction()
Get the material's blending function used for the destination pixels' RGB values.
Murl.IEnums.BlendFunction GetDstColorBlendFunction()
Get the material's blending function used for the destination pixels' alpha value.
Murl.IEnums.BlendFunction GetDstAlphaBlendFunction()
Set the material's blending equations. If alpha blending is enabled (SetBlendMode() with a parameter of IEnums::BLEND_MODE_ALPHA), this method sets the actual equations used to combine the outcome of transforming the source and destination pixels according to the functions specified via SetBlendFunction().
Boolean SetBlendEquation(Murl.IEnums.BlendEquation colorEquation, Murl.IEnums.BlendEquation alphaEquation)
colorEquation | The blending equation used to combine source and destination RGB values. |
alphaEquation | The blending equation used to combine source and destination alpha values. |
Get the material's blending equation for RGB values.
Murl.IEnums.BlendEquation GetColorBlendEquation()
Get the material's blending equation for alpha values.
Murl.IEnums.BlendEquation GetAlphaBlendEquation()
Enable/disable clearing of the render target's color buffer. If color buffer clearing is enabled for a material, the output color buffer gets cleared every time the material is activated (off by default). See SetColorBufferClearValue() for setting the color used for clearing. See also SetDepthBufferClearingEnabled() and SetStencilBufferClearingEnabled().
Boolean SetColorBufferClearingEnabled(Boolean enabled)
enabled | Set to true to enable color buffer clearing. |
Check if clearing of the render target's color buffer is enabled.
Boolean IsColorBufferClearingEnabled()
Enable/disable clearing of the render target's depth buffer. If depth buffer clearing is enabled for a material, the output depth buffer gets cleared every time the material is activated (off by default). See SetDepthBufferClearValue() for setting the depth value used for clearing. See also SetStencilBufferClearingEnabled().
Boolean SetDepthBufferClearingEnabled(Boolean enabled)
enabled | Set to true to enable depth buffer clearing. |
Check if clearing of the render target's depth buffer is enabled.
Boolean IsDepthBufferClearingEnabled()
Enable/disable clearing of the render target's stencil buffer. If stencil buffer clearing is enabled for a material, the output stencil buffer gets cleared every time the material is activated (off by default). See SetStencilBufferClearValue() for setting the stencil value used for clearing. See SetDepthBufferClearingEnabled() and SetColorBufferClearingEnabled().
Boolean SetStencilBufferClearingEnabled(Boolean enabled)
enabled | Set to true to enable stencil buffer clearing. |
Check if clearing of the render target's stencil buffer is enabled.
Boolean IsStencilBufferClearingEnabled()
Set the clear color in effect when color buffer clearing is enabled.
Boolean SetColorBufferClearValue(Murl.Color value)
value | The clear color. |
Get the clear color in effect when color buffer clearing is enabled.
Murl.Color GetColorBufferClearValue()
Set the clear value in effect when depth buffer clearing is enabled.
Boolean SetDepthBufferClearValue(Number value)
value | The clear value. |
Get the clear value in effect when depth buffer clearing is enabled.
Number GetDepthBufferClearValue()
Set the clear value in effect when stencil buffer clearing is enabled.
Boolean SetStencilBufferClearValue(Integer value)
value | The clear value. |
Get the clear value in effect when stencil buffer clearing is enabled.
Integer GetStencilBufferClearValue()
Set the material's object sorting mode. If not specified, the object sort mode is set to IEnums::OBJECT_SORT_MODE_BY_MATERIAL when the material writes to the depth buffer, and to IEnums::OBJECT_SORT_MODE_BY_DEPTH if depth writes are disabled. During rendering a layer, first all drawables are processed that do update the depth buffer (usually opaque geometry) without and depth sorting, and afterwards all other drawables are rendered back-to-front. The actual depth measure (either Z-distance or squared distance) for the latter case is defined per-camera via Graph::ICamera::SetDepthSortMode().
Boolean SetObjectSortMode(Murl.IEnums.ObjectSortMode mode)
mode | The object sorting mode. |
Get the material's object sorting mode.
Murl.IEnums.ObjectSortMode GetObjectSortMode()
Set the material's sorting order relative to other materials. This is useful when doing multi-pass rendering using e.g. a Graph::MultiMaterial. Materials with higher values are rendered later.
Boolean SetSortOrder(Integer order)
order | The sorting order. |
Get the material's sorting order relative to other materials.
Integer GetSortOrder()
Set the variable offset for depth buffer value calculation. This value specifies a variable offset for the generated depth values, before they are written to the depth buffer. See the description of the "factor" parameter at http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPolygonOffset.xml for OpenGL|ES, or the "D3DRS_SLOPESCALEDEPTHBIAS" parameter at http://msdn.microsoft.com/en-us/library/windows/desktop/bb205599(v=vs.85).aspx for DirectX 9. The default offset value is 0.
Boolean SetVariableDepthOffset(Number offset)
offset | The variable depth offset. |
Get the variable offset for depth buffer value calculation.
Number GetVariableDepthOffset()
Set the constant offset for depth buffer value calculation. This value specifies a constant offset for the generated depth values, before they are written to the depth buffer. See the description of the "units" parameter at http://www.khronos.org/opengles/sdk/docs/man/xhtml/glPolygonOffset.xml for OpenGL|ES, or the "D3DRS_DEPTHBIAS" parameter at http://msdn.microsoft.com/en-us/library/windows/desktop/bb205599(v=vs.85).aspx for DirectX 9. The default offset value is 0.
Boolean SetConstantDepthOffset(Number offset)
offset | The constant depth offset. |
Get the constant offset for depth buffer value calculation.
Number GetConstantDepthOffset()
Set the material's camera slot.
Boolean SetCameraSlot(Integer cameraSlot)
cameraSlot | The camera slot. |
Set the material's layer offset.
Boolean SetLayerOffset(Integer layerOffset)
layerOffset | The layer offset. |
Set the material's parameters pass.
Boolean SetParametersStage(Integer parametersStage)
parametersStage | The parameters pass. |
Set the material's texture pass for a given unit.
Boolean SetTextureStage(Integer unit, Integer textureStage)
unit | The texture unit |
textureStage | The texture pass. |
Set the light stage unit used for multi-pass lighting.
Boolean SetLightStageUnit(Integer unit)
unit | The light stage unit, or -1 to disable multi-pass lighting. |
Set if the light should be masked for multi-pass lighting. When multi-pass lighting is performed, this property defines whether rendering should only happen within the light's bounding volume projected on screen. This value only has effect when the light pass unit is set to a defined value (other than -1), otherwise the light is never masked. Setting this value to true can considerably speed up multi-light rendering, as only necessary screen areas are updated.
Boolean SetLightMaskEnabled(Boolean enabled)
enabled | Set to true if the light should be masked. |
Set the material's minimum number of light stages.
Boolean SetMinNumberOfLightStages(Integer minNumStages)
minNumStages | The minimum number of light stages. |
Set the material's maximum number of light stages.
Boolean SetMaxNumberOfLightStages(Integer maxNumStages)
maxNumStages | The maximum number of light stages. |
Get the material's number of detail levels.
Integer GetNumberOfDetailLevels()
Get the material's number of stages for a given detail level.
Integer GetNumberOfStages(Integer detailLevel)
detailLevel | The detail level to query. |
Get the material's camera slot for a given stage.
Integer GetCameraSlot(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's layer offset for a given stage.
Integer GetLayerOffset(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's parameter stage for a given material stage.
Integer GetParametersStage(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's texture stage for a given material stage and texture unit.
Integer GetTextureStage(Integer detailLevel, Integer stage, Integer unit)
detailLevel | The detail level to query. |
stage | The stage to query. |
unit | The texture unit |
Get the light stage unit used for multi-stage lighting for a given material stage.
Integer GetLightStageUnit(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Check if the light is masked for multi-pass lighting.
Boolean IsLightMaskEnabled(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's minimum number of light stages for a given material stage.
Integer GetMinNumberOfLightStages(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's maximum number of light stages for a given material stage.
Integer GetMaxNumberOfLightStages(Integer detailLevel, Integer stage)
detailLevel | The detail level to query. |
stage | The stage to query. |
Get the material's minimum number of light stages for a given material stage.
Integer GetNumberOfLightStages(Integer detailLevel, Integer stage, Integer numLights)
detailLevel | The detail level to query. |
stage | The stage to query. |
numLights | The actual number of currently active lights. |