QuartzUIWorldSurfaceComponent: declaration reference

#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;
};