DxDrawText: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(54 intermediate revisions by 26 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{Client function}}  
{{Client function}}  
Draws a string of text on the screen for one frame. In order for the text to stay visible continuously, you need to call this function with the same parameters on each frame update (see [[onClientRender]]).


==Syntax==
==Syntax==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool dxDrawText ( string text, int left, int top [, int right=left, int bottom=top, int color=white, float scale=1, string font="default", string alignX="left", string alignY="top", bool clip=false, bool wordBreak=false] )
bool dxDrawText ( string text, float leftX, float topY, [ float rightX = leftX, float bottomY = topY, int color = white, float scaleXY = 1.0, float scaleY = 1.0,
                  mixed font = "default", string alignX = "left", string alignY = "top", bool clip = false, bool wordBreak = false,
                  bool postGUI = false, bool colorCoded = false, bool subPixelPositioning = false,
                  float fRotation = 0.0, float fRotationCenterX = 0.0, float fRotationCenterY = 0.0, float fLineSpacing = 0.0 ] )
</syntaxhighlight>
</syntaxhighlight>


===Required Arguments===  
===Required Arguments===  
*'''text:''' the text to draw
*'''text:''' the text to draw
*'''left:''' the absolute X coordinate of the top left corner of the text
*'''leftX:''' the absolute X coordinate of the top left corner of the text
*'''top:''' the absolute Y coordinate of the top left corner of the text
*'''topY:''' the absolute Y coordinate of the top left corner of the text


===Optional Arguments===
===Optional Arguments===
*'''right:''' the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''rightX:''' the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''bottom:''' the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''bottomY:''' the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
*'''color:''' the color of the text, a value produced by [[tocolor]].
*'''color:''' the color of the text, a value produced by [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
*'''scale:''' the size of the text.
*'''scale:''' the size of the text.{{New feature|3.0110|1.1|'''scale:''' can (optionally) be specified as two floats. i.e. '''scaleX, scaleY'''}}
*'''font:''' the dx font to use.
*'''font:''' Either a custom [[DX font]] element or the name of a built-in DX font: '''Note: Some fonts are incompatible with certain languages such as Arabic.'''
{{DxFonts}}
{{DxFonts}}
*'''alignX:''' horizontal alignment of the text within the bounding box. Can be '''"left"''', '''"center"''' or '''"right"'''.
*'''alignX:''' horizontal alignment of the text within the bounding box. Can be '''"left"''', '''"center"''' or '''"right"'''.
Line 23: Line 27:
*'''clip:''' if set to ''true'', the parts of the text that don't fit within the bounding box will be cut off.
*'''clip:''' if set to ''true'', the parts of the text that don't fit within the bounding box will be cut off.
*'''wordBreak:''' if set to ''true'', the text will wrap to a new line whenever it reaches the right side of the bounding box. If ''false'', the text will always be completely on one line.
*'''wordBreak:''' if set to ''true'', the text will wrap to a new line whenever it reaches the right side of the bounding box. If ''false'', the text will always be completely on one line.
* '''postGUI:''' A bool representing whether the text should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
{{New feature/item|3.0130|1.3.0|3986|
*'''colorCoded:''' Set to true to enable embedded #FFFFFF color codes. '''Note: clip and wordBreak are forced false if this is set.'''
*'''subPixelPositioning:''' A bool representing whether the text can be positioned sub-pixel-ly. Looks nicer for moving/scaling animations.
}}
{{New feature/item|3.0135|1.3.5|6054|
*'''fRotation:''' Rotation'''
*'''fRotationCenterX:''' Rotation Origin X'''
*'''fRotationCenterY:''' Rotation Origin Y'''
}}
{{Added feature/item|1.5.9|1.5.8|20957|
*'''fLineSpacing:''' Distance in pixels between the lines of text, this can be a negative number, works only when '''colorCoded''' is set to true''
}}


===Returns===
===Returns===
Returns ''true'' if successful, ''false'' otherwise.
Returns ''true'' if successful, ''false'' otherwise.
==Remarks==
The function is known to ''optimize'' certain drawing scenarios related to scaling and opacity (so called '''text on raster optimisation'''). You can find out more about it [https://forum.mtasa.com/topic/132881-scaling-dx-elements-for-all-resolution/?do=findComment&comment=1002485 here].


==Example==  
==Example==  
This example code will add the current zone name in the lower left corner of the players' screens.
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)
function createText ( )
    local playerX, playerY, playerZ = getElementPosition ( localPlayer )      -- Get our player's coordinates.
    local playerZoneName = getZoneName ( playerX, playerY, playerZ )          -- Get name of the zone the player is in.
    -- Draw zone name text's shadow.
    dxDrawText ( playerZoneName, 44, screenHeight - 41, screenWidth, screenHeight, tocolor ( 0, 0, 0, 255 ), 1.02, "pricedown" )
    -- Draw zone name text.
    dxDrawText ( playerZoneName, 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "pricedown" )
end
function HandleTheRendering ( )
    addEventHandler ( "onClientRender", root, createText ) -- keep the text visible with onClientRender.
end
addEventHandler ( "onClientResourceStart", resourceRoot, HandleTheRendering )
</syntaxhighlight>
This example shows how to set both horizontal and vertical text size.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
--TODO
local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)
 
 
function createText ( )
    dxDrawText ( getTickCount(), 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, 2, "pricedown" )
end
addEventHandler ( "onClientRender", root, createText )
</syntaxhighlight>
</syntaxhighlight>
==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03986|Added ''colorCoded'' and ''subPixelPositioning'' arguments}}
{{ChangelogItem|1.3.5-9.06054|Added ''fRotation'', ''fRotationCenterX'' and ''fRotationCenterY'' arguments}}
{{ChangelogItem|1.5.8-9.20957|Added ''fLineSpacing'' argument}}


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

Latest revision as of 08:15, 5 November 2023

Draws a string of text on the screen for one frame. In order for the text to stay visible continuously, you need to call this function with the same parameters on each frame update (see onClientRender).

Syntax

bool dxDrawText ( string text, float leftX, float topY, [ float rightX = leftX, float bottomY = topY, int color = white, float scaleXY = 1.0, float scaleY = 1.0,
                  mixed font = "default", string alignX = "left", string alignY = "top", bool clip = false, bool wordBreak = false,
                  bool postGUI = false, bool colorCoded = false, bool subPixelPositioning = false,
                  float fRotation = 0.0, float fRotationCenterX = 0.0, float fRotationCenterY = 0.0, float fLineSpacing = 0.0 ] )

Required Arguments

  • text: the text to draw
  • leftX: the absolute X coordinate of the top left corner of the text
  • topY: the absolute Y coordinate of the top left corner of the text

Optional Arguments

  • rightX: the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
  • bottomY: the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
  • color: the color of the text, a value produced by tocolor or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
  • scale: the size of the text.scale: can (optionally) be specified as two floats. i.e. scaleX, scaleY
  • font: Either a custom DX font element or the name of a built-in DX font: Note: Some fonts are incompatible with certain languages such as Arabic.
    • "default": Tahoma
    • "default-bold": Tahoma Bold
    • "clear": Verdana
    • "arial": Arial
    • "sans": Microsoft Sans Serif
    • "pricedown": Pricedown (GTA's theme text)
    • "bankgothic": Bank Gothic Medium
    • "diploma": Diploma Regular
    • "beckett": Beckett Regular
    • "unifont": Unifont
  • alignX: horizontal alignment of the text within the bounding box. Can be "left", "center" or "right".
  • alignY: vertical alignment of the text within the bounding box. Can be "top", "center" or "bottom".
  • clip: if set to true, the parts of the text that don't fit within the bounding box will be cut off.
  • wordBreak: if set to true, the text will wrap to a new line whenever it reaches the right side of the bounding box. If false, the text will always be completely on one line.
  • postGUI: A bool representing whether the text should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
  • colorCoded: Set to true to enable embedded #FFFFFF color codes. Note: clip and wordBreak are forced false if this is set.
  • subPixelPositioning: A bool representing whether the text can be positioned sub-pixel-ly. Looks nicer for moving/scaling animations.
  • fRotation: Rotation
  • fRotationCenterX: Rotation Origin X
  • fRotationCenterY: Rotation Origin Y
  • fLineSpacing: Distance in pixels between the lines of text, this can be a negative number, works only when colorCoded is set to true

Returns

Returns true if successful, false otherwise.

Remarks

The function is known to optimize certain drawing scenarios related to scaling and opacity (so called text on raster optimisation). You can find out more about it here.

Example

This example code will add the current zone name in the lower left corner of the players' screens.

local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)

function createText ( )
    local playerX, playerY, playerZ = getElementPosition ( localPlayer )       -- Get our player's coordinates.
    local playerZoneName = getZoneName ( playerX, playerY, playerZ )          -- Get name of the zone the player is in.

    -- Draw zone name text's shadow.
    dxDrawText ( playerZoneName, 44, screenHeight - 41, screenWidth, screenHeight, tocolor ( 0, 0, 0, 255 ), 1.02, "pricedown" )
    -- Draw zone name text.
    dxDrawText ( playerZoneName, 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, "pricedown" )
end

function HandleTheRendering ( )
    addEventHandler ( "onClientRender", root, createText ) -- keep the text visible with onClientRender.
end

addEventHandler ( "onClientResourceStart", resourceRoot, HandleTheRendering )

This example shows how to set both horizontal and vertical text size.

local screenWidth, screenHeight = guiGetScreenSize ( ) -- Get the screen resolution (width and height)


function createText ( )
    dxDrawText ( getTickCount(), 44, screenHeight - 43, screenWidth, screenHeight, tocolor ( 255, 255, 255, 255 ), 1, 2, "pricedown" )
end
addEventHandler ( "onClientRender", root, createText )

Changelog

Version Description
1.3.0-9.03986 Added colorCoded and subPixelPositioning arguments
1.3.5-9.06054 Added fRotation, fRotationCenterX and fRotationCenterY arguments
1.5.8-9.20957 Added fLineSpacing argument

See Also