X-Plane 10.25 introduces a new mechanism for authors to optimize framerate in very large custom aircraft, using custom datarefs to “kill” the objects attached to the aircraft. This article explains how the mechanism works and how to use it.
This facility can only be used by aircraft that use a plugin (or plugin script) to create custom datarefs. This facility is only useful if the objects attached to the airplane cause significant framerate loss.
Setting an Object-Kill Dataref
An object-kill dataref is a dataref associated with an attached object that, when it has a non-zero value, causes X-Plane to skip drawing of that object entirely. The dataref is provided by a plugin associated with the aircraft.
In the example to the left, the gear have custom datarefs that hide them – the plugin could set these datarefs to 1 when the gear are up or when the camera is inside the 3-d cockpit. There is also a single custom dataref removing both seats and the cabin interior – this dataref would be set to 1 when the camera is facing forward or when the camera is far from the aircraft.
The object-kill dataref is optional; if the slot is left blank (it is left blank by default) the object is always drawn. An object-kill dataref is not available for the cockpit object, which is always drawn.
Performance of object-kill and ANIM_hide
It is already possible to hide objects using animation, e.g. ANIM_hide. So what is the difference between “hiding” part of an object and “killing it” (removing it completely) with a custom dataref?
An object consumes CPU and GPU in several ways:
- Drawing the object takes CPU time, spent running the object’s internal “commands”, reading datarefs for animations, and configuring the graphics card (time spent on the CPU in the video driver).
- Drawing objects takes GPU time to draw the vertices of the objects. This cost is usually minor; you need to draw several million vertices for the GPU to notice.
- Drawing objects takes GPU time to fill in the pixels of the object. This can be significant, particularly for large screen resolutions, lots of translucency, HDR, and FSAA.
- Drawing an object requires accessing the vertices and texture of the object in VRAM; this increases the total amount of VRAM needed to draw the scene. (See here and here for more info.) This VRAM is needed even if only part of the texture or geometry is actually drawn.
When you use ANIM_hide to hide an object, you save the cost of drawing vertices and filling pixels on the GPU. However, you do not save the cost of the CPU time, or the reduction in working set, because X-Plane runs the entire set of CPU computations for the object regardless of what will be drawn. (X-Plane does this because it must be prepared to draw part of the object even if another part is hidden. ANIM_hide was never intended as a performance optimization.)
When you hide an entire object attached to an aircraft using an object-kill dataref, the object is not processed at all; not only is GPU time saved, but CPU time is saved. Since the object’s data in VRAM is not accessed at all, the pressure on VRAM goes down.
Guidelines for Using Object-Kill
- Use object-kill when the object that can be removed is complex, e.g. an object with a lot of animations, ATTR_light_level directives, etc.
- Use object-kill when you can remove every object that references a large texture set. (For example, if your aircraft has a wing texture with a 2048×2048 normal map, it’s a win to remove every object that uses the wing texture.)
- Use object-kill to remove objects that are rarely visible. For example, if your object comes with a ground power unit, staircase truck, cones, and animated ground crew, it can be a win to object-kill the objects since they will mostly be gone.
- Splitting your aircraft into lots of small objects for the purpose of using object-kill is often not a win. There is a fixed CPU cost per object, so if objects are mostly visible, having more of them is a loss.
- Object-kill datarefs need to run quickly; remove objects based on simple static conditions like “kill gear when the gear is fully retracted”, or “kill the GPU when the plane is moving.” It is not worth it to try to do complex 3-d calculations to determine that an object should be killed. X-Plane already applies visibility culling to your objects.