DxCreateTexture: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
(Add tip to pre-convert textures using dxtex texconv)
 
(34 intermediate revisions by 12 users not shown)
Line 2: Line 2:
__NOTOC__
__NOTOC__
This function creates a [[texture]] element that can be used in the dxDraw functions.
This function creates a [[texture]] element that can be used in the dxDraw functions.
{{Important Note|This function uses significant process RAM, make sure you don't load a lot of textures, because you'll run out of memory and crash MTA on your gaming PC beyond the technical limit of 3.5 GB (weak PC users much earlier). Besides that, don't make the common mistake of causing a memory leak by not destroying textures (causing dxTextures to pile up) when they should no longer display per your script, which causes FPS lag and crashes all over MTA due to so many scripters missing it}}
{{Note|The times shown at the right of the page are only the time needed to add the thing to the draw queue, its not the actual time it takes to draw them.}}
{{Tip|It is recommended to pre-convert textures to whatever format you want to load them as. ARGB should be PNG, all other formats are self explanatory. By doing this you can load textures on the fly without any hickups (Note: There might still be some if the user has a slow HHD). See [https://github.com/microsoft/DirectXTex/releases DirectXTex texconv tool]. }}
[[Image:Screenshot_27.png|frame|A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = true][textureEdge = "wrap"]]]
[[Image:DxCreateTexture_mipmaps_false.png |frame|A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = false][textureEdge = "wrap"]]]


It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility [http://nightly.mtasa.com/files/shaders/DxTex.zip DxTex] can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.
==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
element dxCreateTexture ( string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge ] )
element dxCreateTexture ( string pixels / string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
element dxCreateTexture ( string pixels [, string textureFormat = "argb", bool mipmaps = true, string textureEdge ] )
</syntaxhighlight>
element dxCreateTexture ( int width, int height [, string textureFormat, string textureEdge, string textureType, int depth = 1 ] )
<syntaxhighlight lang="lua">
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{OOP||[[Texture|DxTexture]]}}
===Required Arguments===
===Required Arguments===
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
*'''filepath:''' The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
Line 16: Line 22:
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
*'''pixels:''' [[Texture_pixels|Pixels]] containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)
or
or
*'''width:''' Desired width (Must be a power of two. e.g. 128, 256)
*'''width:''' Desired width, preferably power of two (16, 32, 64 etc.), maximum is 16384
*'''height :''' Desired height (Must be a power of two. e.g. 128, 256)
*'''height :''' Desired height, preferably power of two (16, 32, 64 etc.), maximum is 16384


===Optional Arguments===
===Optional Arguments===
*'''textureFormat :''' Desired texture format
{{OptionalArg}}
**''''argb'''' : ARGB uncompressed 32 bit color (default)
*'''textureFormat :''' A string representing the desired texture format, which can be one of:
**''''dxt1'''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and can speed up drawing. Quality not as good as ARGB and does not support alpha blending.
**'''"argb"''' : ARGB uncompressed 32 bit color (default).
**''''dxt3'''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and can speed up drawing. Quality slightly better than DXT1 and supports smooth alpha blending.
**'''"dxt1"''' : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and '''can speed up drawing'''. Quality not as good as ARGB. '''It supports alpha blending, but it can only be on or off, that is: either 0 or 255.'''
**''''dxt5'''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and can speed up drawing. Quality slightly better than DXT1 and supports crisp alpha blending.
**'''"dxt3"''' : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and '''can speed up drawing'''. Quality slightly better than DXT1 and supports crisp alpha blending.
**'''"dxt5"''' : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and '''can speed up drawing'''. Quality slightly better than DXT1 and supports smooth alpha blending.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
*'''mipmaps :''' True to create a mip-map chain so the texture looks good when drawn at various sizes.
{{New feature/item|4.0130|1.3|4035|
*'''textureEdge :''' A string representing the desired texture edge handling, which can be one of:
*'''textureEdge :''' Desired texture edge handling which can be one of:
**'''"wrap"''' : Wrap the texture at the edges (default)
**''''wrap'''' : Wrap the texture at the edges (default)
**'''"clamp"''' : Clamp the texture at the edges. This may help avoid edge artifacts.
**''''clamp'''' : Clamp the texture at the edges. This may help avoid edge artifacts.
**'''"mirror"''' : Mirror the texture at the edges.
*'''textureType :''' Desired texture type which can be one of:
*'''textureType :''' A string representing the desired texture type, which can be one of:
**''''2d'''' : Standard texture (default)
**'''"2d"''' : Standard texture (default)
**''''3d'''' : Volume texture
**'''"3d"''' : Volume texture
**''''cube'''' : Cube map
**'''"cube"''' : Cube map
*'''depth:''' Desired number of slices when creating a volume texture
*'''depth:''' Desired number of slices when creating a volume texture
}}
 
==Returns==
==Returns==
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.
Returns a [[texture]] if successful, ''false'' if invalid arguments were passed to the function.
Line 69: Line 76:
==See Also==
==See Also==
{{Drawing_functions}}
{{Drawing_functions}}
[[hu:dxCreateTexture]]

Latest revision as of 00:00, 4 February 2022

This function creates a texture element that can be used in the dxDraw functions.

[[{{{image}}}|link=|]] Important Note: This function uses significant process RAM, make sure you don't load a lot of textures, because you'll run out of memory and crash MTA on your gaming PC beyond the technical limit of 3.5 GB (weak PC users much earlier). Besides that, don't make the common mistake of causing a memory leak by not destroying textures (causing dxTextures to pile up) when they should no longer display per your script, which causes FPS lag and crashes all over MTA due to so many scripters missing it
[[{{{image}}}|link=|]] Note: The times shown at the right of the page are only the time needed to add the thing to the draw queue, its not the actual time it takes to draw them.
[[{{{image}}}|link=|]] Tip: It is recommended to pre-convert textures to whatever format you want to load them as. ARGB should be PNG, all other formats are self explanatory. By doing this you can load textures on the fly without any hickups (Note: There might still be some if the user has a slow HHD). See DirectXTex texconv tool.
A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = true][textureEdge = "wrap"]
A speedtest showing the performance of a texture created with various settings of textureFormat.[Mipmaps = false][textureEdge = "wrap"]

It is possible to use dxCreateTexture to load cubemaps and volume textures, but these will only be useable as inputs for a shader. The Microsoft utility DxTex can view and change cubemaps and volume textures. DxTex can also convert standard textures into DXT1/3/5 compressed .dds which should reduce file sizes.

Syntax

element dxCreateTexture ( string pixels / string filepath [, string textureFormat = "argb", bool mipmaps = true, string textureEdge = "wrap" ] )
element dxCreateTexture ( int width, int height [, string textureFormat = "argb", string textureEdge = "wrap", string textureType = "2d", int depth = 1 ] )

OOP Syntax Help! I don't understand this!

Method: DxTexture(...)


Required Arguments

  • filepath: The filepath of the image. (.bmp, .dds, .jpg, .png, and .tga images are supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.

or

  • pixels: Pixels containing image data. ('plain', 'jpeg' or 'png' pixels can be used here)

or

  • width: Desired width, preferably power of two (16, 32, 64 etc.), maximum is 16384
  • height : Desired height, preferably power of two (16, 32, 64 etc.), maximum is 16384

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • textureFormat : A string representing the desired texture format, which can be one of:
    • "argb" : ARGB uncompressed 32 bit color (default).
    • "dxt1" : DXT1 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT1 .dds). Uses 8 times less video memory than ARGB and can speed up drawing. Quality not as good as ARGB. It supports alpha blending, but it can only be on or off, that is: either 0 or 255.
    • "dxt3" : DXT3 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT3 .dds). Uses 4 times less video memory than ARGB and can speed up drawing. Quality slightly better than DXT1 and supports crisp alpha blending.
    • "dxt5" : DXT5 compressed - Can take a fraction of a second longer to load (unless the file is already a DXT5 .dds). Uses 4 times less video memory than ARGB and can speed up drawing. Quality slightly better than DXT1 and supports smooth alpha blending.
  • mipmaps : True to create a mip-map chain so the texture looks good when drawn at various sizes.
  • textureEdge : A string representing the desired texture edge handling, which can be one of:
    • "wrap" : Wrap the texture at the edges (default)
    • "clamp" : Clamp the texture at the edges. This may help avoid edge artifacts.
    • "mirror" : Mirror the texture at the edges.
  • textureType : A string representing the desired texture type, which can be one of:
    • "2d" : Standard texture (default)
    • "3d" : Volume texture
    • "cube" : Cube map
  • depth: Desired number of slices when creating a volume texture

Returns

Returns a texture if successful, false if invalid arguments were passed to the function.

Example

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

-- Use 'toggle' command to switch image on and off
addCommandHandler( "toggle",
    function()
        if not myImage then
            myImage = dxCreateTexture( "moonpig.png" )  -- Create texture
        else        
            destroyElement( myImage )                 -- Destroy texture
            myImage = nil
        end
    end
)

Changelog

Version Description
1.3.0-9.04021 Added textureType and depth argument
1.3.0-9.04035 Added textureEdge argument

See Also