Documentation
Drawing (dx)

Drawing (dx)

All Lua functions and events in the Drawing (dx) category, on the server and the client.

Client functions 91

attachCameraRenderAttaches the camera to an element (a vehicle, a player, a ped, an object, a model object). The position and target are in metres in the element's frame (x right, y forward, z up); the target defaults to 10 m in front of the camera. A rear-view mirror is a camera at the back of the car looking backwards plus setCameraRenderMirrored.
createCameraRenderCreates a second camera that renders the world into a texture: a car mirror, CCTV, a screen showing a drone view. Draw the texture with dxDrawImage, dxDrawMaterialLine3D or pass it to a shader. Size 16-2048 pixels, 0-60 shots per second (0 = only on request with renderCameraMatrix/updateCameraRender). Every shot is an extra scene render, so it costs performance.
createGroundDecalNewLays an image on the ground - a track, a stain or a place marker. The image follows slopes and kerbs instead of hanging flat above them. It is drawn up to 150 m from the camera, and with a lifetime set the last second fades out smoothly. The decal stays until destroyGroundDecal or until the resource stops.
createRecordingFromDataCreates a recording from AVI (MJPEG) data: from getRecordingData, a file or another player.
createRecordingPlayerCreates a recording player that is a texture: you draw it like any texture, also in the world with dxDrawMaterialLine3D. The recording can be deleted afterwards; the player keeps its own frames.
destroyGroundDecalNewRemoves a decal made with createGroundDecal.
detachCameraRenderDetaches the camera from an element; it stays at the spot of the last shot.
dxConvertPixelsConverts pixels to another format: plain, png or jpeg (with quality 1-100).
dxCreateFontCreates a font from a resource TTF/OTF file or from a system typeface (pass its name). The size is in points. Pass the font to dxDrawText and guiSetFont.
dxCreateRenderTargetCreates an off-screen drawing surface. After dxSetRenderTarget(rt) every dxDraw* draws on it, and then you draw it like a texture. Without an alpha channel every pixel is opaque.
dxCreateScreenSourceCreates a screen source of a given size. dxUpdateScreenSource writes the game image into it (scaled), which you then draw or process with a shader.
dxCreateTextureCreates a texture: from a resource image file, from pixels (plain, png, jpeg, dds) or an empty one of a given size. The texture is a material for dxDrawImage, dxDrawMaterial*3D and shaders.
dxDrawBorderedRectangleDraws a rectangle with a fill and a border of a given thickness in one call.
dxDrawCircleDraws a circle, an ellipse or a pie slice with centre (x, y) and a radius in pixels. The short form takes just a colour as the fourth argument.
dxDrawGradientRectangleDraws a rectangle with a vertical blend from the top colour to the bottom one.
dxDrawImageDraws an image (a resource PNG/JPG file, a texture, a render target, a browser or a camera) in a screen rectangle, with optional rotation and tint.
dxDrawImageSectionDraws a section of an image (u, v, section width and height in image pixels) in a screen rectangle. Useful for icon sheets and progress bars.
dxDrawLineDraws a line between two screen points.
dxDrawLine3DDraws a line between two world points: projects them onto the screen and joins them. It only draws when both ends are on screen and is not hidden by buildings.
dxDrawMaterialLine3DDraws a material (an image, a texture, a browser, a camera or a shader) as a strip in the 3D world: from the start point (top of the image) to the end, with a given width. The strip faces the camera or the faceX, faceY, faceZ point. The drawing is part of the world: buildings hide it and it glows (a screen is visible at night). This is how you make a billboard, a cinema screen or a sign above a building.
dxDrawMaterialPrimitive3DDraws a triangle shape in the 3D world covered with a material. Vertices are {x, y, z, color, u, v}, where u and v (0-1) tell which image point lands on the vertex. The colour of the whole shape comes from the first vertex.
dxDrawMaterialSectionLine3DLike dxDrawMaterialLine3D, but draws only a section of the material (u, v, section width and height in pixels).
dxDrawModel3DDraws a game object model at a spot for one frame: without collision, hidden by the world. It does not work for peds and vehicles. The first frame of a new model waits until the game loads it. At most 64 objects at once.
dxDrawPrimitiveDraws a 2D shape from a list of {x, y [, color]} vertices: points, lines or triangles. The colour is blended smoothly between vertices.
dxDrawPrimitive3DDraws a shape made of triangles in the 3D world from {x, y, z, color} vertices. The whole shape has the colour of the first vertex.
dxDrawRectangleDraws a filled rectangle on the screen for one frame. Call it in onClientRender to keep it visible.
dxDrawRoundedRectangleDraws a rectangle with rounded corners. The radius is in pixels and never exceeds half of the shorter side.
dxDrawTextDraws text on the screen for one frame. Call it in onClientRender to keep it visible.
dxDrawWiredSphereDraws a wire sphere in the world (for debugging, e.g. a zone range). It is drawn on the screen, so it shows through walls.
dxGetBlendModeReturns the mode set with dxSetBlendMode ("blend" by default).
dxGetDefaultFontReturns the font set with dxSetDefaultFont in this resource or "default".
dxGetDrawPriorityReturns the current resource's dxSetDrawPriority setting: "overHud" (the default) or "underHud".
dxGetFontHeightReturns the height of one line of text in pixels for a scale and a font.
dxGetFontInfoReturns a font description: the typeface (family), the size in pixels (px) and points (size), style settings and the source.
dxGetFontListReturns the names of the built-in fonts: default, default-bold, clear, arial, sans, pricedown, bankgothic, diploma, beckett, unifont, inter, inter-medium, inter-semibold, inter-bold.
dxGetMaterialSizeReturns the width and height of a material: a texture, a render target, a browser or a shader.
dxGetPixelColorReturns the colour of pixel (x, y) from pixels in plain format.
dxGetPixelsFormatTells which format pixels are in: "plain", "png", "jpeg", "dds" or false.
dxGetPixelsSizeReturns the width and height of an image stored in pixels (any format).
dxGetStatusReturns the drawing state: the test mode, the resolution, the number of script textures, render targets and screen sources, and texture memory. Useful for finding texture leaks.
dxGetTextSizeReturns the width and height of a block of text, also when wrapped to a given width.
dxGetTexturePixelsReads the pixels of a texture, a render target or a screen source in plain, png or jpeg format, whole or from a section (x, y, width, height). For example for a screenshot.
dxGetTextWidthReturns the width of text in pixels for a given scale and font (like in dxDrawText). Useful for centring and boxes fitted to text.
dxImageSizeReturns the size of a resource image file in pixels, without creating a texture.
dxIsAspectRatioAdjustmentEnabledReturns the setting from dxSetAspectRatioAdjustmentEnabled.
dxSetAspectRatioAdjustmentEnabledTurns on drawing aspect ratio correction on wide screens. The value is stored for compatibility with existing scripts (dxIsAspectRatioAdjustmentEnabled) but does not change drawing; compute positions from guiGetScreenSize.
dxSetBlendModeSets the colour blending mode for drawing (blend, add, modulate_add, overwrite). The value is stored for compatibility with existing scripts (dxGetBlendMode), but drawing always uses normal blending.
dxSetDefaultFontSets the font dxDrawText uses when none is given, only in the current resource. nil restores the default.
dxSetDrawPrioritySets whether the resource's normal 2D drawings (dxDrawRectangle, dxDrawText, dxDrawImage, dxDrawLine and others without postGUI) are drawn above the game HUD and radar ("overHud", the default) or below them ("underHud"). The setting applies to the resource's next dxDraw* calls and stays until changed; every resource has its own. You can switch inside one onClientRender: some drawings below the HUD, some above it. Drawings with postGUI = true are always on top of everything.
dxSetFontStyleChanges the style of a font from dxCreateFont: bold, italic, underline, strike, weight, spacing, widthScale, shadow, outline, outlineColor, gradient, lineSpacing, size. Pass one key or a table.
dxSetPixelColorSets the colour of pixel (x, y) in plain pixels and changes the passed string. Images smaller than 4x4 are rejected.
dxSetRenderTargetSets where the dxDraw* functions draw: on a render target (optionally clearing it first) or, without an argument, on the screen. It only works in onClientRender and onClientPreRender; after the event drawing goes back to the screen.
dxSetTestModeTurns on a test mode to check that a script handles failures: "no_mem" (creating textures fails), "low_mem" (no effect), "no_shader" (dxCreateShader fails), "none" (off).
dxSetTextureEdgeSets what a texture shows outside its image in sections (dxDrawImageSection): repeat (wrap), mirror (mirror), stretched edge (clamp) or a border colour (border).
dxSetTexturePixelsWrites pixels (plain, png, jpeg) into a texture or a render target, whole or into a section.
dxUpdateScreenSourceRefreshes a screen source with the game image (without the script overlay). The image arrives 1-2 frames later.
getCameraRenderAttachedToReturns the element the camera is attached to.
getCameraRenderExposureReturns the camera's current brightness multiplier and whether it is automatic.
getCameraRenderFrameRateReturns the set number of shots per second (getCameraRenderInfo gives the measured one).
getCameraRenderInfoReturns the camera state: state, the number of frames in the texture (frames), measured shots per second (fps), whether the image arrives (ready), whether the attached element disappeared (attachLost) and an error (error).
getCameraRenderMatrixReturns the camera placement: x, y, z, the target, roll and field of view. For a camera attached to an element it gives the spot of the last shot.
getCameraRenderViewDistanceReturns the camera view distance in metres (0 = like the game).
getRecordingDataReturns the whole recording as an AVI (MJPEG) file in a string, e.g. for fileWrite, sending to the server or createRecordingFromData.
getRecordingFrameReturns the pixels of one recording frame (number from 1) in jpeg (default), png or plain format, e.g. for dxCreateTexture or saving a photo.
getRecordingInfoReturns recording information: whether it runs (recording), the frame count, frames per second, the length in ms (duration), the image size, the data size in bytes (size) and the stop reason (stopReason).
getRecordingPlayerPositionReturns the player position and the recording length in milliseconds.
getWorldPointOcclusionInfoReturns the occlusion check state: whether it is on (enabled), whether the game answers (available), the number of checks (checks), the queue (queue) and stored points (cached).
isCameraRecordingChecks whether the recording is still running (it stops by itself after the maximum time, a memory limit or when the camera is removed).
isCameraRenderChecks whether a value is a working camera from createCameraRender.
isCameraRenderMirroredChecks whether the camera image is mirrored.
isRecordingPlayerPlayingChecks whether the player is playing (not paused and not at the end without a loop).
isWorldPointOcclusionEnabledChecks whether isWorldPointVisible checks occlusion.
isWorldPointVisibleChecks whether a world point is on screen and not hidden by a building or terrain. Occlusion is checked in the background, so the result for a new point arrives after a moment. For 3D labels and markers that should not show through walls.
loadRecordingLoads a recording from a resource AVI (MJPEG) file.
renderCameraMatrixTakes one shot from the given spot (like setCameraRenderMatrix and updateCameraRender at once). The image appears in the texture 1-2 frames later; it also works at 0 shots per second.
saveRecordingSaves a recording to an AVI file in the resource (overwrites an existing one, like fileCreate).
setCameraRenderElementHiddenHides an element only in this camera's image, e.g. your own car in the mirror or the player holding a phone. The element's shadow stays. Up to 64 elements per camera.
setCameraRenderExposureSets the camera image brightness: "auto" (default, picks a 0.5-4 multiplier from the frame brightness like a camera) or a fixed 0.05-16 multiplier. The camera image has lifted shadows so it looks similar to the game at night.
setCameraRenderFrameRateSets how many shots per second the camera takes (0-60; 0 = only on request).
setCameraRenderMatrixPlaces the camera like setCameraMatrix: the position, the point it looks at, roll and field of view (5-170, 70 by default). It detaches the camera from an element.
setCameraRenderMirroredMirrors the camera image horizontally (a mirror). Also applies to recordings from this camera.
setCameraRenderViewDistanceSets the camera view distance in metres (0 = like the game). A shorter distance means a cheaper render, e.g. for a mirror.
setGroundDecalColorNewChanges the colour of a decal made with createGroundDecal.
setRecordingPlayerLoopedTurns looped playback on or off.
setRecordingPlayerPausedPauses or resumes a player. Resuming after the end starts from the beginning.
setRecordingPlayerPositionSeeks the player to a given millisecond of the recording.
setRecordingPlayerSpeedSets the playback speed 0-16 (1 = normal, 0.5 = slow motion).
setWorldPointOcclusionTurns occlusion checks in isWorldPointVisible on or off (false = points visible through walls, for debugging).
startCameraRecordingRecords the image of a camera from createCameraRender into memory (no sound). Returns a recording element. 1-60 frames per second, up to 600 seconds, JPEG quality 1-100. The camera should take at least as many shots per second as the recording, otherwise frames repeat.
stopCameraRecordingStops recording. The recording stays available for playback and saving. Returns false if it was no longer recording.
updateCameraRenderRequests one camera shot in the next frame (the image is in the texture 1-2 frames later).

Client events 3

onClientPreRenderArrives every frame before onClientRender, without drawing. It gets the time since the previous frame, so it suits smooth movement (cameras, animations).
onClientRenderTriggered every game frame. This is where you draw everything that should stay on screen: HUD, counters, text.
onClientScreenSizeChangeThe game resolution or window size changed. Recompute interface positions then.