DxCreateShader: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(8 intermediate revisions by 6 users not shown)
Line 3: Line 3:
This function creates a [[shader]] element that can be used in the dxDraw functions. Successful shader creation is not guaranteed unless the [[shader|Effect File]] contains a fallback technique which will work on every PC in the universe.
This function creates a [[shader]] element that can be used in the dxDraw functions. Successful shader creation is not guaranteed unless the [[shader|Effect File]] contains a fallback technique which will work on every PC in the universe.


=====It is highly recommended that [[dxSetTestMode]] is used when writing and testing scripts using dxCreateShader.=====
<h5>It is highly recommended that [[dxSetTestMode]] is used when writing and testing scripts using dxCreateShader.</h5>


==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
element, string dxCreateShader ( string filepath [, float priority = 0, float maxDistance = 0, bool layered = false, string elementTypes = "world,vehicle,object,other" ] )
element, string dxCreateShader ( string filepath / string raw_data [, float priority = 0, float maxDistance = 0, bool layered = false, string elementTypes = "world,vehicle,object,other" ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{OOP||[[Shader|DxShader]]}}
===Required Arguments===  
===Required Arguments===  
*'''filepath:''' The filepath of the [[shader|shader  Effect File]](.fx) file
*'''filepath / raw_data:''' The filepath of the [[shader|shader  Effect File]] (.fx) file or whole data buffer of the shader file


===Optional Arguments===
===Optional Arguments===
Line 17: Line 17:
*'''priority:''' If more than one shader is matched to a world texture, the shader with the highest priority will be used. If there is more than one shader with the same highest priority, the most recently created shader is used.
*'''priority:''' If more than one shader is matched to a world texture, the shader with the highest priority will be used. If there is more than one shader with the same highest priority, the most recently created shader is used.
*'''maxDistance:''' If non-zero, the shader will be applied to textures nearer than maxDistance only. This can speed up rendering, but (to look good) may require the shader to fade out it's own effect as the texture reaches maxDistance.
*'''maxDistance:''' If non-zero, the shader will be applied to textures nearer than maxDistance only. This can speed up rendering, but (to look good) may require the shader to fade out it's own effect as the texture reaches maxDistance.
 
*'''layered:''' When set to true, the shader will be drawn in a separate render pass. Several layered shaders can be drawn on the same world texture. (To avoid [http://en.wikipedia.org/wiki/Z-fighting Z fighting] artifacts, you may have to add '''DepthBias<nowiki>=</nowiki>-0.0002;''' to the technique pass, but this might cause visual artifacts when applied on vehicles)
{{New feature/item|4.0140|1.3.0|4435|
*'''layered:''' When set to true, the shader will be drawn in a separate render pass. Several layered shaders can be drawn on the same world texture.
*'''elementTypes:''' A comma seperated list of element types to restrict this shader to. Valid element types are:
*'''elementTypes:''' A comma seperated list of element types to restrict this shader to. Valid element types are:
** world - Textures in the GTA world
** world - Textures in the GTA world
Line 27: Line 25:
** other - Element textures which are not peds, vehicles or objects
** other - Element textures which are not peds, vehicles or objects
** all - Everything
** all - Everything
}}


===Returns===
===Returns===
Line 55: Line 52:
)
)
</syntaxhighlight>
</syntaxhighlight>
<br/>
{{New items|5.0156|1.5.6-9.14403|
This example creates basic shader from raw data (without i/o) on resource start:
<syntaxhighlight lang="lua">
local myShader_raw_data = [[
texture tex;
technique replace {
pass P0 {
Texture[0] = tex;
}
}
]]
addEventHandler("onClientResourceStart", resourceRoot, function()
local myShader = dxCreateShader(myShader_raw_data) -- create shader from raw data
if isElement(myShader) then
local myTexture = dxCreateTexture("some_image.png") -- create texture from image file
if isElement(myTexture) then
-- apply image to world texture via shader
dxSetShaderValue(myShader, "tex", myTexture)
engineApplyShaderToWorldTexture(myShader, "shad_ped")
else
outputDebugString("Unable to load texture", 1)
end
else
outputDebugString("Unable to create shader", 1)
end
end)
</syntaxhighlight>
You can pass raw data (shader code) directly into the function (example uses variable ''myShader_raw_data'').
}}


==Changelog==
==Changelog==
{{ChangelogHeader}}
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04435|Added layered and elementTypes arguments}}
{{ChangelogItem|1.3.0-9.04435|Added layered and elementTypes arguments}}
{{ChangelogItem|1.5.6-9.14403|Added option to use raw data instead of a file name}}


==See Also==
==See Also==
{{Drawing_functions}}
{{Drawing_functions}}
[[hu:dxCreateShader]]

Revision as of 12:20, 30 October 2018

This function creates a shader element that can be used in the dxDraw functions. Successful shader creation is not guaranteed unless the Effect File contains a fallback technique which will work on every PC in the universe.

It is highly recommended that dxSetTestMode is used when writing and testing scripts using dxCreateShader.

Syntax

element, string dxCreateShader ( string filepath / string raw_data [, float priority = 0, float maxDistance = 0, bool layered = false, string elementTypes = "world,vehicle,object,other" ] )

OOP Syntax Help! I don't understand this!

Method: DxShader(...)


Required Arguments

  • filepath / raw_data: The filepath of the shader Effect File (.fx) file or whole data buffer of the shader file

Optional Arguments

All the following optional arguments are only relevant when the shader is used with engineApplyShaderToWorldTexture

  • priority: If more than one shader is matched to a world texture, the shader with the highest priority will be used. If there is more than one shader with the same highest priority, the most recently created shader is used.
  • maxDistance: If non-zero, the shader will be applied to textures nearer than maxDistance only. This can speed up rendering, but (to look good) may require the shader to fade out it's own effect as the texture reaches maxDistance.
  • layered: When set to true, the shader will be drawn in a separate render pass. Several layered shaders can be drawn on the same world texture. (To avoid Z fighting artifacts, you may have to add DepthBias=-0.0002; to the technique pass, but this might cause visual artifacts when applied on vehicles)
  • elementTypes: A comma seperated list of element types to restrict this shader to. Valid element types are:
    • world - Textures in the GTA world
    • ped - Player and ped textures
    • vehicle - Vehicles textures
    • object - Objects textures
    • other - Element textures which are not peds, vehicles or objects
    • all - Everything

Returns

  • element: A shader element if successful, false if invalid arguments were passed to the function. You should always check to see if this function has returned false.
  • string: The name of the technique that will be used.

Example

addEventHandler( "onClientRender", root,
    function()
        if myShader then
            dxDrawImage( 100, 350, 300, 350, myShader )
        end
    end
)

-- Use 'toggle' command to switch shader on and off
addCommandHandler( "toggle",
    function()
        if not myShader then
            myShader = dxCreateShader( "fancything.fx" )  -- Create shader
        else        
            destroyElement( myShader )                    -- Destroy shader
            myShader = nil
        end
    end
)


ADDED/UPDATED IN VERSION 1.5.6-9.14403 :

This example creates basic shader from raw data (without i/o) on resource start:

local myShader_raw_data = [[
	texture tex;
	technique replace {
		pass P0 {
			Texture[0] = tex;
		}
	}
]]

addEventHandler("onClientResourceStart", resourceRoot, function()
	local myShader = dxCreateShader(myShader_raw_data) -- create shader from raw data
	if isElement(myShader) then
		local myTexture = dxCreateTexture("some_image.png") -- create texture from image file
		if isElement(myTexture) then
			-- apply image to world texture via shader
			dxSetShaderValue(myShader, "tex", myTexture)
			engineApplyShaderToWorldTexture(myShader, "shad_ped")
		else
			outputDebugString("Unable to load texture", 1)
		end
	else
		outputDebugString("Unable to create shader", 1)
	end
end)

You can pass raw data (shader code) directly into the function (example uses variable myShader_raw_data).

Changelog

Version Description
1.3.0-9.04435 Added layered and elementTypes arguments
1.5.6-9.14403 Added option to use raw data instead of a file name

See Also