DxGetTexturePixels: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
mNo edit summary
 
(9 intermediate revisions by 8 users not shown)
Line 2: Line 2:
__NOTOC__
__NOTOC__
This function fetches the [[Texture_pixels|pixels]] from a [[texture]] element. It can be used with a standard texture, render target or screen source.
This function fetches the [[Texture_pixels|pixels]] from a [[texture]] element. It can be used with a standard texture, render target or screen source.
 
{{Important Note|dxGetTexturePixels will not work on a screen source or render target if the player has disabled screen upload.}}
----
{{Note|
''Performance note:
*This function is slow and not something you want to be doing once a frame.
*''This function is slow and not something you want to be doing once a frame.''
*It is slower when reading pixels from a render target or screen source.
*''It is slower when reading pixels from a render target or screen source.''
*And is very slow indeed if the texture format is not ''' 'argb' ''' (unless the native ''''dds'''' format is used with correct options).
*''And is very slow indeed if the texture format is not ''' 'argb' ''' ''
}}
----


==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
string dxGetTexturePixels ( [ int surfaceIndex = 0, ] element texture [, int x = 0, int y = 0, int width = 0, int height = 0 ] )
string dxGetTexturePixels ( [ int surfaceIndex = 0, ] element texture [, string pixelsFormat = "plain" [, string textureFormat = "unknown"] [, bool mipmaps = true] ] [, int x = 0, int y = 0, int width = 0, int height = 0 ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{OOP||[[texture]]:getPixels}}
===Required Arguments===
===Required Arguments===
*'''texture :''' The texture element to get the pixels from
*'''texture :''' The texture element to get the pixels from


===Optional Arguments===
===Optional Arguments===
{{New feature/item|4.0130|1.3|4021|
*'''surfaceIndex:''' Desired slice to get if the texture is a volume texture, or desired face to get if the texture is a cube map. <nowiki>(Cube map faces: 0=+X 1=-X 2=+Y 3=-Y 4=+Z 5=-Z)</nowiki>
*'''surfaceIndex:''' Desired slice to get if the texture is a volume texture, or desired face to get if the texture is a cube map. <nowiki>(Cube map faces: 0=+X 1=-X 2=+Y 3=-Y 4=+Z 5=-Z)</nowiki>
{{New feature/item|3.0161|1.6.0|22185|
*'''pixelsFormat:''' "plain", "dds"
*'''textureFormat:''' A string representing the desired texture format for "'''dds'''" pixels, which can be one of:
**'''"unknown"''': Determined automatically based on texture format (default).
**'''"argb"''': ARGB uncompressed 32 bit color.
**'''"dxt1"''': DXT1 compressed - Can take a fraction of a second longer to create (unless the texture is already in DXT1). 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 create (unless the texture is already in DXT3). 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 create (unless the texture is already in DXT5). 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 for "'''dds'''" pixels so the texture looks good when drawn at various sizes.
}}
}}
By default the pixels from the whole texture is returned. To get only a portion of the texture, define a rectangular area using all four of these optional arguments:
By default the pixels from the whole texture is returned. To get only a portion of the texture, define a rectangular area using all four of these optional arguments:
Line 29: Line 36:


==Returns==
==Returns==
Returns a ''''plain'''' format pixels string if successful, ''false'' if invalid arguments were passed to the function.
Returns pixels string if successful, ''false'' if invalid arguments were passed to the function.


==Example==  
==Example==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
TODO
local mtaLogo = dxCreateTexture("mta-logo.png")
outputChatBox("MTA logo pixels is: "..dxGetTexturePixels(mtaLogo))
</syntaxhighlight>
</syntaxhighlight>


Line 42: Line 50:
{{ChangelogHeader}}
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.04021|Added surfaceIndex argument}}
{{ChangelogItem|1.3.0-9.04021|Added surfaceIndex argument}}
{{ChangelogItem|1.6.0-9.22185|Added dds pixels format}}


==See Also==
==See Also==
{{Drawing_functions}}
{{Drawing_functions}}
[[Category:Needs Example]]
 
[[hu:dxGetTexturePixels]]

Latest revision as of 14:47, 29 August 2023

This function fetches the pixels from a texture element. It can be used with a standard texture, render target or screen source.

[[{{{image}}}|link=|]] Important Note: dxGetTexturePixels will not work on a screen source or render target if the player has disabled screen upload.
[[{{{image}}}|link=|]] Note:
  • This function is slow and not something you want to be doing once a frame.
  • It is slower when reading pixels from a render target or screen source.
  • And is very slow indeed if the texture format is not 'argb' (unless the native 'dds' format is used with correct options).

Syntax

string dxGetTexturePixels ( [ int surfaceIndex = 0, ] element texture [, string pixelsFormat = "plain" [, string textureFormat = "unknown"] [, bool mipmaps = true] ] [, int x = 0, int y = 0, int width = 0, int height = 0 ] )

OOP Syntax Help! I don't understand this!

Method: texture:getPixels(...)


Required Arguments

  • texture : The texture element to get the pixels from

Optional Arguments

  • surfaceIndex: Desired slice to get if the texture is a volume texture, or desired face to get if the texture is a cube map. (Cube map faces: 0=+X 1=-X 2=+Y 3=-Y 4=+Z 5=-Z)
ADDED/UPDATED IN VERSION 1.6.0 r22185:
  • pixelsFormat: "plain", "dds"
  • textureFormat: A string representing the desired texture format for "dds" pixels, which can be one of:
    • "unknown": Determined automatically based on texture format (default).
    • "argb": ARGB uncompressed 32 bit color.
    • "dxt1": DXT1 compressed - Can take a fraction of a second longer to create (unless the texture is already in DXT1). 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 create (unless the texture is already in DXT3). 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 create (unless the texture is already in DXT5). 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 for "dds" pixels so the texture looks good when drawn at various sizes.

By default the pixels from the whole texture is returned. To get only a portion of the texture, define a rectangular area using all four of these optional arguments:

  • x: Rectangle left position
  • y: Rectangle top position
  • width: Rectangle width
  • height : Rectangle height

Returns

Returns pixels string if successful, false if invalid arguments were passed to the function.

Example

local mtaLogo = dxCreateTexture("mta-logo.png")
outputChatBox("MTA logo pixels is: "..dxGetTexturePixels(mtaLogo))

Requirements

Minimum server version n/a
Minimum client version 1.3

Note: Using this feature requires the resource to have the above minimum version declared in the meta.xml <min_mta_version> section. e.g. <min_mta_version client="1.3" />

Changelog

Version Description
1.3.0-9.04021 Added surfaceIndex argument
1.6.0-9.22185 Added dds pixels format

See Also

Retrieved from "https://wiki.multitheftauto.com/wiki/DxGetTexturePixels?oldid=77535"