DxDrawImage: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (→‎Example: This function is client-sided already, no need for the section.)
No edit summary
 
(18 intermediate revisions by 11 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{Client function}}  
{{Client function}}  
[[Image:MTAsa dxDrawImage.png|thumb|190px|An image drawn on the screen with the dxDrawImage function.]]


Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).<br/>
Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).<br/>
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.<br/>
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.<br/>
<b>Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...</b>
<b>Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...</b>
{{Note|To help prevent edge artifacts when drawing textures, set '''textureEdge''' to '''"clamp"''' when calling [[dxCreateTexture]]}}
 
{{Important Note|Do not draw image from path. Use a texture created with [[dxCreateTexture]] instead to '''efficiently draw image'''.}}
{{Important Note|For further optimising your DX code, see [[dxCreateRenderTarget]]. You should use render target whenever possible, in order to dramatically reduce CPU usage caused by many dxDraw* calls.}}
{{Tip|To help prevent edge artifacts when drawing textures, set '''textureEdge''' to '''"clamp"''' when calling [[dxCreateTexture]].}}
==Syntax==
==Syntax==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool dxDrawImage ( float posX, float posY, float width, float height, mixed image [, float rotation = 0, float rotationCenterOffsetX = 0,  
bool dxDrawImage ( float posX, float posY, float width, float height, mixed image,
float rotationCenterOffsetY = 0, int color = tocolor(255,255,255), bool postGUI = false ] )
                [ float rotation = 0, float rotationCenterOffsetX = 0, float rotationCenterOffsetY = 0,
                  int color = tocolor(255,255,255,255), bool postGUI = false ] )
</syntaxhighlight>
</syntaxhighlight>


Line 17: Line 23:
*'''width:''' the absolute width of the image
*'''width:''' the absolute width of the image
*'''height:''' the absolute height of the image
*'''height:''' the absolute height of the image
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
*'''image:''' Either a [[material]] element or a [[filepath]] of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring. Use a texture created with [[dxCreateTexture]] to '''speed up drawing'''.


===Optional Arguments===
===Optional Arguments===
Line 23: Line 29:
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetX:''' the absolute X offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''rotationCenterOffsetY:''' the absolute Y offset from the image center for which to rotate the image from.
*'''color:''' Tints the image with a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''color:''' Tints the image with a value produced by [[tocolor]] or hexadecimal number in format: 0xAARRGGBB (RR = red, GG = green, BB = blue, AA = alpha).
*'''postgui :''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
*'''postGUI:''' A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).


===Returns===
===Returns===
Line 32: Line 38:
Example of a pendulum swinging from the top of the screen, made using dxDrawImage.
Example of a pendulum swinging from the top of the screen, made using dxDrawImage.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local screenWidth,screenHeight = guiGetScreenSize()  -- Get screen resolution.
local screenWidth, screenHeight = guiGetScreenSize()  -- Get screen resolution.
 
local arrowTexture = dxCreateTexture('arrow.png')


function renderDisplay ( )
function renderDisplay ( )
Line 41: Line 47:
-- using the size of 100 pixels wide, and 240 pixels high.
-- using the size of 100 pixels wide, and 240 pixels high.
-- The center of rotation is at the top of the image.
-- The center of rotation is at the top of the image.
dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, 'arrow.png', angle, 0, -120 )
dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, arrowTexture, angle, 0, -120 )
end
end
 
addEventHandler("onClientRender", root, renderDisplay)  -- Keep everything visible with onClientRender.
 
function HandleTheRendering ( )
addEventHandler("onClientRender", getRootElement(), renderDisplay)  -- Keep everything visible with onClientRender.
end
addEventHandler("onClientResourceStart",resourceRoot, HandleTheRendering)
</syntaxhighlight>
</syntaxhighlight>


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

Latest revision as of 12:49, 18 July 2024

An image drawn on the screen with the dxDrawImage function.

Draws an image on the screen for a single frame. In order for the image to stay visible continuously, you need to call this function with the same parameters on each frame update (see onClientRender).
Image files should ideally have dimensions that are a power of two, to prevent possible blurring.
Power of two: 2px, 4px, 8px, 16px, 32px, 64px, 128px, 256px, 512px, 1024px...


[[{{{image}}}|link=|]] Important Note: Do not draw image from path. Use a texture created with dxCreateTexture instead to efficiently draw image.
[[{{{image}}}|link=|]] Important Note: For further optimising your DX code, see dxCreateRenderTarget. You should use render target whenever possible, in order to dramatically reduce CPU usage caused by many dxDraw* calls.
[[{{{image}}}|link=|]] Tip: To help prevent edge artifacts when drawing textures, set textureEdge to "clamp" when calling dxCreateTexture.

Syntax

bool dxDrawImage ( float posX, float posY, float width, float height, mixed image,
                 [ float rotation = 0, float rotationCenterOffsetX = 0, float rotationCenterOffsetY = 0,
                   int color = tocolor(255,255,255,255), bool postGUI = false ] )

Required Arguments

  • posX: the absolute X coordinate of the top left corner of the image
  • posY: the absolute Y coordinate of the top left corner of the image
  • width: the absolute width of the image
  • height: the absolute height of the image
  • image: Either a material element or a filepath of the image which is going to be drawn. (.dds images are also supported). Image files should ideally have dimensions that are a power of two, to prevent possible blurring. Use a texture created with dxCreateTexture to speed up drawing.

Optional Arguments

  • rotation: the rotation, in degrees for the image.
  • rotationCenterOffsetX: the absolute X offset from the image center for which to rotate the image from.
  • rotationCenterOffsetY: the absolute Y offset from the image center for which to rotate the image from.
  • color: Tints the image with a value produced by tocolor or hexadecimal number in format: 0xAARRGGBB (RR = red, GG = green, BB = blue, AA = alpha).
  • postGUI: A bool representing whether the image should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

Returns

Returns true if successful, false otherwise.

Example

Example of a pendulum swinging from the top of the screen, made using dxDrawImage. 

local screenWidth, screenHeight = guiGetScreenSize()  -- Get screen resolution.
local arrowTexture = dxCreateTexture('arrow.png')

function renderDisplay ( )
	local seconds = getTickCount() / 1000
	local angle = math.sin(seconds) * 80
	-- This will draw the graphic file 'arrow.png' at the top middle of the screen
	-- using the size of 100 pixels wide, and 240 pixels high.
	-- The center of rotation is at the top of the image.
	dxDrawImage ( screenWidth/2 - 50, 0, 100, 240, arrowTexture, angle, 0, -120 )
end
addEventHandler("onClientRender", root, renderDisplay)  -- Keep everything visible with onClientRender.

See Also

Retrieved from "https://wiki.multitheftauto.com/wiki/DxDrawImage?oldid=79916"