DxDrawMaterialSectionLine3D: Difference between revisions

Latest revision as of 17:03, 7 November 2024

This function draws a textured 3D line between two points in the 3D world - rendered for one frame. This should be used in conjunction with onClientPreRender in order to display continuously.

The 3D line with a large width value effectively becomes a rectangle, so it it possible to construct basic shapes such as boxes with several large width lines and the appropriate values for 'faceToward'.

	This page describes the current implementation. For older versions check legacy version

Syntax

bool dxDrawMaterialSectionLine3D ( float startX, float startY, float startZ, float endX, float endY, float endZ,
                                   float u, float v, float usize, float vsize, [ bool flipUV = false, ] element material, float width,
                                 [ int color = white, [ bool stage = "postfx", ] float faceTowardX, float faceTowardY, float faceTowardZ ] )

Required Arguments

startX/Y/Z: The start position of the 3D line, representing a coordinate in the GTA world.
endX/Y/Z: The end position of the 3D line, representing a coordinate in the GTA world.
u: the absolute X coordinate of the top left corner of the section
v: the absolute Y coordinate of the top left corner of the section
usize: the absolute width of the section
vsize: the absolute height of the section
material: A material to draw the line with.
width: The width/thickness of the line in GTA world units. (This is 1/75th of the width used in dxDrawLine3D)

Optional Arguments

flipUV: A bool representing whether a UV orientation should be flipped.
color: An integer of the hex color, produced using tocolor or 0xAARRGGBB.
stage: A string representing a stage at which the actual drawcall should happen:
- prefx - Lines are rendered before the color correction. This stage makes lines look natural to SA but colors could be distorted.
- postfx - Lines are rendered after the color correction. This stage conveys a color from the function to a screen without distortions.
- postgui - Lines are rendered after GUI. The line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
faceTowardX/Y/Z: The direction the front of the line should face towards. If this is not set, the front of the line always faces toward the camera.

Returns

Returns a true if the operation was successful, false otherwise.

Example

This example draws corona like effects near the player

coronaTexture = dxCreateTexture("corona.png")
red = tocolor(255,0,0)
green = tocolor(0,255,0)
blue = tocolor(0,0,255)

addEventHandler("onClientPreRender",root,
    function()
        local x,y,z = getElementPosition(localPlayer)

        dxSetBlendMode("add")   -- Add blend mode looks best for corona effects
        drawCorona( x+2, y+2, z+1, 1, red )
        drawCorona( x+1, y+3, z+2, 1, green )
        drawCorona( x-1, y+2, z+3, 1, blue )
        dxSetBlendMode("blend") -- Restore default
    end
)

-- Draw the corona texture
function drawCorona( x, y, z, size, color )
    dxDrawMaterialSectionLine3D ( x, y, z+size,
                                  x, y, z-size,
                                  0,0,1,1, coronaTexture, size, color)
end

Changelog

Version	Description

1.5.5-9.11998

Added postGUI argument

1.5.8-9.20862

Added flipUV argument

@@ Line 5: / Line 5: @@
 The 3D line with a large width value effectively becomes a rectangle, so it it possible to construct basic shapes such as boxes with several large width lines and the appropriate values for 'faceToward'.
+{{Legacy|legacy/dxDrawMaterialSectionLine3D}}
+{{Updated feature/item|1.5.9|1.5.9|22465|
 ==Syntax==
 <syntaxhighlight lang="lua">
 bool dxDrawMaterialSectionLine3D ( float startX, float startY, float startZ, float endX, float endY, float endZ,
                                     float u, float v, float usize, float vsize, [ bool flipUV = false, ] element material, float width,
-                                  [ int color = white, [ bool postGUI = false, ] float faceTowardX, float faceTowardY, float faceTowardZ ] )
+                                  [ int color = white, [ bool stage = "postfx", ] float faceTowardX, float faceTowardY, float faceTowardZ ] )
 </syntaxhighlight>
@@ Line 23: / Line 26: @@
 ==Optional Arguments==
-{{New items|3.0159|1.5.8|
+{{Added feature/item|1.5.9|1.5.8|20862|
 * '''flipUV''': A bool representing whether a UV orientation should be flipped.
-|20862}}
-* '''color:''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB (AA = alpha, RR = red, GG = green, BB = blue).
-{{New items|5.0155|1.5.5-9.11998|
-* '''postGUI''': A bool representing whether the line should be drawn on top of or behind any ingame GUI.
 }}
+* '''color:''' An integer of the hex color, produced using [[tocolor]] or 0xAARRGGBB.
+* '''stage:''' A string representing a stage at which the actual drawcall should happen:
+** prefx - Lines are rendered before the color correction. This stage makes lines look natural to SA but colors could be distorted.
+** postfx - Lines are rendered after the color correction. This stage conveys a color from the function to a screen without distortions.
+** postgui - Lines are rendered after GUI. The line should be drawn on top of or behind any ingame GUI (rendered by CEGUI).
 * '''faceTowardX/Y/Z:''' The direction the front of the line should face towards. If this is not set, the front of the line always faces toward the camera.
 ===Returns===
 Returns a ''true'' if the operation was successful, ''false'' otherwise.
+}}
 ==Example==
@@ Line 63: / Line 68: @@
 </syntaxhighlight>
-==Requirements==
-{{Requirements|n/a|1.3.0-9.03931|}}
 ==Changelog==
 {{ChangelogHeader}}
-{{ChangelogItem|1.5.5-9.11998|Added postGUI argument}}
+{{ChangelogItem|1.5.5-9.11998|Added ''postGUI'' argument}}
+{{ChangelogItem|1.5.8-9.20862|Added ''flipUV'' argument}}
 ==See Also==