Updated in 1.6.0 r21942

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.

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.

Tip

• It is highly recommended that dxSetTestMode is used when writing and testing scripts using dxCreateRenderTarget.
• Use dxSetBlendMode to get better quality.
• 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.).

OOP Syntax Help! I don't understand this!

• Constructor: DxRenderTarget (...)

Syntax

​dx-rendertarget dxCreateRenderTarget ( ​int width, ​int height, [ ​bool withAlpha = false ] )

Required Arguments

• width: The width of the texture in pixels.
• height: The height of the texture in pixels.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use.

• withAlpha (default: false): The render target will be created with an alpha channel. false will turn images alpha channels to black color.

Returns

• dx-rendertarget: render-target texture

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

Second Client Syntax

​dx-rendertarget|false dxCreateRenderTarget ( ​int width, ​int height, ​string surfaceFormat )

Required Arguments

• width: The width of the texture in pixels.
• height: The height of the texture in pixels.
• surfaceFormat: A string containing the surface format. See Surface formats. Default format without alpha is x8r8g8b8, default with alpha is a8r8g8b8.

Returns

• dx-rendertarget|false: render-target texture

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

Code Examples

Example 1 Example 2 (OOP)

client

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.

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)

client

OOP Required

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.

local myRenderTarget

addEventHandler("onClientResourceStart", resourceRoot, function()
    myRenderTarget = DxRenderTarget(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()
    myRenderTarget:setAsTarget(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)

Changelog

1.6.0 r21942

Added surfaceFormat syntax.

See Also

Drawing Functions

• dxConvertPixels
• dxCreateFont
• dxCreateRenderTargetUpdated
• dxCreateScreenSource
• dxCreateShader
• dxCreateTextureUpdated
• dxDrawCircle
• dxDrawImage
• dxDrawImageSection
• dxDrawLine
• dxDrawLine3D
• dxDrawMaterialLine3D
• dxDrawMaterialPrimitive
• dxDrawMaterialPrimitive3D
• dxDrawMaterialSectionLine3D
• dxDrawModel3DNew
• dxDrawPrimitive
• dxDrawPrimitive3D
• dxDrawRectangle
• dxDrawText
• dxDrawWiredSphere
• dxGetBlendMode
• dxGetFontHeight
• dxGetMaterialSize
• dxGetPixelColor
• dxGetPixelsFormat
• dxGetPixelsSize
• dxGetStatusUpdated
• dxGetTextSize
• dxGetTexturePixelsUpdated
• dxGetTextWidth
• dxIsAspectRatioAdjustmentEnabled
• dxSetAspectRatioAdjustmentEnabled
• dxSetBlendMode
• dxSetPixelColor
• dxSetRenderTarget
• dxSetShaderTessellation
• dxSetShaderTransform
• dxSetShaderValue
• dxSetTestMode
• dxSetTextureEdge
• dxSetTexturePixels
• dxUpdateScreenSource

Drawing Elements

• dx-font
• dx-rendertarget
• dx-screensource
• shader
• texture

Reference

• Scripting Functions