---
title: "QuartzUIWorldSurfaceComponent: declaration reference"
description: "Quartz UI 0.57.0-dev: QuartzUIWorldSurfaceComponent: declaration reference. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# QuartzUIWorldSurfaceComponent: declaration reference

> **0.57.0-dev · beta source documentation.** Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See [validation and limits](https://betterbuilt.games/docs/quartz-ui/evidence).

Pinned source (source: `Source/QuartzUIRuntime/Public/QuartzUIWorldSurfaceComponent.h`) · [integration recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiworldsurfacecomponent) · [practical guide](https://betterbuilt.games/docs/quartz-ui/rendering)

## Complete header

Source snapshot, not an additional example. Unreal annotations distinguish exposed Blueprint nodes from native-only/private methods.

```cpp
#pragma once

#include "Components/StaticMeshComponent.h"
#include "QuartzUIApp.h"
#include "QuartzUIBrowserSession.h"
#include "QuartzUIPresentationTarget.h"
#include "QuartzUIView.h"

#include "QuartzUIWorldSurfaceComponent.generated.h"

class ULocalPlayer;
class UMaterialInstanceDynamic;
class UQuartzUIAppAsset;
class UQuartzUISurfaceTexture;
class UQuartzUIView;
struct FQuartzUIDirectWorldSurfaceTestAccess;

/**
 * Direct browser-texture world presentation.
 *
 * This is ordinary mesh geometry sized in Unreal world units. It never creates
 * a Slate widget, UWidgetComponent, widget renderer, or second render target.
 * Browser cadence changes page pixels only; camera attachment is handled by
 * Unreal's normal scene renderer with no browser/provider round trip.
 */
UCLASS(
	BlueprintType,
	ClassGroup = "QuartzUI",
	meta = (BlueprintSpawnableComponent, DisplayName = "QuartzUI Direct World Surface"))
class QUARTZUIRUNTIME_API UQuartzUIWorldSurfaceComponent final
	: public UStaticMeshComponent
	, public IQuartzUIPresentationTarget
{
	GENERATED_BODY()

public:
	UQuartzUIWorldSurfaceComponent(const FObjectInitializer& ObjectInitializer);

	/** Creates and owns a logical view, including its project contracts/providers. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool InitializeApp(const UQuartzUIAppAsset* App, ULocalPlayer* OwningLocalPlayer);

	/** Attaches the direct browser presentation to an existing unpresented view. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool AttachToView(UQuartzUIView* View);

	/** Core-contract-only path for small self-contained pages. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool InitializeStandalone(const FQuartzUIAppDefinition& Definition);

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	void ReleaseQuartzUI();

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool SetQuartzUIRuntimeSuspended(bool bSuspended);

	/** Recreates the MID binding after callers replace mesh materials at runtime. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool RefreshMaterialBinding();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	UQuartzUIView* GetAttachedView() const { return AttachedView.Get(); }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	UQuartzUISurfaceTexture* GetSurfaceTexture() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	FQuartzUIRenderSurfaceDescriptor GetSurfaceDescriptor() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	EQuartzUIBrowserSessionState GetBrowserSessionState() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	FString GetBrowserFailureReason() const;

	UFUNCTION(BlueprintCallable, Category = "QuartzUI|World Surface")
	bool SetRasterSize(FIntPoint NewPixelSize);

	UFUNCTION(BlueprintPure, Category = "QuartzUI|World Surface")
	FIntPoint GetRasterSize() const { return RasterSize; }

	virtual UQuartzUIBridge* GetQuartzUIPresentationBridge() const override;
	virtual void DetachQuartzUIPresentation(UQuartzUIView* ExpectedView) override;
	virtual void TickComponent(
		float DeltaTime,
		ELevelTick TickType,
		FActorComponentTickFunction* ThisTickFunction) override;
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;

	static bool IsRasterSizeValid(FIntPoint Candidate);

private:
	bool StartSession(
		const FQuartzUIAppDefinition& Definition,
		const FString& ContractHash,
		const FString& BrowserContextId,
		UQuartzUIView* View,
		bool bOwnsView);
	void SynchronizeViewState();
	void TickBrowserSession(float DeltaTime);
	bool ApplyBrowserSuspension();
	void UpdateVisibilitySuspension();
	void ReleaseSession(bool bCloseOwnedView);

	UFUNCTION()
	void HandleAttachedViewStateChanged(EQuartzUIViewState PreviousState, EQuartzUIViewState NewState);

protected:
	virtual void OnVisibilityChanged() override;
	virtual void OnHiddenInGameChanged() override;

private:

	/** Browser raster resolution, deliberately independent of mesh/world size. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|World Surface", meta = (ClampMin = "1", ClampMax = "8192"))
	FIntPoint RasterSize = FIntPoint(1024, 512);

	/** Material slot receiving the stable browser texture facade. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|World Surface", meta = (ClampMin = "0"))
	int32 MaterialIndex = 0;

	/** Texture parameter on the authored world-surface material. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|World Surface")
	FName TextureParameterName = TEXT("SlateUI");

	/** Stops browser painting while the mesh has not contributed to a recent frame. */
	UPROPERTY(EditAnywhere, Category = "QuartzUI|World Surface|Performance")
	bool bAutoSuspendWhenNotRendered = true;

	UPROPERTY(EditAnywhere, Category = "QuartzUI|World Surface|Performance", meta = (ClampMin = "0.1", ClampMax = "10.0"))
	float AutoSuspendDelaySeconds = 0.5f;

	UPROPERTY(Transient)
	TObjectPtr<UMaterialInstanceDynamic> SurfaceMaterialInstance;

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIView> AttachedView;

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIView> OwnedView;

	TSharedPtr<IQuartzUIBrowserSession> BrowserSession;
	EQuartzUIBrowserSessionState LastObservedSessionState = EQuartzUIBrowserSessionState::Closed;
	double SessionStartTimeSeconds = 0.0;
	bool bExplicitlySuspended = false;
	bool bVisibilitySuspended = false;
	bool bBrowserSuspended = false;
	bool bSynchronizingViewState = false;

	friend struct FQuartzUIDirectWorldSurfaceTestAccess;
};
```

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/reference-quartzuiworldsurfacecomponent