Garry's Mod Wiki

surface

The surface library allows you to draw text and shapes on the screen. Primarily used for making HUDs & custom GUI panels.

Methods

surface.CreateFont( string fontName, table fontData )
Creates a new font. To prevent the font from displaying incorrectly when using the outline setting, set antialias to false. This will ensure the text properly fills out the entire outline. Be sure to check the List of Default Fonts first! Those fonts can be used without using this function. See Also: Finding the Font Name. Due to the static nature of fonts, do NOT create the font more than once. You should only be creating them once, it is recommended to create them at the top of your script. Do not use this function within GM:HUDPaint or any other hook! Define fonts that you will actually use, as fonts are very taxing on performance and will cause crashes! Do not create fonts for every size.
boolean surface.DisableClipping( boolean disable )
We advise against using this. It may be changed or removed in a future update. Alias of DisableClipping so use that instead. Enables or disables the clipping used by the VGUI that limits the drawing operations to a panels bounds. Identical to DisableClipping. See also Panel:NoClipping.
surface.DrawCircle( number originX, number originY, number radius, number r, number g, number b, number a = 255 )
Draws a hollow circle, made of lines. For a filled circle, see examples for surface. DrawPoly. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawLine( number startX, number startY, number endX, number endY )
Draws a line from one point to another. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawOutlinedRect( number x, number y, number w, number h, number thickness = 1 )
Draws a hollow box with a given border width. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawPoly( table vertices )
Draws a textured polygon (secretly a triangle fan) with a maximum of 4096 vertices. Only works properly with convex polygons. You may try to render concave polygons, but there is no guarantee that things wont get messed up. Unlike most surface library functions, non-integer coordinates are not rounded. You must reset the drawing color and texture before calling the function to ensure consistent results. See examples below. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawRect( number x, number y, number width, number height )
Draws a solid rectangle on the screen. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawText( string text, boolean forceAdditive = nil )
Draw the specified text on the screen, using the previously set position, font and color. This function does not handle newlines. This function moves the text position by the length of the drawn text - this can be used to change text properties (such as font or color) without having to manually recalculate the text position. See example #2 for example use of this behavior. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawTexturedRect( number x, number y, number width, number height )
Draw a textured rectangle with the given position and dimensions on the screen, using the current active texture set with surface. SetMaterial. It is also affected by surface. SetDrawColor. See also render. SetMaterial and render. DrawScreenQuadEx. See also surface. DrawTexturedRectUV. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawTexturedRectRotated( number x, number y, number width, number height, number rotation )
Draw a textured rotated rectangle with the given position and dimensions and angle on the screen, using the current active texture. This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks.
surface.DrawTexturedRectUV( number x, number y, number width, number height, number startU, number startV, number endU, number endV )
Draws a textured rectangle with a repeated or partial texture. u and v refer to texture coordinates. (u, v) = (0, 0) is the top left (u, v) = (1, 0) is the top right (u, v) = (1, 1) is the bottom right (u, v) = (0, 1) is the bottom left Using a start point of (1, 0) and an end point to (0, 1), you can draw an image flipped horizontally, same goes with other directions. Going above 1 will tile the texture. Negative values are allowed as well. Here's a helper image: If you are using a . png image, you need supply the "noclamp" flag as second parameter for Material if you intend to use tiling. If you find that surface. DrawTexturedRectUV is getting your texture coordinates (u0, v0), (u1, v1) wrong and you're rendering with a material created with CreateMaterial, try adjusting them with the following code: local du = 0. 5 / 32 -- half pixel anticorrection local dv = 0. 5 / 32 -- half pixel anticorrection local u0, v0 = (u0 - du) / (1 - 2 * du), (v0 - dv) / (1 - 2 * dv) local u1, v1 = (u1 - du) / (1 - 2 * du), (v1 - dv) / (1 - 2 * dv) Explanation: surface. DrawTexturedRectUV tries to correct the texture coordinates by half a pixel (something to do with sampling) and computes the correction using IMaterial::GetMappingWidth()/GetMappingHeight(). If the material was created without a $basetexture, then GetMappingWidth()/GetMappingHeight() uses the width and height of the error material (which is 32x32). This is a rendering function that requires a 2d rendering context. This means that it will only work in 2d Rendering Hooks. The UV offsets might require (sub-)pixel correction for accurate tiling results. Issue Tracker: 3173
Returns the current alpha multiplier affecting drawing operations. This is set by surface. SetAlphaMultiplier or by the game engine in certain other cases.
Returns the current color affecting draw operations. The returned color will not have the color metatable. Issue Tracker: 2407
number surface.GetHUDTexture( string name )
Gets the HUD icon TextureID with the specified name.
Returns the current color affecting text draw operations. The returned color will not have the color metatable. Issue Tracker: 2407
Returns the X and Y co-ordinate that has been set with surface. SetTextPos or changed by surface. DrawText.
number, number surface.GetTextSize( string text )
Returns the width and height (in pixels) of the given text with the font that has been set with surface. SetFont. Does not take into account new lines, the returned height is for the entire font (as specified by the font), not maximum of individual characters.
number surface.GetTextureID( string name/path )
Returns the texture id of the material with the given name/path, for use with surface. SetTexture. Opposite version of this function is surface. GetTextureNameByID. This function will not work with . png or . jpg images. For that, see Material. You will probably want to use it regardless.
Returns name/path of texture by ID. Opposite version of this function is surface. GetTextureID.
number, number surface.GetTextureSize( number textureID )
Returns the size of the texture with the associated texture ID. For . png/. jpg textures loaded with Material you can use the $realheight and $realwidth material parameters (IMaterial:GetInt) to get the size of the image.
surface.PlaySound( string soundfile )
Play a sound file directly on the client (such as UI sounds, etc). Valid sample rates: 11025 Hz, 22050 Hz and 44100 Hz, otherwise you may see this kind of message: Unsupported 32-bit wave file your_sound. wav and Invalid sample rate (48000) for sound 'your_sound. wav'
We advise against using this. It may be changed or removed in a future update. You should use ScrH instead. Returns the height of the current client's screen.
We advise against using this. It may be changed or removed in a future update. You should use ScrW instead. Returns the width of the current client's screen.
surface.SetAlphaMultiplier( number multiplier )
Sets the alpha multiplier that will influence all upcoming drawing operations. See also render. SetBlend.
surface.SetDrawColor( number r, number g, number b, number a = 255 )
Set the color of any future shapes to be drawn, can be set by either using R, G, B, A as separate values or by a Color. Using a color structure is not recommended to be created procedurally. Providing a Color structure is slower than providing four numbers. You may use Color:Unpack for this. The alpha value may not work properly if you're using a material without $vertexalpha. Due to post processing and gamma correction the color you set with this function may appear differently when rendered. This problem does not occur on materials drawn with surface. DrawTexturedRect.
surface.SetFont( string fontName )
Set the current font to be used for text operations later. The fonts must first be created with surface. CreateFont or be one of the Default Fonts.
surface.SetMaterial( IMaterial material )
Sets the material to be used in all upcoming draw operations using the surface library. Not to be confused with render. SetMaterial. If you need to unset the texture, use the draw. NoTexture convenience function. Material function calls are expensive to be done inside this function or inside rendering context, you should be caching the results of Material callsWhen using render. PushRenderTarget or render. SetRenderTarget, material should have the $ignorez flag set to make it visible. If the material is not used in 3D rendering, it is probably safe to add it with this code: material:SetInt( "$flags", bit. bor( material:GetInt( "$flags" ), 32768 ) )
surface.SetTextColor( number r, number g, number b, number a = 255 )
Set the color of any future text to be drawn, can be set by either using R, G, B, A as separate numbers or by a Color. Using a color structure is not recommended to be created procedurally. Providing a Color structure is slower than providing four numbers. You may use Color:Unpack for this.
surface.SetTextPos( number x, number y )
Set the top-left position to draw any future text at.
surface.SetTexture( number textureID )
Sets the texture to be used in all upcoming draw operations using the surface library. See surface. SetMaterial for an IMaterial alternative. It's probably best to use the alternative mentioned above.