DxDrawCircle: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (Yes I could have made it use check( ) but I want to keep it as lightweight as possible so live with it)
 
(19 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{Useful Function}}
{{Client Function}}
<lowercasetitle/>
<lowercasetitle/>
__NOTOC__
__NOTOC__
This function draws a number of 2D lines in order to achieve a circle shape on the screen - rendered for '''one''' frame.  This should be used in conjunction with [[onClientRender]] in order to display continuously.
{{New feature/item|3.0156|1.5.5|13977|This function draws a circle shape on the screen - rendered for '''one''' frame.  This should be used in conjunction with [[onClientRender]] in order to be display continuously.}}


==Syntax==
==Syntax==
<syntaxhighlight lang="lua">bool dxDrawCircle ( int posX, int posY [, int radius = 50, int, width = 5, int angleAmount = 1, int startAngle = 0, int stopAngle = 360, int color = white, bool postGUI = false ] )</syntaxhighlight>
<syntaxhighlight lang="lua">bool dxDrawCircle ( float posX, float posY, float radius [, float startAngle = 0.0, float stopAngle = 360.0, int theColor = white,
                    int theCenterColor = theColor, int segments = 32, int ratio = 1, bool postGUI = false ] )</syntaxhighlight>


===Required Arguments===
===Required Arguments===
[[Image:DxDrawCircle_example.png|thumb|An example of how dxDrawCircle function works in practice.]]
[[Image:DxDrawCircle_Saml1er.png|thumb|An example of how dxDrawCircle function works in practice.]]
 
* '''posX''': An integer representing the '''absolute''' X position of the circle center, represented by pixels on the screen.
* '''posX''': An integer representing the '''absolute''' X position of the circle center, represented by pixels on the screen.
* '''posY''': An integer representing the '''absolute''' Y position of the circle center, represented by pixels on the screen.
* '''posY''': An integer representing the '''absolute''' Y position of the circle center, represented by pixels on the screen.
* '''radius''': An integer representing the radius scale of the circle that is being drawn.


===Optional Arguments===
===Optional Arguments===
{{OptionalArg}}
{{OptionalArg}}
* '''radius''': An integer representing the radius scale of the circle that is being drawn.
* '''width''': An integer representing the width of the line that is being drawn.
* '''angleAmount''': An integer representing the tightness of the circle. Lower amount makes it smoother, higher amount makes it more of a clock looking circle.
* '''startAngle''': An integer representing the angle of the first point of the circle.
* '''startAngle''': An integer representing the angle of the first point of the circle.
* '''stopAngle''': An integer representing the angle of the last point of the circle.
* '''stopAngle''': An integer representing the angle of the last point of the circle.
* '''color''': An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''theColor''': An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''postGUI''': A bool representing whether the line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
* '''theCenterColor''': An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
* '''segments''': An integer ranging from 3-1024 representing how many triangles are used to form the circle, more segments = smoother circle. Note: using lots of segments may cause lag.
* '''ratio''': Ratio between width and height, e.g: 2 would mean that the width of the circle is 2 times the height.
* '''postGUI''': A bool representing whether the circle should be drawn on top of or behind any ingame GUI (rendered by CEGUI).


===Returns===
===Returns===
Returns ''true'' if the creation of the 2D circle was successful, ''false'' otherwise.
Returns ''true'' if the creation of the 2D circle was successful, ''false'' otherwise.


==Code==
==Remarks==
<section name="Client" class="client" show="true">
By documentation this function does perform a '''triangle approximation of the cicle'''. This is important for when there is no shader support on the end-user hardware. If there is shader support then you can instead use shaders with euler-based math (sin/cos/asin) to create a smoother circle. The performance does scale much better than increasing the segment count of this function because drawing using shader would take up only one draw-call. Take look at [https://forum.mtasa.com/topic/133045-dxdrawcircle-chart/?do=findComment&comment=1002953 this post] for more details.
<syntaxhighlight lang="lua">
 
function dxDrawCircle( posX, posY, radius, width, angleAmount, startAngle, stopAngle, color, postGUI )
The above remark is about drawing circles on modern end-user hardware with angle-interval support, as necessary by example for pie-charts. '''Drawing full circles''' is easier because the math can be simplified to a euler distance calculation from the texcoord (0.5, 0.5) to the currently drawing pixel. Then the HLSL clip function can be used to not render any pixels outside of the circle. Read more about it in [https://forum.mtasa.com/topic/133453-round-render-target/#comment-1004102 this post].
if ( type( posX ) ~= "number" ) or ( type( posY ) ~= "number" ) then
 
return false
end
local function clamp( val, lower, upper )
if ( lower > upper ) then lower, upper = upper, lower end
return math.max( lower, math.min( upper, val ) )
end
radius = type( radius ) == "number" and radius or 50
width = type( width ) == "number" and width or 5
angleAmount = type( angleAmount ) == "number" and width or 1
startAngle = clamp( type( startAngle ) == "number" and startAngle or 0, 0, 360 )
stopAngle = clamp( type( stopAngle ) == "number" and stopAngle or 360, 0, 360 )
color = color or tocolor( 255, 255, 255, 200 )
postGUI = type( postGUI ) == "boolean" and postGUI or false
if ( stopAngle < startAngle ) then
local tempAngle = stopAngle
stopAngle = startAngle
startAngle = tempAngle
end
for i = startAngle, stopAngle, angleAmount do
local startX = math.cos( math.rad( i ) ) * ( radius - width )
local startY = math.sin( math.rad( i ) ) * ( radius - width )
local endX = math.cos( math.rad( i ) ) * ( radius + width )
local endY = math.sin( math.rad( i ) ) * ( radius + width )
dxDrawLine( startX + posX, startY + posY, endX + posX, endY + posY, color, width, postGUI )
end
return true
end
</syntaxhighlight>
</section>
<br />'''Author:''' Socialz
<br />
==Example==
==Example==
<section name="Client" class="client" show="true">
This function draws a rectangle with rounded corners.
This example draws a progressing circle shape in the middle of the screen.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local screenWidth, screenHeight = guiGetScreenSize( )
function dxDrawRoundedRectangle(x, y, rx, ry, color, radius)
local stopAngle = 0
    rx = rx - radius * 2
    ry = ry - radius * 2
    x = x + radius
    y = y + radius


addEventHandler( "onClientRender", root,
    if (rx >= 0) and (ry >= 0) then
function( )
        dxDrawRectangle(x, y, rx, ry, color)
if ( stopAngle < 360 ) then
        dxDrawRectangle(x, y - radius, rx, radius, color)
stopAngle = stopAngle + 5
        dxDrawRectangle(x, y + ry, rx, radius, color)
else
        dxDrawRectangle(x - radius, y, radius, ry, color)
stopAngle = 0
        dxDrawRectangle(x + rx, y, radius, ry, color)
end
dxDrawCircle( screenWidth / 2, screenHeight / 2, nil, nil, nil, nil, stopAngle )
end
)
</syntaxhighlight>
</section>


<section name="Client" class="client" show="true">
        dxDrawCircle(x, y, radius, 180, 270, color, color, 7)
This example draws the shape of a circle arc with an angle of 90° (example by: Michael89/Trevit)
        dxDrawCircle(x + rx, y, radius, 270, 360, color, color, 7)
<syntaxhighlight lang="lua">
        dxDrawCircle(x + rx, y + ry, radius, 0, 90, color, color, 7)
addEventHandler( "onClientRender", root,  
        dxDrawCircle(x, y + ry, radius, 90, 180, color, color, 7)
function( )
    end
-- We're starting to draw the circle at 0° which means that the first point of the arc is ( 200+50 | 200 )
end
-- Therefore the last point is ( 200 | 200+50 ). > Our arc is the "lower right" quarter of the circle.
dxDrawRoundedRectangle(350, 50, 100, 100, tocolor(0, 255, 0, 255), 20)
dxDrawCircle( 200, 200, 50, 5, 1, 0, 90 )
end
)
</syntaxhighlight>
</syntaxhighlight>
</section>


==See Also==
==See Also==
{{Useful_Functions}}
{{Drawing_functions}}
 
[[hu:dxDrawCircle]]

Latest revision as of 19:07, 8 December 2021

This function draws a circle shape on the screen - rendered for one frame. This should be used in conjunction with onClientRender in order to be display continuously.

Syntax

bool dxDrawCircle ( float posX, float posY, float radius [, float startAngle = 0.0, float stopAngle = 360.0, int theColor = white,
                    int theCenterColor = theColor, int segments = 32, int ratio = 1, bool postGUI = false ] )

Required Arguments

An example of how dxDrawCircle function works in practice.
  • posX: An integer representing the absolute X position of the circle center, represented by pixels on the screen.
  • posY: An integer representing the absolute Y position of the circle center, represented by pixels on the screen.
  • radius: An integer representing the radius scale of the circle that is being drawn.

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.

  • startAngle: An integer representing the angle of the first point of the circle.
  • stopAngle: An integer representing the angle of the last point of the circle.
  • theColor: An integer of the hex color, produced using tocolor or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
  • theCenterColor: An integer of the hex color, produced using tocolor or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
  • segments: An integer ranging from 3-1024 representing how many triangles are used to form the circle, more segments = smoother circle. Note: using lots of segments may cause lag.
  • ratio: Ratio between width and height, e.g: 2 would mean that the width of the circle is 2 times the height.
  • postGUI: A bool representing whether the circle should be drawn on top of or behind any ingame GUI (rendered by CEGUI).

Returns

Returns true if the creation of the 2D circle was successful, false otherwise.

Remarks

By documentation this function does perform a triangle approximation of the cicle. This is important for when there is no shader support on the end-user hardware. If there is shader support then you can instead use shaders with euler-based math (sin/cos/asin) to create a smoother circle. The performance does scale much better than increasing the segment count of this function because drawing using shader would take up only one draw-call. Take look at this post for more details.

The above remark is about drawing circles on modern end-user hardware with angle-interval support, as necessary by example for pie-charts. Drawing full circles is easier because the math can be simplified to a euler distance calculation from the texcoord (0.5, 0.5) to the currently drawing pixel. Then the HLSL clip function can be used to not render any pixels outside of the circle. Read more about it in this post.

Example

This function draws a rectangle with rounded corners. 

function dxDrawRoundedRectangle(x, y, rx, ry, color, radius)
    rx = rx - radius * 2
    ry = ry - radius * 2
    x = x + radius
    y = y + radius

    if (rx >= 0) and (ry >= 0) then
        dxDrawRectangle(x, y, rx, ry, color)
        dxDrawRectangle(x, y - radius, rx, radius, color)
        dxDrawRectangle(x, y + ry, rx, radius, color)
        dxDrawRectangle(x - radius, y, radius, ry, color)
        dxDrawRectangle(x + rx, y, radius, ry, color)

        dxDrawCircle(x, y, radius, 180, 270, color, color, 7)
        dxDrawCircle(x + rx, y, radius, 270, 360, color, color, 7)
        dxDrawCircle(x + rx, y + ry, radius, 0, 90, color, color, 7)
        dxDrawCircle(x, y + ry, radius, 90, 180, color, color, 7)
    end
end
dxDrawRoundedRectangle(350, 50, 100, 100, tocolor(0, 255, 0, 255), 20)

See Also

Retrieved from "https://wiki.multitheftauto.com/wiki/DxDrawCircle?oldid=73127"