From 42150e94720c78bb6a2fb0623c9f861f4f281731 Mon Sep 17 00:00:00 2001 From: Raanan Weber Date: Fri, 18 Sep 2026 15:42:01 +0200 Subject: [PATCH] Document normalized occlusion query visibility Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../features/featuresDeepDive/occlusionQueries.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/features/featuresDeepDive/occlusionQueries.md b/content/features/featuresDeepDive/occlusionQueries.md index 3324b6f32..289569947 100644 --- a/content/features/featuresDeepDive/occlusionQueries.md +++ b/content/features/featuresDeepDive/occlusionQueries.md @@ -45,6 +45,20 @@ If your object is behind an opaque object by default, you can set the `isOcclude sphere.isOccluded = true; ``` +## Reading a Query Result + +When you manage an occlusion query directly, wait until the result is available before reading it. Use [`isOcclusionQueryVisible`](/typedoc/classes/babylon.abstractengine#isocclusionqueryvisible) when you only need to know whether any samples passed: + +```javascript +if (engine.isQueryResultAvailable(query)) { + const isVisible = engine.isOcclusionQueryVisible(query); +} +``` + +This method returns `true` for any positive result and `false` for zero. It provides the same visibility check for WebGL and WebGPU. + +Use `getQueryResult(query)` only when you need the raw backend value. The size of a positive raw value is backend-specific and may be greater than `1`, so do not compare it with a fixed positive value. `isOcclusionQueryVisible(query)` does not change the raw result. + ## Advanced As described earlier, the Occlusion Queries result is asynchronous, and it may take some time to get the result. Because of this, the object may take several frames to appear while waiting for the query result. In this case, you can use the `occlusionRetryCount` property to set the number of waiting frames before the query is interrupted. Once that happens, you will need to decide whether to draw the object or maintain its state. The `occlusionType` property is used for this purpose, and you have 2 options: