VisualServer¶
Inherits: Object
Server for anything visible.
Description¶
Server for anything visible. The visual server is the API backend for everything visible. The whole scene system mounts on it to display.
The visual server is completely opaque, the internals are entirely implementation specific and cannot be accessed.
The visual server can be used to bypass the scene system entirely.
Resources are created using the *_create functions.
All objects are drawn to a viewport. You can use the Viewport attached to the SceneTree or you can create one yourself with viewport_create. When using a custom scenario or canvas, the scenario or canvas needs to be attached to the viewport using viewport_set_scenario or viewport_attach_canvas.
In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the visual server from a running game, the scenario can be accessed from the scene tree from any Spatial node with Spatial.get_world. Otherwise, a scenario can be created with scenario_create.
Similarly, in 2D, a canvas is needed to draw all canvas items.
In 3D, all visible objects are comprised of a resource and an instance. A resource can be a mesh, a particle system, a light, or any other 3D object. In order to be visible resources must be attached to an instance using instance_set_base. The instance must also be attached to the scenario using instance_set_scenario in order to be visible.
In 2D, all visible objects are some form of canvas item. In order to be visible, a canvas item needs to be the child of a canvas attached to a viewport, or it needs to be the child of another canvas item that is eventually attached to the canvas.
Tutorials¶
Properties¶
Methods¶
Signals¶
frame_post_draw ( )
Emitted at the end of the frame, after the VisualServer has finished updating all the Viewports.
frame_pre_draw ( )
Emitted at the beginning of the frame, before the VisualServer updates all the Viewports.
Enumerations¶
enum CubeMapSide:
CUBEMAP_LEFT = 0 --- Marks the left side of a cubemap.
CUBEMAP_RIGHT = 1 --- Marks the right side of a cubemap.
CUBEMAP_BOTTOM = 2 --- Marks the bottom side of a cubemap.
CUBEMAP_TOP = 3 --- Marks the top side of a cubemap.
CUBEMAP_FRONT = 4 --- Marks the front side of a cubemap.
CUBEMAP_BACK = 5 --- Marks the back side of a cubemap.
enum TextureType:
TEXTURE_TYPE_2D = 0 --- Normal texture with 2 dimensions, width and height.
TEXTURE_TYPE_CUBEMAP = 2 --- Texture made up of six faces, can be looked up with a
vec3in shader.TEXTURE_TYPE_2D_ARRAY = 3 --- An array of 2-dimensional textures.
TEXTURE_TYPE_3D = 4 --- A 3-dimensional texture with width, height, and depth.
enum TextureFlags:
TEXTURE_FLAG_MIPMAPS = 1 --- Generates mipmaps, which are smaller versions of the same texture to use when zoomed out, keeping the aspect ratio.
TEXTURE_FLAG_REPEAT = 2 --- Repeats the texture (instead of clamp to edge).
TEXTURE_FLAG_FILTER = 4 --- Uses a magnifying filter, to enable smooth zooming in of the texture.
TEXTURE_FLAG_ANISOTROPIC_FILTER = 8 --- Uses anisotropic mipmap filtering. Generates smaller versions of the same texture with different aspect ratios.
This results in better-looking textures when viewed from oblique angles.
TEXTURE_FLAG_CONVERT_TO_LINEAR = 16 --- Converts the texture to the sRGB color space.
TEXTURE_FLAG_MIRRORED_REPEAT = 32 --- Repeats the texture with alternate sections mirrored.
TEXTURE_FLAG_USED_FOR_STREAMING = 2048 --- Texture is a video surface.
TEXTURE_FLAGS_DEFAULT = 7 --- Default flags. TEXTURE_FLAG_MIPMAPS, TEXTURE_FLAG_REPEAT and TEXTURE_FLAG_FILTER are enabled.
enum ShaderMode:
SHADER_SPATIAL = 0 --- Shader is a 3D shader.
SHADER_CANVAS_ITEM = 1 --- Shader is a 2D shader.
SHADER_PARTICLES = 2 --- Shader is a particle shader.
SHADER_MAX = 3 --- Represents the size of the ShaderMode enum.
enum ArrayType:
ARRAY_VERTEX = 0 --- Array is a vertex array.
ARRAY_NORMAL = 1 --- Array is a normal array.
ARRAY_TANGENT = 2 --- Array is a tangent array.
ARRAY_COLOR = 3 --- Array is a color array.
ARRAY_TEX_UV = 4 --- Array is an UV coordinates array.
ARRAY_TEX_UV2 = 5 --- Array is an UV coordinates array for the second UV coordinates.
ARRAY_BONES = 6 --- Array contains bone information.
ARRAY_WEIGHTS = 7 --- Array is weight information.
ARRAY_INDEX = 8 --- Array is index array.
ARRAY_MAX = 9 --- Represents the size of the ArrayType enum.
enum ArrayFormat:
ARRAY_FORMAT_VERTEX = 1 --- Flag used to mark a vertex array.
ARRAY_FORMAT_NORMAL = 2 --- Flag used to mark a normal array.
ARRAY_FORMAT_TANGENT = 4 --- Flag used to mark a tangent array.
ARRAY_FORMAT_COLOR = 8 --- Flag used to mark a color array.
ARRAY_FORMAT_TEX_UV = 16 --- Flag used to mark an UV coordinates array.
ARRAY_FORMAT_TEX_UV2 = 32 --- Flag used to mark an UV coordinates array for the second UV coordinates.
ARRAY_FORMAT_BONES = 64 --- Flag used to mark a bone information array.
ARRAY_FORMAT_WEIGHTS = 128 --- Flag used to mark a weights array.
ARRAY_FORMAT_INDEX = 256 --- Flag used to mark an index array.
ARRAY_COMPRESS_VERTEX = 512 --- Flag used to mark a compressed (half float) vertex array.
ARRAY_COMPRESS_NORMAL = 1024 --- Flag used to mark a compressed (half float) normal array.
ARRAY_COMPRESS_TANGENT = 2048 --- Flag used to mark a compressed (half float) tangent array.
ARRAY_COMPRESS_COLOR = 4096 --- Flag used to mark a compressed (half float) color array.
ARRAY_COMPRESS_TEX_UV = 8192 --- Flag used to mark a compressed (half float) UV coordinates array.
ARRAY_COMPRESS_TEX_UV2 = 16384 --- Flag used to mark a compressed (half float) UV coordinates array for the second UV coordinates.
ARRAY_COMPRESS_BONES = 32768 --- Flag used to mark a compressed bone array.
ARRAY_COMPRESS_WEIGHTS = 65536 --- Flag used to mark a compressed (half float) weight array.
ARRAY_COMPRESS_INDEX = 131072 --- Flag used to mark a compressed index array.
ARRAY_FLAG_USE_2D_VERTICES = 262144 --- Flag used to mark that the array contains 2D vertices.
ARRAY_FLAG_USE_16_BIT_BONES = 524288 --- Flag used to mark that the array uses 16-bit bones instead of 8-bit.
ARRAY_FLAG_USE_OCTAHEDRAL_COMPRESSION = 2097152 --- Flag used to mark that the array uses an octahedral representation of normal and tangent vectors rather than cartesian.
ARRAY_COMPRESS_DEFAULT = 2194432 --- Used to set flags ARRAY_COMPRESS_NORMAL, ARRAY_COMPRESS_TANGENT, ARRAY_COMPRESS_COLOR, ARRAY_COMPRESS_TEX_UV, ARRAY_COMPRESS_TEX_UV2, ARRAY_COMPRESS_WEIGHTS, and ARRAY_FLAG_USE_OCTAHEDRAL_COMPRESSION quickly.
enum PrimitiveType:
PRIMITIVE_POINTS = 0 --- Primitive to draw consists of points.
PRIMITIVE_LINES = 1 --- Primitive to draw consists of lines.
PRIMITIVE_LINE_STRIP = 2 --- Primitive to draw consists of a line strip from start to end.
PRIMITIVE_LINE_LOOP = 3 --- Primitive to draw consists of a line loop (a line strip with a line between the last and the first vertex).
PRIMITIVE_TRIANGLES = 4 --- Primitive to draw consists of triangles.
PRIMITIVE_TRIANGLE_STRIP = 5 --- Primitive to draw consists of a triangle strip (the last 3 vertices are always combined to make a triangle).
PRIMITIVE_TRIANGLE_FAN = 6 --- Primitive to draw consists of a triangle strip (the last 2 vertices are always combined with the first to make a triangle).
PRIMITIVE_MAX = 7 --- Represents the size of the PrimitiveType enum.
enum BlendShapeMode:
BLEND_SHAPE_MODE_NORMALIZED = 0 --- Blend shapes are normalized.
BLEND_SHAPE_MODE_RELATIVE = 1 --- Blend shapes are relative to base weight.
enum LightType:
LIGHT_DIRECTIONAL = 0 --- Is a directional (sun) light.
LIGHT_OMNI = 1 --- Is an omni light.
LIGHT_SPOT = 2 --- Is a spot light.
enum LightParam:
LIGHT_PARAM_ENERGY = 0 --- The light's energy.
LIGHT_PARAM_INDIRECT_ENERGY = 1 --- Secondary multiplier used with indirect light (light bounces).
LIGHT_PARAM_SIZE = 2 --- The light's size, currently only used for soft shadows in baked lightmaps.
LIGHT_PARAM_SPECULAR = 3 --- The light's influence on specularity.
LIGHT_PARAM_RANGE = 4 --- The light's range.
LIGHT_PARAM_ATTENUATION = 5 --- The light's attenuation.
LIGHT_PARAM_SPOT_ANGLE = 6 --- The spotlight's angle.
LIGHT_PARAM_SPOT_ATTENUATION = 7 --- The spotlight's attenuation.
LIGHT_PARAM_CONTACT_SHADOW_SIZE = 8 --- Scales the shadow color.
LIGHT_PARAM_SHADOW_MAX_DISTANCE = 9 --- Max distance that shadows will be rendered.
LIGHT_PARAM_SHADOW_SPLIT_1_OFFSET = 10 --- Proportion of shadow atlas occupied by the first split.
LIGHT_PARAM_SHADOW_SPLIT_2_OFFSET = 11 --- Proportion of shadow atlas occupied by the second split.
LIGHT_PARAM_SHADOW_SPLIT_3_OFFSET = 12 --- Proportion of shadow atlas occupied by the third split. The fourth split occupies the rest.
LIGHT_PARAM_SHADOW_NORMAL_BIAS = 13 --- Normal bias used to offset shadow lookup by object normal. Can be used to fix self-shadowing artifacts.
LIGHT_PARAM_SHADOW_BIAS = 14 --- Bias the shadow lookup to fix self-shadowing artifacts.
LIGHT_PARAM_SHADOW_BIAS_SPLIT_SCALE = 15 --- Increases bias on further splits to fix self-shadowing that only occurs far away from the camera.
LIGHT_PARAM_MAX = 16 --- Represents the size of the LightParam enum.
enum LightBakeMode:
LIGHT_BAKE_DISABLED = 0
LIGHT_BAKE_INDIRECT = 1
LIGHT_BAKE_ALL = 2
enum LightOmniShadowMode:
LIGHT_OMNI_SHADOW_DUAL_PARABOLOID = 0 --- Use a dual paraboloid shadow map for omni lights.
LIGHT_OMNI_SHADOW_CUBE = 1 --- Use a cubemap shadow map for omni lights. Slower but better quality than dual paraboloid.
enum LightOmniShadowDetail:
LIGHT_OMNI_SHADOW_DETAIL_VERTICAL = 0 --- Use more detail vertically when computing shadow map.
LIGHT_OMNI_SHADOW_DETAIL_HORIZONTAL = 1 --- Use more detail horizontally when computing shadow map.
enum LightDirectionalShadowMode:
LIGHT_DIRECTIONAL_SHADOW_ORTHOGONAL = 0 --- Use orthogonal shadow projection for directional light.
LIGHT_DIRECTIONAL_SHADOW_PARALLEL_2_SPLITS = 1 --- Use 2 splits for shadow projection when using directional light.
LIGHT_DIRECTIONAL_SHADOW_PARALLEL_4_SPLITS = 2 --- Use 4 splits for shadow projection when using directional light.
enum LightDirectionalShadowDepthRangeMode:
LIGHT_DIRECTIONAL_SHADOW_DEPTH_RANGE_STABLE = 0 --- Keeps shadows stable as camera moves but has lower effective resolution.
LIGHT_DIRECTIONAL_SHADOW_DEPTH_RANGE_OPTIMIZED = 1 --- Optimize use of shadow maps, increasing the effective resolution. But may result in shadows moving or flickering slightly.
enum ViewportUpdateMode:
VIEWPORT_UPDATE_DISABLED = 0 --- Do not update the viewport.
VIEWPORT_UPDATE_ONCE = 1 --- Update the viewport once then set to disabled.
VIEWPORT_UPDATE_WHEN_VISIBLE = 2 --- Update the viewport whenever it is visible.
VIEWPORT_UPDATE_ALWAYS = 3 --- Always update the viewport.
enum ViewportClearMode:
VIEWPORT_CLEAR_ALWAYS = 0 --- The viewport is always cleared before drawing.
VIEWPORT_CLEAR_NEVER = 1 --- The viewport is never cleared before drawing.
VIEWPORT_CLEAR_ONLY_NEXT_FRAME = 2 --- The viewport is cleared once, then the clear mode is set to VIEWPORT_CLEAR_NEVER.
enum ViewportMSAA:
VIEWPORT_MSAA_DISABLED = 0 --- Multisample antialiasing is disabled.
VIEWPORT_MSAA_2X = 1 --- Multisample antialiasing is set to 2×.
VIEWPORT_MSAA_4X = 2 --- Multisample antialiasing is set to 4×.
VIEWPORT_MSAA_8X = 3 --- Multisample antialiasing is set to 8×.
VIEWPORT_MSAA_16X = 4 --- Multisample antialiasing is set to 16×.
VIEWPORT_MSAA_EXT_2X = 5 --- Multisample antialiasing is set to 2× on external texture. Special mode for GLES2 Android VR (Oculus Quest and Go).
VIEWPORT_MSAA_EXT_4X = 6 --- Multisample antialiasing is set to 4× on external texture. Special mode for GLES2 Android VR (Oculus Quest and Go).
enum ViewportUsage:
VIEWPORT_USAGE_2D = 0 --- The Viewport does not render 3D but samples.
VIEWPORT_USAGE_2D_NO_SAMPLING = 1 --- The Viewport does not render 3D and does not sample.
VIEWPORT_USAGE_3D = 2 --- The Viewport renders 3D with effects.
VIEWPORT_USAGE_3D_NO_EFFECTS = 3 --- The Viewport renders 3D but without effects.
enum ViewportRenderInfo:
VIEWPORT_RENDER_INFO_OBJECTS_IN_FRAME = 0 --- Number of objects drawn in a single frame.
VIEWPORT_RENDER_INFO_VERTICES_IN_FRAME = 1 --- Number of vertices drawn in a single frame.
VIEWPORT_RENDER_INFO_MATERIAL_CHANGES_IN_FRAME = 2 --- Number of material changes during this frame.
VIEWPORT_RENDER_INFO_SHADER_CHANGES_IN_FRAME = 3 --- Number of shader changes during this frame.
VIEWPORT_RENDER_INFO_SURFACE_CHANGES_IN_FRAME = 4 --- Number of surface changes during this frame.
VIEWPORT_RENDER_INFO_DRAW_CALLS_IN_FRAME = 5 --- Number of draw calls during this frame.
VIEWPORT_RENDER_INFO_2D_ITEMS_IN_FRAME = 6 --- Number of 2d items drawn this frame.
VIEWPORT_RENDER_INFO_2D_DRAW_CALLS_IN_FRAME = 7 --- Number of 2d draw calls during this frame.
VIEWPORT_RENDER_INFO_MAX = 8 --- Represents the size of the ViewportRenderInfo enum.
enum ViewportDebugDraw:
VIEWPORT_DEBUG_DRAW_DISABLED = 0 --- Debug draw is disabled. Default setting.
VIEWPORT_DEBUG_DRAW_UNSHADED = 1 --- Debug draw sets objects to unshaded.
VIEWPORT_DEBUG_DRAW_OVERDRAW = 2 --- Overwrites clear color to
(0,0,0,0).VIEWPORT_DEBUG_DRAW_WIREFRAME = 3 --- Debug draw draws objects in wireframe.
enum ScenarioDebugMode:
SCENARIO_DEBUG_DISABLED = 0 --- Do not use a debug mode.
SCENARIO_DEBUG_WIREFRAME = 1 --- Draw all objects as wireframe models.
SCENARIO_DEBUG_OVERDRAW = 2 --- Draw all objects in a way that displays how much overdraw is occurring. Overdraw occurs when a section of pixels is drawn and shaded and then another object covers it up. To optimize a scene, you should reduce overdraw.
SCENARIO_DEBUG_SHADELESS = 3 --- Draw all objects without shading. Equivalent to setting all objects shaders to
unshaded.
enum InstanceType:
INSTANCE_NONE = 0 --- The instance does not have a type.
INSTANCE_MESH = 1 --- The instance is a mesh.
INSTANCE_MULTIMESH = 2 --- The instance is a multimesh.
INSTANCE_IMMEDIATE = 3 --- The instance is an immediate geometry.
INSTANCE_PARTICLES = 4 --- The instance is a particle emitter.
INSTANCE_LIGHT = 5 --- The instance is a light.
INSTANCE_REFLECTION_PROBE = 6 --- The instance is a reflection probe.
INSTANCE_GI_PROBE = 7 --- The instance is a GI probe.
INSTANCE_LIGHTMAP_CAPTURE = 8 --- The instance is a lightmap capture.
INSTANCE_MAX = 9 --- Represents the size of the InstanceType enum.
INSTANCE_GEOMETRY_MASK = 30 --- A combination of the flags of geometry instances (mesh, multimesh, immediate and particles).
enum InstanceFlags:
INSTANCE_FLAG_USE_BAKED_LIGHT = 0 --- Allows the instance to be used in baked lighting.
INSTANCE_FLAG_DRAW_NEXT_FRAME_IF_VISIBLE = 1 --- When set, manually requests to draw geometry on next frame.
INSTANCE_FLAG_MAX = 2 --- Represents the size of the InstanceFlags enum.
enum ShadowCastingSetting:
SHADOW_CASTING_SETTING_OFF = 0 --- Disable shadows from this instance.
SHADOW_CASTING_SETTING_ON = 1 --- Cast shadows from this instance.
SHADOW_CASTING_SETTING_DOUBLE_SIDED = 2 --- Disable backface culling when rendering the shadow of the object. This is slightly slower but may result in more correct shadows.
SHADOW_CASTING_SETTING_SHADOWS_ONLY = 3 --- Only render the shadows from the object. The object itself will not be drawn.
enum NinePatchAxisMode:
NINE_PATCH_STRETCH = 0 --- The nine patch gets stretched where needed.
NINE_PATCH_TILE = 1 --- The ni