set_offscreen_redirect

Defines the circumstances where the actor should be redirected into an offscreen image.

The offscreen image is used to flatten the actor into a single image while painting for two main reasons. Firstly, when the actor is painted a second time without any of its contents changing it can simply repaint the cached image without descending further down the actor hierarchy. Secondly, it will make the opacity look correct even if there are overlapping primitives in the actor.

Caching the actor could in some cases be a performance win and in some cases be a performance lose so it is important to determine which value is right for an actor before modifying this value. For example, there is never any reason to flatten an actor that is just a single texture (such as a Texture) because it is effectively already cached in an image so the offscreen would be redundant. Also if the actor contains primitives that are far apart with a large transparent area in the middle (such as a large CluterGroup with a small actor in the top left and a small actor in the bottom right) then the cached image will contain the entire image of the large area and the paint will waste time blending all of the transparent pixels in the middle.

The default method of implementing opacity on a container simply forwards on the opacity to all of the children. If the children are overlapping then it will appear as if they are two separate glassy objects and there will be a break in the color where they overlap. By redirecting to an offscreen buffer it will be as if the two opaque objects are combined into one and then made transparent which is usually what is expected.

The image below demonstrates the difference between redirecting and not. The image shows two Clutter groups, each containing a red and a green rectangle which overlap. The opacity on the group is set to 128 (which is 50%). When the offscreen redirect is not used, the red rectangle can be seen through the blue rectangle as if the two rectangles were separately transparent. When the redirect is used the group as a whole is transparent instead so the red rectangle is not visible where they overlap.

Sample of using an offscreen redirect for transparency:

The default value for this property is 0, so we effectively will never redirect an actor offscreen by default. This means that there are times that transparent actors may look glassy as described above. The reason this is the default is because there is a performance trade off between quality and performance here. In many cases the default form of glassy opacity looks good enough, but if it's not you will need to set the AUTOMATIC_FOR_OPACITY flag to enable redirection for opacity.

Custom actors that don't contain any overlapping primitives are recommended to override the has_overlaps virtual to return false for maximum efficiency.

Parameters:

this	A Actor
redirect	New offscreen redirect flags for the actor.