DgsCreateCustomRenderer: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Created page with "__NOTOC__ {{Client function}} This function creates a custom renderer that can be used in any texture required property of dgs elements, which is useful for creating custom DG...")
 
 
(9 intermediate revisions by the same user not shown)
Line 2: Line 2:
{{Client function}}
{{Client function}}
This function creates a custom renderer that can be used in any texture required property of dgs elements, which is useful for creating custom DGS plugins.
This function creates a custom renderer that can be used in any texture required property of dgs elements, which is useful for creating custom DGS plugins.
'''Notice:''' The environment of '''renderFunction''' is inside DGS. You have to use [[dgsSetProperty]] if you want to pass something into the '''renderFunction'''.


==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
element dgsCreateCustomRenderer( string renderFunction )
element dgsCreateCustomRenderer( [ string renderFunction ] )
</syntaxhighlight>  
</syntaxhighlight>  


===Required Arguments===  
===Optional Arguments===  
*'''renderFunction:''' A string of lua code which will be the new renderer of the custom renderer.
*'''renderFunction''': A string of lua code which will be the new renderer function of the custom renderer.
**'''Predefined Variable of renderFunction:''' For detail, see [[dxDrawImage]]
**''Predefined Variable of renderFunction'': Determined by '''dxDrawType'''. For detail, see [[dxDrawImage]] or [[dxDrawText]]
***'''posX:''' Absolute X position of the renderer's bounding box.
**Global:
***'''posY:''' Absolute Y position of the renderer's bounding box.
***'''dxDrawType''': A string indicates what kind of drawing, can be "'''image'''" or "'''text'''".
***'''width:''' Absolute width of the renderer's bounding box.
**Passed By Function:
***'''height:''' Absolute height of the renderer's bounding box.
**''When dxDrawType is "image"'':
***'''posX''': Absolute X position of the renderer's bounding box.
***'''posY''': Absolute Y position of the renderer's bounding box.
***'''width''': Absolute width of the renderer's bounding box.
***'''height''': Absolute height of the renderer's bounding box.
***'''self''': The custom renderer itself.
***'''rotation''': The rotation of renderer's bounding box.
***'''rotationCenterOffsetX''': The rotation center offset x of renderer's bounding box.
***'''rotationCenterOffsetY''': The rotation center offset x of renderer's bounding box.
***'''color''': The color to be applied.
***'''postGUI''': Whether the dx draw is require postGUI
**''When dxDrawType is "text"'':
***'''self:''' The custom renderer itself.
***'''self:''' The custom renderer itself.
***'''rotation:''' The rotation of renderer's bounding box.
***'''leftX:''' the absolute X coordinate of the top left corner of the text
***'''rotationCenterOffsetX:''' The rotation center offset x of renderer's bounding box.
***'''topY:''' the absolute Y coordinate of the top left corner of the text
***'''rotationCenterOffsetY:''' The rotation center offset x of renderer's bounding box.
***'''rightX:''' the absolute X coordinate of the right side of the text bounding box. Used for text aligning, clipping and word breaking.
***'''color:''' The color to be applied.
***'''bottomY:''' the absolute Y coordinate of the bottom side of the text bounding box. Used for text aligning, clipping and word breaking.
***'''postGUI:''' Whether the dx draw is require postGUI
***'''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.{{New feature|3.0110|1.1|'''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.'''
***'''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===
Line 35: Line 61:
local tex = dxCreateTexture("exampleTexture.png") --Create a texture
local tex = dxCreateTexture("exampleTexture.png") --Create a texture
local image = DGS:dgsCreateImage(300,300,200,200,customRenderer,false) --Apply the custom renderer
local image = DGS:dgsCreateImage(300,300,200,200,customRenderer,false) --Apply the custom renderer
DGS:dgsSetProperty(customRenderer,"customTexture",tex) --Make a reference for the texture that can be used in the render function.
DGS:dgsAttachToAutoDestroy(tex,image) --The texture will be destroyed when the image destroys
DGS:dgsAttachToAutoDestroy(tex,image) --The texture will be destroyed when the image destroys
DGS:dgsAttachToAutoDestroy(customRenderer,image) --The custom renderer will be destroyed when the image destroys


setTimer(function()
setTimer(function()

Latest revision as of 16:20, 25 March 2022

This function creates a custom renderer that can be used in any texture required property of dgs elements, which is useful for creating custom DGS plugins.

Notice: The environment of renderFunction is inside DGS. You have to use dgsSetProperty if you want to pass something into the renderFunction.

Syntax

element dgsCreateCustomRenderer( [ string renderFunction ] )

Optional Arguments

  • renderFunction: A string of lua code which will be the new renderer function of the custom renderer.
    • Predefined Variable of renderFunction: Determined by dxDrawType. For detail, see dxDrawImage or dxDrawText
    • Global:
      • dxDrawType: A string indicates what kind of drawing, can be "image" or "text".
    • Passed By Function:
    • When dxDrawType is "image":
      • posX: Absolute X position of the renderer's bounding box.
      • posY: Absolute Y position of the renderer's bounding box.
      • width: Absolute width of the renderer's bounding box.
      • height: Absolute height of the renderer's bounding box.
      • self: The custom renderer itself.
      • rotation: The rotation of renderer's bounding box.
      • rotationCenterOffsetX: The rotation center offset x of renderer's bounding box.
      • rotationCenterOffsetY: The rotation center offset x of renderer's bounding box.
      • color: The color to be applied.
      • postGUI: Whether the dx draw is require postGUI
    • When dxDrawType is "text":
      • self: The custom renderer itself.
      • 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
      • 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.
      • 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 a dgs-dxcustomrenderer element if successfully, false otherwise

Example

DGS = exports.dgs
local customRenderer = DGS:dgsCreateCustomRenderer([[
	local texture = dgsGetProperty(self,"customTexture")
	dxDrawImage(posX,posY,width,height,texture,rotation,rotationCenterOffsetX,rotationCenterOffsetY,color,postGUI)
	dxDrawImage(posX-width,posY-height,width,height,texture,rotation,rotationCenterOffsetX,rotationCenterOffsetY,color,postGUI)
]] )
local tex = dxCreateTexture("exampleTexture.png") --Create a texture
local image = DGS:dgsCreateImage(300,300,200,200,customRenderer,false) --Apply the custom renderer
DGS:dgsSetProperty(customRenderer,"customTexture",tex) --Make a reference for the texture that can be used in the render function.
DGS:dgsAttachToAutoDestroy(tex,image) --The texture will be destroyed when the image destroys
DGS:dgsAttachToAutoDestroy(customRenderer,image) --The custom renderer will be destroyed when the image destroys

setTimer(function()
	destroyElement(image)
end,10000,1)

See Also

Custom Cursor Functions

Multi Language Supports

Animation

3D Element

3D Interface

3D Line

3D Image

3D Text

Browser

Button

Check Box

Combo Box

Custom Renderer

Edit

Detect Area

Drag'N Drop

Grid List

Image

Memo

Menu

Label

Layout

Line

Progress Bar

Radio Button

Scale Pane

Scroll Bar

Scroll Pane

Selector

Style

Switch Button

Tab Panel

Window

Basic Shape Plugins

Circle

Quadrilateral

Rounded Rectangle

Other Plugins

Blur Box

Canvas

Chart

Color Picker

Effect 3D

Gradient

Mask

Media Browser

Nine Slice

Object Preview Supports

Paste Handler

QRCode

Remote Image

Screen Source

SVG

Tooltips