OVROverlay Class

Combined with compositionDepth for final render order. Determines whether overlay renders behind, in front, or disabled relative to scene content. Underlay for backgrounds/skyboxes, Overlay for UI/HUD, None to disable rendering completely.

Dynamic mode enables video and animated UI but consumes more GPU resources.

When true, the layer uses HDCP (High-bandwidth Digital Content Protection) or similar mechanisms to protect copyrighted content. Use for DRM-protected media, copyrighted video content, or sensitive information. May have performance overhead and platform limitations.

For side-by-side stereo: use (0,0,0.5,1). For over-under: use (0,0.5,1,1).

For side-by-side stereo: use (0.5,0,0.5,1). For over-under: use (0,0,1,0.5).

Requires overrideTextureRectMatrix enabled to take effect.

Requires overrideTextureRectMatrix enabled to take effect.

Modern VR systems typically use bottom-left as the texture origin, so this property provides backward compatibility. Enable when working with legacy textures or content that appears upside-down in the overlay.

When true, the srcRectLeft, srcRectRight, destRectLeft, and destRectRight properties control texture sampling and positioning. Use for stereo layouts, texture atlasing, or custom viewport positioning.

When true, allows fine-tuning the visual appearance of overlays without modifying source textures. Use colorScale and colorOffset to control the adjustments. Final color = (SourceColor * colorScale) + colorOffset. More efficient than CPU texture modifications.

Each component multiplies the corresponding channel in the source texture before colorOffset is applied. Default value (1,1,1,1) applies no scaling. Use for brightness adjustment, color tinting, or transparency fading.

Each component is added to the corresponding channel after colorScale multiplication. Default value (0,0,0,0) applies no offset. Use for color tinting, brightness boost, or fade to color.

WARNING: Performance-intensive feature that should only be used when you have sufficient GPU budget and require the highest possible visual quality. Not recommended for most applications. Consider useAutomaticFiltering instead, to achieve better quality filtering when performance headroom allows.

WARNING: Performance-intensive feature that should only be used when you have sufficient GPU budget and require the highest possible visual quality. Not recommended for most applications. Consider useAutomaticFiltering instead, to achieve better quality filtering when performance headroom allows.

When true, the overlay is hidden from rendering. Use this property to dynamically show/hide overlays without disabling the component. This is useful when the overlay may be frequently hidden and shown, without the performance hit of full layer teardown and setup.

When true, creates an Android Surface object that can be used with MediaPlayer, Camera2 API, or other native Android media frameworks. Use for video playback, camera feeds, or streaming content. External surfaces provide optimal video performance by bypassing Unity's texture management.

This dimension determines the resolution of the media content that can be rendered to the surface. Choose dimensions that match your media content resolution for optimal quality. Higher resolutions consume more GPU resources. Some image producers may override these dimensions to match source content size.

This dimension determines the resolution of the media content that can be rendered to the surface. Ensure the width/height ratio matches your content's aspect ratio to prevent distortion. Use the lowest resolution that provides acceptable quality. Some image producers may override these dimensions to match source content size.

Lower values render first (behind).

When true, prevents the overlay from being occluded by scene geometry even when "Shared Depth Buffer" is enabled in the VR runtime. Enable for UI elements that should always be visible (HUD, menus). Disable for 3D UI that should interact with scene geometry.

Controls color depth, precision, and gamma correction behavior. Use sRGB for standard UI/video, floating point for HDR content, linear for custom color management. The system automatically detects HDR formats from texture types. Higher precision formats consume more memory and bandwidth.

Each shape provides different ways to display content in 3D space, from flat panels to immersive 360-degree environments. Choose based on content type: Quad for UI/video, Cylinder for wrap-around content, Cubemap/Equirect for 360° content, Passthrough for mixed reality. Some shapes have platform limitations (Cylinder/OffcenterCubemap are mobile-only, Fisheye not supported on OpenXR).

Array index 0 contains the left eye texture, index 1 contains the right eye texture. For mono content, only index 0 is used and the same texture is displayed to both eyes. Use Cubemap textures for Cubemap shapes, Texture2D/RenderTexture for others. For dynamic content, use OverrideOverlayTextureInfo() to avoid expensive native pointer lookups per frame.

This affects alpha blending behavior during overlay composition with scene content. In premultiplied alpha, RGB values are already multiplied by alpha (e.g., red pixel (1,0,0) with 50% alpha becomes (0.5,0,0,0.5)). Enable for modern rendering pipelines that use premultiplied alpha. Disable for standard "straight alpha" textures.

Provides smoother visual results compared to standard bilinear filtering when textures are scaled up or down. Use for high-resolution UI elements, text overlays, or detailed images when you have sufficient GPU budget. Consider useAutomaticFiltering to let the runtime decide based on performance characteristics.

DEPRECATED: This setting will be removed in future versions. Fix your cubemap textures instead of relying on this legacy behavior.

This is a performance-optimized alternative to useExpensiveSuperSample that provides better quality with reasonable GPU cost. Super sampling renders content at higher resolution then downsamples for display, reducing aliasing. Use for text overlays, UI elements with fine details, or when visual quality is prioritized over performance. Cannot be used simultaneously with sharpening filters unless using useAutomaticFiltering.

This is a performance-optimized alternative to useExpensiveSharpen that provides good quality enhancement with reasonable GPU cost. Sharpening enhances edge contrast to make content appear crisper. Use for text-heavy UI overlays, soft/blurry images, or content with fine details. Cannot be used simultaneously with super sampling unless using useAutomaticFiltering.

Recommended for most applications.

This helps with positioning and setup during development but has no effect at runtime. Creates a visual representation for positioning overlays, visualizing size/shape, and debugging placement. Only approximates VR appearance and may not represent all shapes accurately. No impact on runtime performance.

This handle is used internally to reference the layer in all compositor operations and submissions. Set to 0 initially, positive values indicate active layer, reset to 0 when destroyed. Used for texture submission, property updates, and cleanup operations. Managed on main Unity thread only. A layerId of 0 indicates initialization failure or destroyed state.

Returns Stereo if separate left/right eye textures are provided on Android, otherwise Mono.

Used for layer composition ordering and efficient overlay management.

Updated each frame during rendering to reflect the actual visibility state.This property is set to true when the overlay is successfully submitted to the VR compositor and not hidden via the hidden flag. Used to determine whether to disable the associated Renderer component for performance optimization.

Returns 2 for stereo layout (separate left/right eye textures), 1 for mono layout (shared texture).Used to determine array sizes for texture management and processing loops. Stereo layout is only supported on Android platforms with separate eye textures.

Set to true when OverrideOverlayTextureInfo is called, reset after processing.

Single entry for mono, two entries for stereo rendering.

Defines all rendering parameters including format, size, layout, and feature flags.

Typically 3 for triple buffering to prevent blocking during texture updates.

Prevents garbage collection from moving the layerId value while compositor holds a pointer to it.

Allows VR runtime to directly access and modify the layer ID without managed/native transitions.

Increments each frame for dynamic overlays to cycle through available texture stages.

Helps optimize rendering by avoiding redundant texture population within the same frame.

Used for backward compatibility and automatic renderer visibility management.

Used by the overlay system to manage layer indices, track overlay lifecycle, and optimize resource allocation. Provides automatic layer index assignment, efficient reuse of destroyed overlay slots, and proper cleanup coordination. Not thread-safe - use only on main Unity thread. Total overlay count can impact VR compositor performance.

Contains the shader and settings for efficient texture copying and format conversion.

Each material extracts and processes a specific face of the cubemap.

Use this method to efficiently update overlay textures without triggering expensive native texture pointer lookups each frame. GetNativeTexturePtr() is expensive - pre-cache the pointer and use this method instead of directly assigning to textures array.

Source rectangles define which portion of the input texture is sampled (normalized 0-1 coordinates). Destination rectangles define where the content appears in the final overlay rendering.

Handles coordinate conversions for external surfaces, texture inversion, and fisheye projections. Converts source/destination rectangles into GPU-ready transformation matrices. External surfaces use inverted Y coordinates, fisheye applies -0.5 offset for centering. Populates textureRectMatrix with scale/bias values for compositor UV transformation.

This method provides a convenient way to apply color transformations without manually setting individual properties.Applies the provided scale and offset values. The final color is calculated as: (SourceColor * scale) + offset.

Forces recreation of the preview visualization object with current overlay settings.

Passthrough shapes don't need textures as they display real-world content.

Handles layer descriptor creation, compositor setup, and instance registry management.

Called during layer teardown to free compositor texture memory.

Cleans up the layer ID, destroys textures, and removes the overlay from the global instances registry. Performs comprehensive cleanup: hides overlay, removes from registry, destroys layer, releases handles, resets state. Can be called multiple times safely. Automatically invoked by OnDisable, OnDestroy, and TrySubmitLayer when needed.

Ensures application textures are properly prepared and accessible to the VR compositor.

Analyzes texture properties and overlay settings to generate the appropriate layer specification. Automatically detects HDR formats from texture types, sets feature flags based on enabled properties, and calculates appropriate dimensions from external surfaces or texture dimensions.

Converts normalized source rectangles to exact pixel coordinates with appropriate padding. For stereo textures, uses appropriate eye rectangle. For shared textures, calculates union of both eyes. Adds 2-pixel border to handle texture filtering edge cases.

Renders the source texture to a sub-region with custom projection and viewport settings. Uses scissor rectangle and viewport offsetting to blit only the necessary region, reducing GPU bandwidth. Integrates with Unity's command buffer system for efficient GPU command submission.

Handles format conversion, alpha premultiplication, and texture rectangle processing.

Handles filtering validation, texture matrix updates, and alpha premultiplication settings.

Manages Unity editor visualization for overlay positioning and debugging.

Passthrough shapes don't require texture content as they render camera or environment data directly.Passthrough shapes include: ReconstructionPassthrough, SurfaceProjectedPassthrough, KeyboardHandsPassthrough, and KeyboardMaskedHandsPassthrough. These shapes are used for mixed reality applications where real-world content is integrated with virtual elements.