QuartzUIBrowserSession: 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.

Pinned source (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h) · integration recipe · practical guide

EQuartzUIRenderSurfaceTransfer

Advanced type. Describes how browser pixels reach the material-facing Unreal texture.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L13)

FQuartzUIBrowserSurfacePolicy

Internal type. Conservative direct-surface raster budget shared by sessions and presenters.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. This named helper is runtime-owned; inspect/use it through the owner above rather than constructing it in gameplay.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L24)

EQuartzUIBrowserSessionState

Advanced type. Browser lifecycle independent of any Slate or world presenter.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L37)

FQuartzUIBrowserSessionPolicy

Internal type. Pure lifecycle decisions shared by the Epic session and automation tests.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. This named helper is runtime-owned; inspect/use it through the owner above rather than constructing it in gameplay.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L49)

FQuartzUIRenderSurfaceDescriptor

Advanced type. Immutable snapshot of the newest material-facing browser surface.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L68)

FQuartzUIBrowserSessionSettings

Advanced type. Browser/session creation data with no Epic WebBrowser types in its contract.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L92)

IQuartzUIRenderSurface

Advanced type. Backend-neutral render surface consumed by Slate or world presenters.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L111)

IQuartzUIBrowserSession

Advanced type. Backend-neutral browser lifetime and material surface boundary. TickViewport must be called once per active game frame. Epic's off-screen browser uses that heartbeat to remain visible even when no Slate widget owns it. Resize requests are coalesced by the implementation.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L126)

FQuartzUIBrowserSessionCreateDelegate

Advanced delegate. Browser Session Create Delegate: callback signature for backend-neutral browser/render-surface interfaces and capability descriptors.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L142)

FQuartzUIBrowserSessionFactory

Advanced type. The only place that selects an actual browser backend.

Prerequisites / integration: Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the QuartzUIBrowserSession recipe in the host module QuartzUIRuntime.

Minimal example / lifecycle: Use WorldSurface presenter; inspect descriptor Transfer field. Session owns bridge and external texture lifetime; close nonblocking.

Avoid: Widening native texture casts to unsupported platform/RHI. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: Source/QuartzUIRuntime/Public/QuartzUIBrowserSession.h#L148)

Complete header

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

#pragma once

#include "CoreMinimal.h"
#include "Templates/SharedPointer.h"

#include "QuartzUIBrowserSession.generated.h"

class UTexture;
class UQuartzUIBridge;

/** Describes how browser pixels reach the material-facing Unreal texture. */
UENUM(BlueprintType)
enum class EQuartzUIRenderSurfaceTransfer : uint8
{
	Unavailable,
	CpuUpload,
	SynchronizedGpuCopy,
	ExternalTexture,
	/** Public backend surface is direct, but its internal paint path is opaque. */
	BackendManaged
};

/** Conservative direct-surface raster budget shared by sessions and presenters. */
class QUARTZUIRUNTIME_API FQuartzUIBrowserSurfacePolicy final
{
public:
	static constexpr int32 MaximumDimension = 8192;
	/** CEF source plus Epic's presentation texture, both assumed BGRA8. */
	static constexpr int32 EstimatedBackendBytesPerPixel = 8;

	static int64 GetMaximumPixelCount();
	static bool IsPixelSizeValid(FIntPoint PixelSize);
};

/** Browser lifecycle independent of any Slate or world presenter. */
UENUM(BlueprintType)
enum class EQuartzUIBrowserSessionState : uint8
{
	Creating,
	Loading,
	Ready,
	Suspended,
	Failed,
	Closing,
	Closed
};

/** Pure lifecycle decisions shared by the Epic session and automation tests. */
class QUARTZUIRUNTIME_API FQuartzUIBrowserSessionPolicy final
{
public:
	/** Epic CEF windowless OnPaint is hard-capped at 60 Hz by the backend. */
	static constexpr int32 MaximumEpicWindowlessFrameRate = 60;
	static int32 ClampEpicWindowlessFrameRate(const int32 RequestedFrameRate)
	{
		return FMath::Clamp(RequestedFrameRate, 1, MaximumEpicWindowlessFrameRate);
	}

	static EQuartzUIBrowserSessionState ResolveStateAfterResume(
		bool bReadinessFailed,
		bool bReadinessReady);
	/** Keeps a completed-document policy pending while suspended and consumes it once active. */
	static bool ConsumePendingPagePolicy(bool bSuspended, bool& bPending);
};

/** Immutable snapshot of the newest material-facing browser surface. */
USTRUCT(BlueprintType)
struct QUARTZUIRUNTIME_API FQuartzUIRenderSurfaceDescriptor
{
	GENERATED_BODY()

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	FIntPoint PixelSize = FIntPoint::ZeroValue;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	FName PixelFormatName = NAME_None;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	int64 FrameId = 0;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	int64 SurfaceGeneration = 0;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	EQuartzUIRenderSurfaceTransfer Transfer = EQuartzUIRenderSurfaceTransfer::Unavailable;

	UPROPERTY(BlueprintReadOnly, Category = "QuartzUI|Rendering")
	bool bTextureAvailable = false;
};

/** Browser/session creation data with no Epic WebBrowser types in its contract. */
struct QUARTZUIRUNTIME_API FQuartzUIBrowserSessionSettings
{
	TWeakObjectPtr<UObject> Owner;
	FString InitialUrl = TEXT("about:blank");
	FString InitialHtml;
	FString AllowedPackagedOrigin;
#if WITH_EDITOR
	FString AllowedDevelopmentOrigin;
#endif
	FString ContractHash;
	FString BrowserContextId;
	FIntPoint InitialPixelSize = FIntPoint(1024, 512);
	int32 BrowserFrameRate = 60;
	float HandshakeTimeoutSeconds = 5.0f;
	bool bSupportsTransparency = true;
	bool bAllowTextSelection = false;
};

/** Backend-neutral render surface consumed by Slate or world presenters. */
class QUARTZUIRUNTIME_API IQuartzUIRenderSurface
{
public:
	virtual ~IQuartzUIRenderSurface() = default;
	virtual FQuartzUIRenderSurfaceDescriptor GetDescriptor() const = 0;
	virtual UTexture* GetTexture() const = 0;
};

/**
 * Backend-neutral browser lifetime and material surface boundary.
 *
 * TickViewport must be called once per active game frame. Epic's off-screen
 * browser uses that heartbeat to remain visible even when no Slate widget owns
 * it. Resize requests are coalesced by the implementation.
 */
class QUARTZUIRUNTIME_API IQuartzUIBrowserSession
{
public:
	virtual ~IQuartzUIBrowserSession() = default;
	virtual void TickViewport(FIntPoint PixelSize, float DeltaSeconds) = 0;
	virtual bool LoadUrl(const FString& Url) = 0;
	virtual void Reload() = 0;
	virtual void ExecuteJavaScript(const FString& Script) = 0;
	virtual bool SetSuspended(bool bSuspended) = 0;
	virtual void Close() = 0;
	virtual EQuartzUIBrowserSessionState GetState() const = 0;
	virtual FString GetFailureReason() const = 0;
	virtual UQuartzUIBridge* GetBridge() const = 0;
	virtual TSharedRef<IQuartzUIRenderSurface> GetRenderSurface() const = 0;
};

DECLARE_DELEGATE_RetVal_OneParam(
	TSharedPtr<IQuartzUIBrowserSession>,
	FQuartzUIBrowserSessionCreateDelegate,
	const FQuartzUIBrowserSessionSettings&);

/** The only place that selects an actual browser backend. */
class QUARTZUIRUNTIME_API FQuartzUIBrowserSessionFactory final
{
public:
	/** Shared one-time resource-scheme and Epic browser initialization. */
	static bool PrepareEpicBackend();
	/** Public-API native-texture import is capability-gated to Win64 D3D11/12. */
	static bool SupportsEpicDirectSurface();

	/** Creates an off-screen Epic browser without constructing a Slate widget. */
	static TSharedPtr<IQuartzUIBrowserSession> CreateEpic(
		const FQuartzUIBrowserSessionSettings& Settings);

#if WITH_DEV_AUTOMATION_TESTS
	/** Fake-backend injection. Real accelerated paint is disabled by UE automation. */
	static void SetFactoryOverrideForTesting(const FQuartzUIBrowserSessionCreateDelegate& Factory);
	static void ClearFactoryOverrideForTesting();
#endif
};