ViewportWidget::EnableViewportTexture

Defined in: C4Viewports.h

Allocates a texture map used to hold the image rendered in a viewport widget.

Prototype

void EnableViewportTexture(bool staticFlag);

Parameters

staticFlag Indicates whether the viewport is usually static and can be rendered with the existing texture image.

Description

The EnableViewportTexture function allocates an internal texture map that is used to hold the image rendered into a viewport by the rendering callback function installed with the ViewportWidget::SetTextureRenderCallback function.

The staticFlag parameter determines whether the texture image can be used as a cache from which to render the viewport when its contents are not changing. If the process of rendering the contents of the viewport is expensive, this caching mechanism can improve performance significantly. Once an image has been cached in the texture map, the texture rendering callback function is no longer called until the texture map is invalidated using the ViewportWidget::InvalidateViewportTexture function. Instead, the image in the texture map is drawn by rendering a single quad that covers the viewport.

If a direct rendering callback function has been installed with the ViewportWidget::SetDirectRenderCallback function, then it continues to be called once per frame regardless of whether the viewport image is cached in a texture map. This allows lower-cost dynamic objects to be rendered on top of a high-cost static scene.

The texture map can be removed by calling the ViewportWidget::DisableViewportTexture function, and this stops the texture rendering callback function from being called.