Urho.Graphics Class

Graphics subsystem. Manages the application window, rendering state and GPU resources.

See Also: Graphics

Syntax

public class Graphics : UrhoObject

Remarks

Graphics implements the low-level functionality:

  • Creating the window and the rendering context.
  • Setting the screen mode.
  • Keeping track of GPU resources.
  • Keeping track of rendering context state (current rendertarget, vertex and index buffers, textures, shaders and renderstates)
  • Loading shaders.
  • Performing primitive rendering operations.
  • Handling disconnected GPUs.

The screen resolution, fullscreen or windowed mode, vertical sync and hardware multisampling level are all set at once by calling Graphics.SetMode

When setting the initial screen mode, Graphics does a few checks:

  • For Direct3D9, shader model 3.0 support is checked.
  • For OpenGL, version 3.2 support is checked for first and used if available. As a fallback, version 2.0 with EXT_framebuffer_object, EXT_packed_depth_stencil and EXT_texture_filter_anisotropic extensions is checked for. The ARB_instanced_arrays extension is also checked for but not required; it will enable hardware instancing support when present.
  • Are hardware shadow maps supported? Both AMD & NVIDIA style shadow maps can be used. If neither are available, no shadows will be rendered.
  • Are light pre-pass and deferred rendering modes supported? These require sufficient multiple rendertarget support, and R32F texture format support.

The actual rendering of 3D views is driven by the Renderer class.

Dealing with GPU Disconnetion

On Direct3D9 and Android OpenGL ES 2.0 it is possible to lose the rendering context (and therefore GPU resources) due to the application window being minimized or sent to the background.  

Additionally, to work around possible GPU driver bugs the desktop OpenGL context will be voluntarily destroyed and recreated when changing screen mode or toggling between fullscreen and windowed. Therefore, on all graphics APIs one must be prepared for losing GPU resources.

Textures that have been loaded from a file, as well as vertex & index buffers that have shadowing enabled will restore their contents automatically, the rest have to be restored manually. On Direct3D9 non-dynamic (managed) textures and buffers will never be lost, as the runtime automatically backs them up to system memory.

Shader Parameters

You can set parameters for the shaders by calling one of the M:Urho.Graphics.SetShaderParameter methods in this class.  In addition to controlling the shader parameters for your own shaders, you can use this to set the parameters for the various built-in shaders.

Some of the parameters that you can set for the built-in shaders are:

VSP
  • AmbientStartColor
  • AmbientEndColor
  • BillboardRot
  • CameraPos
  • ClipPlane
  • NearClip
  • FarClip
  • DepthMode
  • DeltaTime
  • ElapsedTime
  • FrustumSize
  • GBufferOffsets
  • LightDir
  • LightPos
  • NormalOffsetScale
  • Model
  • View
  • ViewInv
  • ViewProj
  • UOffset
  • VOffset
  • Zone
  • LightMatrices
  • SkinMatrices
  • VertexLights
PSP

  • AmbientColor
  • CameraPosPS
  • DeltaTimePS
  • DepthReconstruct
  • ElapsedTimePS
  • FogColor
  • FogParams
  • GBufferInvSize
  • LightColor
  • LightDirPS
  • LightPosPS
  • NormalOffsetScalePS
  • MatDiffColor
  • MatEmissiveColor
  • MatEnvMapColor
  • MatSpecColor
  • NearClipPS
  • FarClipPS
  • ShadowCubeAdjust
  • ShadowDepthFade
  • ShadowIntensity
  • ShadowMapInvSize
  • ShadowSplits
  • LightMatricesPS
  • VSMShadowParams
  • Roughness
  • Metallic
  • Requirements

    Namespace: Urho
    Assembly: Urho (in Urho.dll)
    Assembly Versions: 1.0.0.0

    The members of Urho.Graphics are listed below.

    See Also: UrhoObject

    Public Constructors

    Constructs a new instance of Urho.Graphics, given a raw pointer to an unmanaged object

    Protected Constructors

    Empty constructor, chain to this constructor when you provide your own constructor that sets the handle field.

    Public Properties

    [read-only]
    static
    AlphaFormatUInt32. Return the API-specific alpha texture format.
    [read-only]
    AlphaToCoverageBoolean. Return whether alpha-to-coverage is enabled.
    [read-only]
    ApiNameString. Return graphics API name.
    [read-only]
    BlendModeBlendMode. Return blending mode. Or Set blending mode.
    [read-only]
    BorderlessBoolean. Return whether window is borderless.
    ColorWriteBoolean. Return whether color write is enabled. Or Set color write on/off.
    CullModeCullMode. Return hardware culling mode. Or Set hardware culling mode.
    DefaultTextureAnisotropyUInt32. Return or Set default texture anisotropy level. Called by Renderer before rendering.
    DefaultTextureFilterModeTextureFilterMode. Return default texture filtering mode. Or Set default texture filtering mode.
    [read-only]
    DeferredSupportBoolean. Return whether deferred rendering is supported.
    [read-only]
    DepthConstantBiasSingle. Return depth constant bias.
    [read-only]
    DepthSlopeScaledBiasSingle. Return depth slope scaled bias.
    DepthStencilRenderSurface. Return depth-stencil surface. Or Set depth-stencil surface.
    [read-only]
    static
    DepthStencilFormatUInt32. Return the API-specific hardware depth-stencil texture format.
    DepthTestCompareMode. Return depth compare mode. Or Set depth compare.
    DepthWriteBoolean. Return whether depth write is enabled. Or Set depth write on/off.
    [read-only]
    DesktopResolutionIntVector2. Return the desktop resolution.
    [read-only]
    DeviceLostBoolean. Return whether device is lost, and can not yet render.
    DitherBoolean. Controls whether the rendering output is dithered. 
    [read-only]
    DummyColorFormatUInt32. Return dummy color texture format for shadow maps. 0 if not needed, may be nonzero on OS X to work around an Intel driver issue.
    ExternalWindowIntPtr. Return OS-specific external window handle. Null if not in use. Or Set external window handle. Only effective before setting the initial screen mode. On Windows it is necessary to set up OpenGL pixel format manually for the window.
    FillModeFillMode. Return polygon fill mode. Or Set polygon fill mode.
    [read-only]
    static
    Float16FormatUInt32. Return the API-specific single channel 16-bit float texture format.
    [read-only]
    static
    Float32FormatUInt32. Return the API-specific single channel 32-bit float texture format.
    FlushGPUBoolean. Return whether the GPU command buffer is flushed each frame. Not yet implemented on OpenGL. Or Set whether to flush the GPU command buffer to prevent multiple frames being queued and uneven frame timesteps. Not yet implemented on OpenGL.
    [read-only]
    FullscreenBoolean. Return whether window is fullscreen.
    [read-only]
    HardwareShadowSupportBoolean. Return whether shadow map depth compare is done in hardware. Always true on OpenGL.
    [read-only]
    HeightInt32. Return window height.
    [read-only]
    HighDPIBoolean. Return whether window is high DPI.
    [read-only]
    HiresShadowMapFormatUInt32. Return 24-bit shadow map depth texture format, or 0 if not supported.
    [read-only]
    ImplGraphicsImpl*. Return graphics implementation, which holds the actual API-specific resources.
    IndexBufferIndexBuffer. Return index buffer. Or Set index buffer.
    [read-only]
    InitializedBoolean. Return whether rendering initialized.
    [read-only]
    InstancingSupportBoolean. Return whether hardware instancing is supported.
    [read-only]
    LightPrepassSupportBoolean. Return whether light pre-pass rendering is supported.
    LineAntiAliasBoolean. Get or Set line antialiasing on/off.
    [read-only]
    static
    LinearDepthFormatUInt32. Return the API-specific linear depth texture format.
    [read-only]
    static
    LuminanceAlphaFormatUInt32. Return the API-specific luminance alpha texture format.
    [read-only]
    static
    LuminanceFormatUInt32. Return the API-specific luminance texture format.
    [read-only]
    static
    MaxBonesUInt32. Return maximum number of supported bones for skinning.
    [read-only]
    MultiSampleInt32. Return multisample mode (1 = no multisampling.)
    [read-only]
    NumBatchesUInt32. Return number of batches drawn this frame.
    [read-only]
    NumPrimitivesUInt32. Return number of primitives drawn this frame.
    OrientationsString. Return allowed screen orientations. Or Set allowed screen orientations as a space-separated list of "LandscapeLeft", "LandscapeRight", "Portrait" and "PortraitUpsideDown". Affects currently only iOS platform.
    [read-only]
    PixelShaderShaderVariation. Return pixel shader.
    [read-only]
    static
    PixelUVOffsetVector2. Return UV offset required for pixel perfect rendering.
    [read-only]
    static
    ReadableDepthFormatUInt32. Return the API-specific readable hardware depth format, or 0 if not supported.
    [read-only]
    ReadableDepthSupportBoolean. Return whether a readable hardware depth format is available.
    [read-only]
    RenderTargetDimensionsIntVector2. Return rendertarget width and height.
    [read-only]
    ResizableBoolean. Return whether window is resizable.
    [read-only]
    static
    RG16FormatUInt32. Return the API-specific RG 16-bit texture format.
    [read-only]
    static
    RGBA16FormatUInt32. Return the API-specific RGBA 16-bit texture format.
    [read-only]
    static
    RGBAFloat16FormatUInt32. Return the API-specific RGBA 16-bit float texture format.
    [read-only]
    static
    RGBAFloat32FormatUInt32. Return the API-specific RGBA 32-bit float texture format.
    [read-only]
    static
    RGBAFormatUInt32. Return the API-specific RGBA texture format.
    [read-only]
    static
    RGBFormatUInt32. Return the API-specific RGB texture format.
    [read-only]
    static
    RGFloat16FormatUInt32. Return the API-specific RG 16-bit float texture format.
    [read-only]
    static
    RGFloat32FormatUInt32. Return the API-specific RG 32-bit float texture format.
    [read-only]
    ScissorRectIntRect. Return scissor rectangle coordinates.
    [read-only]
    ScissorTestBoolean. Return whether scissor test is enabled.
    [read-only]
    SdlWindowIntPtr. Return pointer to SDL window.
    ShaderCacheDirString. Return or Set shader cache directory, Direct3D only. This can either be an absolute path or a path within the resource system.
    [read-only]
    ShadowMapFormatUInt32. Return shadow map depth texture format, or 0 if not supported.
    SRGBBoolean. Return whether the main window is using sRGB conversion on write. Or Set whether the main window uses sRGB conversion on write.
    [read-only]
    SRGBSupportBoolean. Return whether sRGB conversion on texture sampling is supported.
    [read-only]
    SRGBWriteSupportBoolean. Return whether sRGB conversion on rendertarget writing is supported.
    [read-only]
    StencilCompareMaskUInt32. Return stencil compare bitmask.
    [read-only]
    StencilFailStencilOp. Return stencil operation to do if stencil test fails.
    [read-only]
    StencilPassStencilOp. Return stencil operation to do if stencil test passes.
    [read-only]
    StencilRefUInt32. Return stencil reference value.
    [read-only]
    StencilTestBoolean. Return whether stencil test is enabled.
    [read-only]
    StencilTestModeCompareMode. Return stencil compare mode.
    [read-only]
    StencilWriteMaskUInt32. Return stencil write bitmask.
    [read-only]
    StencilZFailStencilOp. Return stencil operation to do if depth compare fails.
    [read-only]
    TripleBufferBoolean. Return whether triple buffering is enabled.
    [read-only]
    override
    TypeStringHash. Urho's type system type.
    [read-only]
    override
    TypeNameString. Urho's low-level type name.
    [read-only]
    static
    TypeNameStaticString. Urho's low-level type name, accessible as a static method.
    [read-only]
    static
    TypeStaticStringHash. Urho's low-level type, accessible as a static method.
    [read-only]
    UseClipPlaneBoolean. Return whether a custom clipping plane is in use.
    [read-only]
    VertexShaderShaderVariation. Return vertex shader.
    [read-only]
    ViewportIntRect. Return the viewport coordinates.
    [read-only]
    VSyncBoolean. Return whether vertical sync is on.
    [read-only]
    WidthInt32. Return window width.
    [read-only]
    WindowPositionIntVector2. Return window position.
    WindowTitleString. Return window title. Or Set window title.

    Public Methods

    AddGPUObject(GPUObject*)
    Add a GPU object to keep track of. Called by GPUObject.
    BeginDumpShaders(String)
    Begin dumping shader variation names to an XML file for precaching.
    BeginFrame() : Boolean
    Begin frame rendering. Return true if device available and can render.
    CleanupScratchBuffers()
    Clean up too large scratch buffers.
    Clear(UInt32, Color, Single, UInt32)
    Clear any or all of rendertarget, depth buffer and stencil buffer.
    ClearParameterSource(ShaderParameterGroup)
    Clear remembered shader parameter source group.
    ClearParameterSources()
    Clear remembered shader parameter sources.
    ClearTransformSources()
    Clear remembered transform shader parameter sources.
    Close()
    Close the window.
    Draw(PrimitiveType, UInt32, UInt32)
    Draw non-indexed geometry.
    Draw(PrimitiveType, UInt32, UInt32, UInt32, UInt32)
    Draw indexed geometry.
    Draw(PrimitiveType, UInt32, UInt32, UInt32, UInt32, UInt32)
    Draw indexed geometry with vertex index offset.
    DrawInstanced(PrimitiveType, UInt32, UInt32, UInt32, UInt32, UInt32)
    Draw indexed, instanced geometry.
    DrawInstanced(PrimitiveType, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32)
    Draw indexed, instanced geometry with vertex index offset.
    EndDumpShaders()
    End dumping shader variations names.
    EndFrame()
    End frame rendering and swap buffers.
    FreeScratchBuffer(IntPtr)
    Free a CPU-side scratch buffer.
    static
    GetFormat(String) : UInt32
    Return the API-specific texture format from a textual description, for example "rgb".
    GetFormat(CompressedFormat) : UInt32
    Return hardware format for a compressed image format, or 0 if unsupported.
    GetRenderTarget(UInt32) : RenderSurface
    Return rendertarget by index.
    GetShader(ShaderType, String, String) : ShaderVariation
    Return a shader variation by name and defines.
    GetTexture(UInt32) : Texture
    Return texture by texture unit index.
    GetTextureUnit(String) : TextureUnit
    Return texture unit index by name.
    GetTextureUnitName(TextureUnit) : String
    Return texture unit name by index.
    GetVertexBuffer(UInt32) : VertexBuffer
    Return current vertex buffer by index.
    HasShaderParameter(StringHash) : Boolean
    Check whether a shader parameter exists on the currently set shaders.
    HasTextureUnit(TextureUnit) : Boolean
    Check whether the current shader program uses a texture unit.
    Maximize()
    Maximize the Window.
    Minimize()
    Minimize the Window.
    NeedParameterUpdate(ShaderParameterGroup, Void*) : Boolean
    Check whether a shader parameter group needs update. Does not actually check whether parameters exist in the shaders.
    OnWindowMoved()
    Window was moved through user interaction. 
    OnWindowResized()
    React to window resize.
    PrecacheShaders(File)
    Precache shader variations from an XML file generated with BeginDumpShaders().
    PrecacheShaders(MemoryBuffer)
    RemoveGPUObject(GPUObject*)
    Remove a GPU object. Called by GPUObject.
    ReserveScratchBuffer(UInt32) : IntPtr
    Reserve a CPU-side scratch buffer.
    ResetDepthStencil()
    Reset depth-stencil surface.
    ResetRenderTarget(UInt32)
    Reset specific rendertarget.
    ResetRenderTargets()
    Reset all rendertargets, depth-stencil surface and viewport.
    ResolveToTexture(TextureCube) : Boolean
    Resolve a multisampled cube texture on itself.
    ResolveToTexture(Texture2D) : Boolean
    Resolve a multisampled texture on itself.
    ResolveToTexture(Texture2D, IntRect) : Boolean
    Resolve multisampled backbuffer to a texture rendertarget. The texture's size should match the viewport size.
    SetBlendMode(BlendMode, Boolean)
    Set blending and alpha-to-coverage modes. Alpha-to-coverage is not supported on Direct3D9.
    SetClipPlane(Boolean, Plane, Matrix3x4, Matrix4)
    Set a custom clipping plane. The plane is specified in world space, but is dependent on the view and projection matrices.
    SetDepthBias(Single, Single)
    Set depth bias.
    SetDepthStencil(Texture2D)
    Set depth-stencil surface.
    SetMode(Int32, Int32) : Boolean
    Set screen resolution only. Return true if successful.
    SetMode(Int32, Int32, Boolean, Boolean, Boolean, Boolean, Boolean, Boolean, Int32) : Boolean
    Set screen mode. Return true if successful.
    SetRenderTarget(UInt32, RenderSurface)
    Set rendertarget.
    SetRenderTarget(UInt32, Texture2D)
    Set rendertarget.
    SetScissorTest(Boolean, IntRect)
    Set scissor test.
    SetShaderParameter(StringHash, Boolean)
    Set shader boolean constant.
    SetShaderParameter(StringHash, Int32)
    Set shader integer constant.
    SetShaderParameter(StringHash, Single)
    Set shader float constant.
    SetShaderParameter(StringHash, Color)
    Set shader color constant.
    SetShaderParameter(StringHash, Matrix3x4)
    Set shader matrix constant.
    SetShaderParameter(StringHash, Matrix4)
    Set shader matrix constant.
    SetShaderParameter(StringHash, Vector2)
    Set shader 2D vector constant.
    SetShaderParameter(StringHash, Vector3)
    Set shader 3D vector constant.
    SetShaderParameter(StringHash, Vector4)
    Set shader 4D vector constant.
    SetShaderParameter(StringHash, Single*, UInt32)
    Set shader float constants.
    SetShaders(ShaderVariation, ShaderVariation)
    Set shaders.
    SetStencilTest(Boolean, CompareMode, StencilOp, StencilOp, StencilOp, UInt32, UInt32, UInt32)
    Set stencil test.
    SetStereo(Boolean)
    Internal use.
    SetTexture(UInt32, Texture)
    Set texture.
    SetTextureParametersDirty()
    Dirty texture parameters of all textures (when global settings change.)
    SetVertexBuffer(VertexBuffer)
    Set vertex buffer.
    SetViewport(IntRect)
    Set viewport.
    SetWindowIcon(Image)
    Set window icon.
    SetWindowPosition(IntVector2)
    Set window position.
    SetWindowPosition(Int32, Int32)
    Set window position.
    TakeScreenShot(Image) : Boolean
    Take a screenshot. Return true if successful.
    ToggleFullscreen() : Boolean
    Toggle between full screen and windowed mode. Return true if successful.