Script fragment commands

AcquireTarget

Acquires a render target from the cache that is of the given size and format, and adds it to the local variables. This is similar to acquiring an MRenderTarget.

XML Syntax:

<acquireTarget 
    name="beauty" 
    format="EFORMAT_R32G32B32A32_FLOAT"
    size="@finalDesc.Size" 
    relSize="1.0,1.0"
    msaa="@finalDesc.NumMSAASamples"
/>

Attributes

• name - the name the new target will be given in the current context. After being acquired, targets are always referred to by name; therefore, local target names should be kept unique within the context of a frame. This is a required attribute.

• format – the name of the raster format that should be used when creating the target. The format specifies the number of channels in the target, and the size and ordering of channels.

  See MHWRender::MRasterFormat for available values; for example, EFORMAT_<format> corresponds to k<format>.

  Note that the format parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, format="@final” will find a parameter on the current fragment called “final”, ensure that “final” is a texture or target parameter, and then set the new target’s format to be the same as that of the texture or target in “final”. Format is a required attribute.

• size – the size of the target to be created, represented as a list of integers, separated by commas; for example, “16,16”. Accepted sizes are hardware dependent. Note that the size parameter, like the format parameter, accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, size ="@final” will find a parameter on the current fragment called “final”, ensure that “final” is a texture or target parameter, and then set the new target’s size to be the same as that of the texture or target in “final”. size is a required attribute.

  NOTE:

  final denotes the buffer that results should be drawn into at the end of the operation.

  To create a new offscreen buffer, you may want to obtain the properties from finalDesc, which is a description of final.

• relSize – relative size is an optional attribute that multiples the values given in the size attribute to obtain the final size used for creating the target. It denotes the width (x) and height (y) scale, and is represented as a list of 2 floating point numbers, separated by commas; for example, “0.5,0.5”. The relative size attribute does not accept the @ notation, but if the size parameter is indirect, the indirect size will be scaled by the relative size.
• msaa - sample count for multi-sample anti-aliasing

SetTarget

Sets the given target to the given target slot on the device. The target should have been previously acquired or provided by a parameter prior to its use in setTarget.

XML Syntax:

<setTarget
    index="0" 
    value="beauty"
/>

Attributes

• index - the index of the target being set. 4 simultaneous targets are supported, named “0” through “3”. index is a required attribute, and must be an integer from 0 to 3.

• value - the name of the target to be set to the device. This target should be in the local cache or provided by a referenced parameter. Note that the value parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, value ="@final” will find a parameter on the current fragment called “final”, ensure that “final” is a target parameter, and then set the target held by “final” to the device’s target at the given index. Value is a required attribute. The empty string “” is treated as NULL and de-references the target. This is done so that ReleaseTargets can function correctly.

SetDepthStencil

Sets the given target to the depth stencil buffer for the device. The target should have been previously acquired or provided by a parameter prior to its use in setDepthStencil.

XML Syntax:

<setDepthStencil 
    value="myDepthStencil"
/>

Attributes:

• value - the name of the target to be set to the device’s depth stencil buffer. This target should be in the local cache or provided by a referenced parameter, and must have been created with a depth format. Note that the value parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, value ="@depthIn” will find a parameter on the current fragment called “depthIn”, ensure that “depthIn” is a depth target parameter, and then set the target held by “depthIn” to the device. Value is a required attribute. The empty string “” is treated as NULL.

ReleaseTargets

This command releases one or more targets from the local cache back to the target cache and removes the associated parameters from the local cache.

XML Syntax:

<releaseTargets 
    value="beauty,temp0"
/>

Attributes:

• value - a list of targets to be released, separated by commas. The empty string ”” is taken to mean “all targets”. Also, a wildcard operator * will match string remainders; so, for example, if an effect has acquired many targets, “tone0” thru “tone10”, they may be released as a group by using value="tone*".

ReleaseAll

This command releases all of the local parameters back to the caches.

XML Syntax:

<releaseAll/>

Clear

This command clears a combination of the color buffer, the depth buffer and the stencil buffer to the given values.

XML Syntax:

<clear 
    color="0,0,0,0" 
    depth="1.0" 
    stencil="0"
/>

Attributes:

• color - a list of float values representing the clear color, separated by commas; for example: “0.63,0.32,0.77,0.0”. color is an optional attribute, and if it is not given or if it is set to an empty string ””, it is taken to mean “do not clear the color component”. Only float4 RGBA colors are accepted.

• depth - a single float value representing the depth clear value; for example: “1.00”. depth is an optional attribute, and if it is not given or if it is set to an empty string ””, it is taken to mean “do not clear the z component”.

• stencil - a single integer value representing the clear value for the stencil buffer; for example, “128”. For stencil buffers created with D24S8, the most common format, accepted values are between 0 and 255. stencil is an optional attribute, if it is not given or if it is set to an empty string ””, it is taken to mean “do not clear the stencil component”.

SetCamera

This command sets the current drawing camera to the given value.

XML Syntax:

<setCamera 
    value="camera0" 
    index="0" 
/>

Attributes:

• value – the name of the camera to make active. Must either exist as a local parameter or be provided indirectly with a valid value. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@cameraIn” will find a parameter on the current fragment called “cameraIn”, ensure that “cameraIn” is a camera parameter, and then set the camera held by “cameraIn” to the context. Note also that the special value “light” is recognized in conjunction with the optional index attribute to specify the camera associated with a light. For example, <setCamera value="light" index="2" /> sets the current camera to the camera associated with light 2. value is a required parameter.
• index - an optional integer parameter that indicates which light to use as a source for the camera. Only meaningful when value=”light”.

SetViewport

This command sets the current viewport to the given drawing region. All drawing, including quad draws and clears, are restricted to the active viewport.

XML Syntax:

<setViewport
    value="0.0,0.0, 0.5,0.5"
/>

Attributes:

• value – a list of 4 float values, separated by commas. The target area is represented in normalized coordinates, 0..1, 0…1. The first two values represent the position of the viewport in this normalized space, and the latter two values represent the size of the viewport, also in normalized space, where a size of 1.0 means the entire target in that dimension.

SetScissorRect

This command sets the current scissor rectangle to the given region. This command has no effect unless the render state is set to enable the scissor rectangle. If the rectangle is enabled, then drawing, including quad draws, are restricted to the scissor rectangle.

XML Syntax:

<setScissorRect
    value="0.0,0.0, 0.5,0.5"
/>

Attributes:

• value – a list of 4 float values, separated by commas. The scissor rectangle is represented in normalized coordinates, 0..1, 0…1. The first two values represent the position of the scissor rectangle in this normalized space, and the latter two values represent the size of the scissor rectangle, also in normalized space, where a size of 1.0 means the entire target in that dimension. Values less than 0 and greater than 1 are accepted. If the scissor rectangle is enabled and empty, or not on the screen, then the Render command doesn’t run the renderer or draw a screen quad, since no pixel will be drawn.

SetEffect

This command sets the override effect to the given value. All drawing, including quad draws, use the override effect until it is reset.

An effect can only be set once, but can be reused several times.

XML Syntax:

<setEffect  
    name="DownSampleEffect"
    path="downSample"
    technique="Main"
    macrolist=""  
/>

Attributes:

• name – name of the effect that is being set. Required. The name can be the same as or different from the effect path. If this value is "", the effect path is used as the name of the effect. If the effect path is also "", the current effect is removed.

• path – the path for the effect file. Optional. If this value is not empty, the effect will be created with the file, and if the specified effect name is already used by another effect, that effect will be released. If this value is empty, the effect with the specified effect name is reused, and if the effect doesn’t exist, this command will fail.

  It is not necessary to provide a file extension, as Maya will look up the appropriate extension based on the device being used; for example, .fx for DX11, .ogsfx for Core Profile and .cgfx for non-core profile OpenGL.

  The override effect is terminated by setting the value to "", the empty string.

• technique – the name of the active technique. Optional. If the effect path is empty, this parameter will be ignored. If the technique is not found in the effect, the command will fail.

• macrolist – a string of macro names and definitions, separated by commas. Optional. Each definition follows the macro name, such as ” SHADOWPARAM, 0.1, SHADOWCOLOR, 0x2310, …”. An empty definition is specified with two commas, such as ”PERSPECTIVE_ENABLED,,…”. If the effect path is empty, this parameter will be ignored.

SetEffectParameter

This command sets the value of a parameter on the current effect to the given value. All subsequent uses of this effect will have this value.

XML Syntax:

<setEffectParameter  
    effect="downSample"  
    name="scale"  
    value="0.0,1.0" 
/>

Attributes:

• effect – name of the effect that holds the parameter that you want to set. effect is a required attribute.

• name – name of the parameter that is being set. name is a required attribute.

• value – value to set the parameter to. Exact syntax is dependent on the parameter type; for example, the above example will match a float2, but not a target. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@cameraIn” will find a parameter on the current fragment called “cameraIn”, ensure that “cameraIn” is of the same type as the parameter referred to by name, and then set the parameter to the value of cameraIn.

SetTexture

This command sets the value of the given texture slot on the device to the given sampler state and texture.

XML Syntax:

<SetTexture 
    effect="Main" 
    name="gDistanceTex" 
    value="PointClamp" 
    texture="@DistanceMap" 
/>

Attributes:

• effect – name of the effect that holds the texture parameter that you want to set. Required.
• name – name of the texture parameter that is being set. name is a required attribute, and must be of target or texture type.
• value – name of the requested sampler state; for example: “PointClamp”. Only states currently in the cache or the factory are available . Note that this parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@samplerIn” will find a parameter on the current fragment called “samplerIn”, ensure that it is a sampler state parameter, and then set the samplerIn value as the value to be used when this texture is activated.

• texture – name of the texture to set into the slot/parameter. Only states currently in the cache or the factory are available. Note that the texture parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, texture ="@textureIn” will find a parameter on the current fragment called “textureIn”, ensure that “textureIn” is a texture parameter, and then set the textureIn’s value as the value to be used when this texture is activated.

SetState

This command sets a given state block to the device. The complete device state may be set (the “RenderState”); or, each of its three components, the blend state, rasterizer state and depth stencil state may be set separately.

XML Syntax:

<setState
    name="DepthStencilState"  
    value="myDepthStencilState" 
/>

• name – the state category that you want to set. Required. Valid name values are "RenderState", "BlendState", "RasterizerState",or "DepthStencilState". RenderState sets all the other states.
• value – name of the state to set the device to. A state object will be created for you automatically if it hasn't been declared already. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@stateIn” will find a parameter on the current fragment called “stateIn”, ensure that it is of the same type as the parameter name, and then set stateIn's value into the given state category. value is a required parameter, but its value may be the empty string, “”.

SetRenderParameter

This command sets a parameter on the given renderer. The parameter may hold an auxiliary world, or specify an object filter used to accept all objects with certain item flags set. Examples are “visible”, and “castsShadow”.

XML Syntax:

<setRenderParameter  
    renderer="opaqueRend"  
    name="filter" 
    value="visible" 
/>

Attributes:

• renderer – name of the renderer on which to set parameters.
• name – name of the parameter on the renderer.
• value – value to set to the given parameter. May be a simple value: “0.0”, “true”, or “21”, or the name of another parameter (usually in the local cache); for example, “transpWorld” that holds the object to set to the renderer.

Declare

This command declares a new parameter of the given type and adds it to the local cache. It optionally sets the value of the parameter to the given value. The parameter may subsequently be set by the setParameter command.

XML Syntax:

<declare  
    name="light0Shadow" 
    type="target" 
    value="shadowBuf0" 
/>

Attributes:

• name - the name of the parameter to declare. If this parameter is already in the local cache and is of the correct type, no action is taken. If the parameter is in the local cache, but of the wrong type, an error is generated due to the name conflict. name is a required attribute, and may not be set to the empty string, “”.
• type – type of the parameter being created. Accepts int, float, int4, float4, target, texture, world, bool, and string.
• value – value to which the parameter is initially set. Exact syntax is dependent on the parameter type; for example, the above example will match a target, but not a float2. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@cameraIn” will find a parameter on the current fragment called “cameraIn”, ensure that “cameraIn” is of the same type as the parameter name, and then set parameter name's value to cameraIn’s value.

SetParameter

This command sets a given parameter to the given value, which may be another parameter.

XML Syntax:

<setParameter  
    name="@output"  
    value="1.0,0.25" 
/>

Attributes:

• name - the name of the parameter. This parameter should be in the local cache or provided by reference. Note that the name parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, name ="@output” will find a parameter on the current fragment called “output”, and set name to the given value. name is a required attribute.
• value – value to set the parameter to. Exact syntax is dependent on the parameter type. In the example above, value will match a float2, but not a target. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@cameraIn” will find a parameter on the current fragment called “cameraIn”, ensure that “cameraIn” is of the same type as the parameter name, and then set parameter name's value to cameraIn’s value.

If

This command tests a given parameter for NULL or false, and if it is NULL or false, all statements are skipped until “else” or “endIf”. The statement can be nested.

XML Syntax:

<if  
    value="@depthStencil"
/>

Attributes

• value - the name of the parameter to test. This parameter should be in the local cache or provided by reference. The parameter must be either of the pointer type (world, texture, target, state, and so forth), or of the boolean type. Note that the value parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, value ="@output” will find a parameter on the current fragment called “output”, and set the parameter value to the given value. name is a required attribute.

IfNot

This command tests a given parameter for NULL or false and if it is NULL or false, all statements are executed until else or endIf. If true or not NULL, no statements are executed until an else or endif is encountered. The statement can be nested.

XML Syntax:

<ifNot  
    value="@depthStencil" 
/>

Attributes

• value - the name of the parameter to test. This parameter should be in the local cache or provided by reference. The parameter must be either of the pointer type (world, texture, target, state, and so forth), or of the boolean type. Note that the value parameter accepts the @ notation. The @ notation gets the value from a parameter of the fragment referred to by the @. For example, value ="@output” will find a parameter on the current fragment called “output”, and test the parameter value for NULL or false. Value is a required attribute, and should not be set to the empty string, “”.

Else

This command ends the main section and begins the else section of an if or ifNot command. It reverses the state of statement inclusion produced by if or ifNot. If an if statement evaluates to true, statements are executed until an endIf or an else is encountered. If an else is encountered, no subsequent statements are executed until an endIf is encountered. The conditional statement can be nested. Must be contained between either an if / endIf pair, or between an ifNot / endIf pair.

XML Syntax:

<else/>

Attributes

• None

EndIf

This command ends an if or ifNot command and restores normal, unconditional processing. All statements after the endIf are executed normally. The conditional statement can be nested. This command must match the if command one to one, and must appear after the matching if command.

XML Syntax:

<endIf/>

Attributes

• None

Call

This command calls a user supplied callback object. If the callback object is not in the local cache, it is created for you and added to the local parameters, then called. The callback takes 2 optional arguments.

XML Syntax:

<call 
    name="myCallback " 
    arg0="doThisThing" arg1="0.125"
/>

Attributes

• name - the name of the callback object. If the callback object is not in the local cache, it is created for you and added to the local parameters, then executed. name is a required attribute and may not be an empty string.
• arg0, arg1, arg2 - the first, second, and third arguments to the callback function. Parsed to the correct type by the callback object, these values are always provided as a string so that many types may be specified. Note that the arg parameters accept the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, arg0 ="@filterIn” will find a parameter on the current fragment called “filterIn”, and the callback would use that value in its computations. These are optional parameters and may be set to the empty string, “”.

Render

This command renders all the objects in the list named in the value attribute. Valid values include "opaqueList", which is the list of opaque objects that you want to draw, and “quad”, that draws a single full screen quad. Render does not set targets, cameras, state, override effects, or other rendering related values; it merely draws the geometry with the state currently set in the interpreter. Both quad draws and scene draws are restricted to the area of the viewport.

XML Syntax:

<render 
    name="@opaqueList" 
/>

Attributes:

• name - the objects that should be rendered. Note that the name parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. name is a required attribute, and may not be set to the empty string, “”.

SetStateCommand

This command will use a state setter class to manage the render state or sampler state of the virtual device. This command includes the setting of the state changes, the committing of the state changes, and the restoring to old state.

XML Syntax:

<SetStateCommand 
    commandName="SetStateParameter" 
    name="localStateSetter_fsShadow"
    parameter="SetBlendEnable" 
    value="true"
    index="0" 
/>

• commandName - a string indicating the name of the command. Required.

  Currently only four types of commands are allowed: “SetStateParameter”, “SetRenderState”, “CommitNewState” and “RestorePreviousState”.

• name - a string indicating the name of the state setter. Required. The state setter must have been already declared in a previous script.
• parameter - a string indicating the name of the state or state parameter. The “SetStateParameter” and “SetRenderState” commands require this field. Note that this parameter accepts the @ notation. The @ notation gets the actual string from a string parameter of the fragment referred to by the @. For example, parameter="@ambientState” will find a parameter on the current fragment called “ambientState”, and the StateSetter will use the string in the parameter as the state name.
• value - a string indicating the value of the state change. The type of the value varies depending on the parameter. For example, if the parameter is “DepthBias”, the value will be a float. Note that the value parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, value ="@clearColor” will find a parameter on the current fragment called “clearColor”, and the state setter will use the value in the parameter as the state value.
• index - a string indicating the index of the state that the state setter will change, or the stencil operation type that the state setter will change. If the parameter is a state parameter that requires an index, then this is an integer representing the index. If the parameter is “StencilFrontFace” or “StencilBackFace”, then this is the stencil operation type. Note that the index parameter accepts the @ notation. The @ notation gets the actual value from a parameter of the fragment referred to by the @. For example, index="@blendIndex” will find a parameter on the current fragment called “blendIndex”, and the state setter will use the value in the parameter as the state index.