EngineApplyShaderToWorldTexture: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(Replace to root.)
 
(17 intermediate revisions by 6 users not shown)
Line 2: Line 2:
__NOTOC__
__NOTOC__
This function applies a [[shader]] to one or more world textures.
This function applies a [[shader]] to one or more world textures.
{{Note|The resource [http://wiki.multitheftauto.com/wiki/Shader_examples#Texture_names shader_tex_names] can help in finding the names of world textures.}}
{{Tip|
{{Note|When replacing the texture for a ped using the CJ skin, set '''textureName''' to "CJ"}}
* The resource [[Shader_examples#Texture_names|shader_tex_names]] can help in finding the names of world textures.
{{Note|The shader inherits the render states of the original when it is drawn, so texture stage 0 will already be set to the original texture.}}
* When replacing the texture for a ped using the CJ skin, set '''textureName''' to "CJ"
 
* The shader inherits the render states of the original when it is drawn, so texture stage 0 will already be set to the original texture.
{{New feature/item|4.0150|1.3.1|5246|
* When using with a 'ped', ensure you have set 'ped' or 'all' in the elementTypes when calling [[dxCreateShader]]
* CJ body parts textures can be replaced by using: "cj_ped_head", "cj_ped_torso", "cj_ped_legs", "cj_ped_feet" and maybe some other things like "cj_ped_necklace", "cj_ped_watch" etc. Latest version of [http://wiki.multitheftauto.com/wiki/Shader_examples#Texture_names shader_tex_names] will show what is being used.
* CJ body parts textures can be replaced by using: "cj_ped_head", "cj_ped_hat", "cj_ped_torso", "cj_ped_legs", "cj_ped_feet", "cj_ped_glasses", "cj_ped_necklace", "cj_ped_watch" and "cj_ped_extra1". Latest version of [http://wiki.multitheftauto.com/wiki/Shader_examples#Texture_names shader_tex_names] will show what is being used.
}}
}}
==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool engineApplyShaderToWorldTexture ( element shader, string textureName [, element targetElement = nil, bool appendLayers = true ] )
bool engineApplyShaderToWorldTexture ( element shader, string textureName [, element targetElement = nil, bool appendLayers = true ] )
</syntaxhighlight>  
</syntaxhighlight>
{{New feature/item|3.0141|1.4.0|6987|{{OOP||[[shader]]:applyToWorldTexture}}}}


===Required Arguments===  
===Required Arguments===  
Line 19: Line 20:


===Optional Arguments===  
===Optional Arguments===  
{{New feature/item|4.0140|1.3.0|4140|
{{New feature/item|3.0130|1.3.0|4140|
*'''targetElement:''' The element to restrict applying the shader to. If this is not set the shader will be applied to everything using the texture name. Valid element types for targetElement are [[vehicle|vehicles]] and [[Object|objects]].
*'''targetElement:''' The element to restrict applying the shader to. If this is not set the shader will be applied to everything using the texture name. Valid element types for targetElement are [[vehicle|vehicles]], [[Object|objects]] and [[Ped|peds]].
{{New feature/item|4.0150|1.3.1|4939|
:'''targetElement''' can be a [[ped|ped]].
}}
}}
}}
*'''appendLayers:''' allows two or more layered shaders to be applied in the same texture. You may want to modify the ''DepthBias'' in the technique pass to avoid Z-fighting artifacts when using this.
*'''appendLayers:''' --TODO
 
===Returns===
===Returns===
Returns ''true'' if the shader was successfully applied, ''false'' otherwise.
Returns ''true'' if the shader was successfully applied, ''false'' otherwise.


==Example==
==Example==
This example will replace the texture of a group of common explosions (grenades, rockets, etc) with a custom explosion effect
<syntaxhighlight lang="lua">
theTechnique = dxCreateShader("shader.fx")
explosionTexture = dxCreateTexture( "tex/Explosion.png")
function replaceEffect()
engineApplyShaderToWorldTexture(theTechnique, "fireball6")
dxSetShaderValue (theTechnique, "gTexture", explosionTexture)
end
addEventHandler("onClientResourceStart", resourceRoot, replaceEffect)
</syntaxhighlight>
This example will apply a shader to the "des_logwall" world texture (which is used by the house near the 'play' gamemode spawn point)
This example will apply a shader to the "des_logwall" world texture (which is used by the house near the 'play' gamemode spawn point)
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
myShader = dxCreateShader( "hello.fx" )
theTechnique = dxCreateShader("shader.fx")
engineApplyShaderToWorldTexture( myShader, "des_logwall" )
engineApplyShaderToWorldTexture(theTechnique, "des_logwall")
</syntaxhighlight>
</syntaxhighlight>


This untested example will apply a shader to the current vehicle of the local player
This example will apply a shader to the current vehicle of the local player
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
myShader = dxCreateShader( "hello.fx" )
theTechnique = dxCreateShader( "shader.fx" )
 
function applyShader(thePlayer, seat)
local theVehicle = source
 
if seat == 0 and thePlayer == localPlayer then
engineApplyShaderToWorldTexture(theTechnique, "vehiclegrunge256", theVehicle)
engineApplyShaderToWorldTexture(theTechnique, "?emap*", theVehicle)
end
end
addEventHandler("onClientVehicleEnter", root, applyShader)


addEventHandler("onClientVehicleEnter", root,
function removeShader(thePlayer, seat)
    function(thePlayer, seat)
local theVehicle = source
        local theVehicle = source
        if seat == 0 and thePlayer == localPlayer then
            engineApplyShaderToWorldTexture( myShader, "vehiclegrunge256", theVehicle )
            engineApplyShaderToWorldTexture( myShader, "?emap*", theVehicle )
        end
    end
)


addEventHandler("onClientVehicleExit", root,
if seat == 0 and thePlayer == localPlayer then
    function(thePlayer, seat)
        engineRemoveShaderFromWorldTexture(theTechnique, "vehiclegrunge256", theVehicle)
        local theVehicle = source
        engineRemoveShaderFromWorldTexture(theTechnique, "?emap*", theVehicle)
        if seat == 0 and thePlayer == localPlayer then
end
            engineRemoveShaderFromWorldTexture( myShader, "vehiclegrunge256", theVehicle )
end
            engineRemoveShaderFromWorldTexture( myShader, "?emap*", theVehicle )
addEventHandler("onClientVehicleExit", root, removeShader)
        end
    end
)
</syntaxhighlight>
</syntaxhighlight>


==Changelog==
 
{{ChangelogHeader}}
Basic texture replacement shader example (compatible with all script examples on this page):
{{ChangelogItem|1.3.0-9.04140|Added targetElement argument}}
<syntaxhighlight lang="fx">
{{ChangelogItem|1.3.0-9.04418|Added peds to allowed element types (for pixel shaders only)}}
texture gTexture;
{{ChangelogItem|1.3.1-9.04939|Added peds to allowed element types (full support)}}
 
technique TexReplace
{
    pass P0
    {
        Texture[0] = gTexture;
    }
}
</syntaxhighlight>
* Save the above code as [shadername]'''.fx'''


==See Also==
==See Also==
{{Engine_functions}}
{{Engine_functions}}
{{Drawing_functions}}
{{Drawing_functions}}

Latest revision as of 23:50, 1 November 2022

This function applies a shader to one or more world textures.

[[{{{image}}}|link=|]] Tip:
  • The resource shader_tex_names can help in finding the names of world textures.
  • When replacing the texture for a ped using the CJ skin, set textureName to "CJ"
  • The shader inherits the render states of the original when it is drawn, so texture stage 0 will already be set to the original texture.
  • When using with a 'ped', ensure you have set 'ped' or 'all' in the elementTypes when calling dxCreateShader
  • CJ body parts textures can be replaced by using: "cj_ped_head", "cj_ped_hat", "cj_ped_torso", "cj_ped_legs", "cj_ped_feet", "cj_ped_glasses", "cj_ped_necklace", "cj_ped_watch" and "cj_ped_extra1". Latest version of shader_tex_names will show what is being used.

Syntax

bool engineApplyShaderToWorldTexture ( element shader, string textureName [, element targetElement = nil, bool appendLayers = true ] )

OOP Syntax Help! I don't understand this!

Method: shader:applyToWorldTexture(...)

Required Arguments

  • shader: The shader which is to be applied
  • textureName: The name of the world texture to apply the shader to. Wildcard matching e.g. "ro?ds*" can be used to apply to more than one texture at a time.

Optional Arguments

  • targetElement: The element to restrict applying the shader to. If this is not set the shader will be applied to everything using the texture name. Valid element types for targetElement are vehicles, objects and peds.
  • appendLayers: allows two or more layered shaders to be applied in the same texture. You may want to modify the DepthBias in the technique pass to avoid Z-fighting artifacts when using this.

Returns

Returns true if the shader was successfully applied, false otherwise.

Example

This example will replace the texture of a group of common explosions (grenades, rockets, etc) with a custom explosion effect 

theTechnique = dxCreateShader("shader.fx")
explosionTexture = dxCreateTexture( "tex/Explosion.png")

function replaceEffect()
	engineApplyShaderToWorldTexture(theTechnique, "fireball6")
	dxSetShaderValue (theTechnique, "gTexture", explosionTexture)
end
addEventHandler("onClientResourceStart", resourceRoot, replaceEffect)

This example will apply a shader to the "des_logwall" world texture (which is used by the house near the 'play' gamemode spawn point) 

theTechnique = dxCreateShader("shader.fx")
engineApplyShaderToWorldTexture(theTechnique, "des_logwall")

This example will apply a shader to the current vehicle of the local player 

theTechnique = dxCreateShader( "shader.fx" )

function applyShader(thePlayer, seat)
local theVehicle = source

	if seat == 0 and thePlayer == localPlayer then
		engineApplyShaderToWorldTexture(theTechnique, "vehiclegrunge256", theVehicle)
		engineApplyShaderToWorldTexture(theTechnique, "?emap*", theVehicle)
	end
end
addEventHandler("onClientVehicleEnter", root, applyShader)

function removeShader(thePlayer, seat)
local theVehicle = source

	if seat == 0 and thePlayer == localPlayer then
        	engineRemoveShaderFromWorldTexture(theTechnique, "vehiclegrunge256", theVehicle)
        	engineRemoveShaderFromWorldTexture(theTechnique, "?emap*", theVehicle)
	end
end
addEventHandler("onClientVehicleExit", root, removeShader)


Basic texture replacement shader example (compatible with all script examples on this page): 

texture gTexture;

technique TexReplace
{
    pass P0
    {
        Texture[0] = gTexture;
    }
}
  • Save the above code as [shadername].fx

See Also



Retrieved from "https://wiki.multitheftauto.com/wiki/EngineApplyShaderToWorldTexture?oldid=75637"