DxCreateRenderTarget: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(22 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{Client function}}
{{Client function}}
__NOTOC__
__NOTOC__
{{New feature|3.0110|1.1|
This function creates a render target element, which is a special type of [[texture]] that can be drawn on with the dx functions. Successful render target creation is not guaranteed, and may fail due to hardware or memory limitations.
Only available in 1.1
}}
This function creates a render target element, which is a special type of [[texture]] that can be draw on with the dx functions.


Note that successful render target creation is not guaranteed, and may fail due to hardware or memory limitations. You should always check to see if this function has returned false.
To see if creation is likely to fail, use [[dxGetStatus]]. (When '''VideoMemoryFreeForMTA''' is zero, failure ''is'' guaranteed.)
{{Tip|Use [[dxSetBlendMode]] to get better quality}}
{{Tip|It is highly recommended that [[dxSetTestMode]] is used when writing and testing scripts using dxCreateRenderTarget.}}
{{Note|Render targets are usually cleared when the player minimizes MTA (i.e. alt-tab). See [[onClientRestore]] for details on when to restore any fixed content.}}


==Syntax==  
==Syntax==  
Line 12: Line 12:
element dxCreateRenderTarget ( int width, int height [, bool withAlpha = false ] )
element dxCreateRenderTarget ( int width, int height [, bool withAlpha = false ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{Added feature/item|1.6.1|1.6.0|21938|
<syntaxhighlight lang="lua">
element dxCreateRenderTarget ( int width, int height, surface-format surfaceFormat )
</syntaxhighlight>
}}
{{OOP||[[Texture|DxRenderTarget]]}}
===Required Arguments===  
===Required Arguments===  
*'''width :''' The width of the texture in pixels.
*'''width :''' The width of the texture in pixels.
*'''height :''' The height of the texture in pixels.
*'''height :''' The height of the texture in pixels.
*'''withAlpha:''' The render target will be created with an alpha channel.
*'''withAlpha:''' The render target will be created with an alpha channel. 'false' will turn images' alpha channels to black color
{{Added feature/item|1.6.1|1.6.0|21938|
*'''surfaceFormat :''' See [[Surface format|Surface formats]]
}}


===Returns===
===Returns===
Returns a [[texture]] [[element]] if successful, ''false'' if the system is unable to create a render target.
Returns a [[texture]] element if successful, ''false'' if the system is unable to create a render target.
 
'''You should always check to see if this function has returned false.'''
 
==Explanation==
What is a render target?
 
A render target is like a blank canvas. You can draw on the render target as many times as you like - and even clear it.
 
If your dxDraw* calls are static (meaning the appearance doesn't change), or only update periodically, then a render target can be useful not only for cleaner code - but for performance reasons too. Instead of making possibly hundreds of dxDraw* calls every frame, you can simply make those calls on a single frame and draw directly to the render target, then use a '''single''' dxDrawImage call every frame afterwards to display the render target.
 
Render targets can also be used to create and display the same thing multiple times, as shown in the example below.
 


==Example==
==Example==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local myRenderTarget
addEventHandler("onClientResourceStart", resourceRoot,
addEventHandler("onClientResourceStart", resourceRoot,
     function()
     function()
         myRenderTarget = dxCreateRenderTarget( 80, 100 )           -- Create a render target texture which is 80 x 100 pixels
         myRenderTarget = dxCreateRenderTarget(250, 100, true)       -- Create a render target
 
        if (myRenderTarget) then
            updateRenderTarget()    -- Our function to draw to the render target (see below)
        end
     end
     end
)
)
Line 32: Line 58:
     function()
     function()
         if myRenderTarget then
         if myRenderTarget then
             dxSetRenderTarget( myRenderTarget )                    -- Start drawing on myRenderTarget
             -- Draw the render target lots of times in different positions on the screen
            dxDrawText ( "Hello", 10, 20 )                          -- Draw a message
             dxDrawImage(350, 50, 250, 100, myRenderTarget)
            dxSetRenderTarget()                                    -- Stop drawing on myRenderTarget
             dxDrawImage(450, 380, 250, 100, myRenderTarget)
 
             dxDrawImage(550, 250, 250, 100, myRenderTarget)
             dxDrawImage( 50, 50, 100, 100, myRenderTarget )       -- Now use myRenderTarget as a material and draw it lots of times
             dxDrawImage(650, 70, 250, 100, myRenderTarget)
             dxDrawImage( 150, 350, 150, 100, myRenderTarget )
             dxDrawImage( 250, 250, 100, 150, myRenderTarget )
             dxDrawImage( 350, 30, 150, 150, myRenderTarget )
         end
         end
     end
     end
)
)
function updateRenderTarget()
    dxSetRenderTarget(myRenderTarget, true)
    dxSetBlendMode("modulate_add")  -- Set 'modulate_add' when drawing stuff on the render target
    dxDrawText("Hello " .. getTickCount(), 10, 10, 0, 0, tocolor(255, 255, 255, 255), 2, "clear")        -- Draw a message
    dxDrawRectangle(10, 50, 40, 40, tocolor(math.random(255), math.random(255), math.random(255)))      -- Draw a square with random color
    -- ... etc, imagine you have a lot of dxDraw* calls to make, this is where render targets come in handy!
    dxSetBlendMode("blend")  -- Restore default blending
    dxSetRenderTarget()      -- Restore default render target
end
-- We can even update the render target on the fly, by binding it to a key
bindKey("r", "down", updateRenderTarget)
</syntaxhighlight>
</syntaxhighlight>


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

Latest revision as of 16:34, 10 August 2023

This function creates a render target element, which is a special type of texture that can be drawn on with the dx functions. Successful render target creation is not guaranteed, and may fail due to hardware or memory limitations.

To see if creation is likely to fail, use dxGetStatus. (When VideoMemoryFreeForMTA is zero, failure is guaranteed.)

[[{{{image}}}|link=|]] Tip: Use dxSetBlendMode to get better quality
[[{{{image}}}|link=|]] Tip: It is highly recommended that dxSetTestMode is used when writing and testing scripts using dxCreateRenderTarget.
[[{{{image}}}|link=|]] Note: Render targets are usually cleared when the player minimizes MTA (i.e. alt-tab). See onClientRestore for details on when to restore any fixed content.

Syntax

element dxCreateRenderTarget ( int width, int height [, bool withAlpha = false ] )
BETA: NEW FEATURE (BUILD: 1.6.0 r21938)
element dxCreateRenderTarget ( int width, int height, surface-format surfaceFormat )

OOP Syntax Help! I don't understand this!

Method: DxRenderTarget(...)


Required Arguments

  • width : The width of the texture in pixels.
  • height : The height of the texture in pixels.
  • withAlpha: The render target will be created with an alpha channel. 'false' will turn images' alpha channels to black color
BETA: NEW FEATURE (BUILD: 1.6.0 r21938)

Returns

Returns a texture element if successful, false if the system is unable to create a render target.

You should always check to see if this function has returned false.

Explanation

What is a render target?

A render target is like a blank canvas. You can draw on the render target as many times as you like - and even clear it.

If your dxDraw* calls are static (meaning the appearance doesn't change), or only update periodically, then a render target can be useful not only for cleaner code - but for performance reasons too. Instead of making possibly hundreds of dxDraw* calls every frame, you can simply make those calls on a single frame and draw directly to the render target, then use a single dxDrawImage call every frame afterwards to display the render target.

Render targets can also be used to create and display the same thing multiple times, as shown in the example below.


Example

local myRenderTarget

addEventHandler("onClientResourceStart", resourceRoot,
    function()
        myRenderTarget = dxCreateRenderTarget(250, 100, true)       -- Create a render target

        if (myRenderTarget) then 
            updateRenderTarget()     -- Our function to draw to the render target (see below)
        end
    end
)

addEventHandler( "onClientRender", root,
    function()
        if myRenderTarget then
            -- Draw the render target lots of times in different positions on the screen
            dxDrawImage(350, 50, 250, 100, myRenderTarget)
            dxDrawImage(450, 380, 250, 100, myRenderTarget)
            dxDrawImage(550, 250, 250, 100, myRenderTarget)
            dxDrawImage(650, 70, 250, 100, myRenderTarget)
        end
    end
)

function updateRenderTarget()
    dxSetRenderTarget(myRenderTarget, true)
    dxSetBlendMode("modulate_add")  -- Set 'modulate_add' when drawing stuff on the render target

    dxDrawText("Hello " .. getTickCount(), 10, 10, 0, 0, tocolor(255, 255, 255, 255), 2, "clear")        -- Draw a message
    dxDrawRectangle(10, 50, 40, 40, tocolor(math.random(255), math.random(255), math.random(255)))       -- Draw a square with random color

    -- ... etc, imagine you have a lot of dxDraw* calls to make, this is where render targets come in handy!

    dxSetBlendMode("blend")  -- Restore default blending
    dxSetRenderTarget()      -- Restore default render target
end

-- We can even update the render target on the fly, by binding it to a key
bindKey("r", "down", updateRenderTarget)

See Also

Retrieved from "https://wiki.multitheftauto.com/wiki/DxCreateRenderTarget?oldid=77437"