RenderGraphUtils.cpp File Reference

#include "RenderGraphUtils.h"
#include "ClearQuad.h"
#include "DataDrivenShaderPlatformInfo.h"
#include "GlobalShader.h"
#include "PixelShaderUtils.h"
#include "RenderGraphResourcePool.h"
#include "RenderTargetPool.h"
#include "RHIGPUReadback.h"
#include <initializer_list>

Classes
class	FDrawTexturePS
class	FClearUAVRectsPS
class	FInitIndirectArgs1DCS

Functions
void	ClearUnusedGraphResourcesImpl (const FShaderParameterBindings &ShaderBindings, const FShaderParametersMetadata *ParametersMetadata, void *InoutParameters, std::initializer_list< FRDGResourceRef > ExcludeList)
void	ClearUnusedGraphResourcesImpl (TArrayView< const FShaderParameterBindings * > ShaderBindingsList, const FShaderParametersMetadata *ParametersMetadata, void *InoutParameters, std::initializer_list< FRDGResourceRef > ExcludeList)
FRDGTextureRef	RegisterExternalTextureWithFallback (FRDGBuilder &GraphBuilder, const TRefCountPtr< IPooledRenderTarget > &ExternalPooledTexture, const TRefCountPtr< IPooledRenderTarget > &FallbackPooledTexture)
RENDERCORE_API FRDGTextureMSAA	CreateTextureMSAA (FRDGBuilder &GraphBuilder, FRDGTextureDesc Desc, const TCHAR *NameMultisampled, const TCHAR *NameResolved, ETextureCreateFlags ResolveFlagsToAdd)
	IMPLEMENT_GLOBAL_SHADER (FDrawTexturePS, "/Engine/Private/Tools/DrawTexture.usf", "DrawTexturePS", SF_Pixel)
void	AddCopyTexturePass (FRDGBuilder &GraphBuilder, FRDGTextureRef InputTexture, FRDGTextureRef OutputTexture, const FRHICopyTextureInfo &CopyInfo)
RENDERCORE_API void	AddDrawTexturePass (FRDGBuilder &GraphBuilder, const FGlobalShaderMap *ShaderMap, FRDGTextureRef InputTexture, FRDGTextureRef OutputTexture, const FRDGDrawTextureInfo &DrawInfo)
void	AddCopyBufferPass (FRDGBuilder &GraphBuilder, FRDGBufferRef DstBuffer, uint64 DstOffset, FRDGBufferRef SrcBuffer, uint64 SrcOffset, uint64 NumBytes)
void	AddCopyBufferPass (FRDGBuilder &GraphBuilder, FRDGBufferRef DstBuffer, FRDGBufferRef SrcBuffer)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGBufferUAVRef BufferUAV, uint32 Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVFloatPass (FRDGBuilder &GraphBuilder, FRDGBufferUAVRef BufferUAV, float Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FUintVector4 &ClearValues, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FVector4f &ClearValues, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const uint32(&ClearValues)[4], ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const float(&ClearValues)[4], ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FLinearColor &ClearColor, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, uint32 Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, float Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FVector &Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FIntPoint &Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FVector2D &Value, ERDGPassFlags ComputePassFlags)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, FRDGTextureUAVRef TextureUAV, const FVector4d &Value, ERDGPassFlags ComputePassFlags)
	IMPLEMENT_GLOBAL_SHADER (FClearUAVRectsPS, "/Engine/Private/ClearReplacementShaders.usf", "ClearTextureRWPS", SF_Pixel)
void	AddClearUAVPass (FRDGBuilder &GraphBuilder, ERHIFeatureLevel::Type FeatureLevel, FRDGTextureUAVRef TextureUAV, const uint32(&ClearValues)[4], FRDGBufferSRVRef RectCoordBufferSRV, uint32 NumRects)
void	AddClearRenderTargetPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture)
void	AddClearRenderTargetPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture, const FLinearColor &ClearColor)
void	AddClearRenderTargetPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture, const FLinearColor &ClearColor, FIntRect Viewport)
void	AddClearRenderTargetPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture, const FRDGTextureClearInfo &TextureClearInfo)
void	AddClearDepthStencilPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture, bool bClearDepth, float Depth, bool bClearStencil, uint8 Stencil)
void	AddClearDepthStencilPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture, ERenderTargetLoadAction DepthLoadAction, ERenderTargetLoadAction StencilLoadAction)
void	AddClearStencilPass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture)
void	AddResummarizeHTilePass (FRDGBuilder &GraphBuilder, FRDGTextureRef Texture)
void	AddEnqueueCopyPass (FRDGBuilder &GraphBuilder, FRHIGPUTextureReadback *Readback, FRDGTextureRef SourceTexture, FResolveRect Rect, uint32 SourceSlice)
void	AddEnqueueCopyPass (FRDGBuilder &GraphBuilder, FRHIGPUBufferReadback *Readback, FRDGBufferRef SourceBuffer, uint32 NumBytes)
	IMPLEMENT_GLOBAL_SHADER (FInitIndirectArgs1DCS, "/Engine/Private/Tools/SetupIndirectArgs.usf", "InitIndirectArgs1DCS", SF_Compute)
FRDGBufferRef	CreateStructuredBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, uint32 BytesPerElement, uint32 NumElements, const void *InitialData, uint64 InitialDataSize, ERDGInitialDataFlags InitialDataFlags)
FRDGBufferRef	CreateStructuredBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, uint32 BytesPerElement, FRDGBufferNumElementsCallback &&NumElementsCallback, FRDGBufferInitialDataCallback &&InitialDataCallback, FRDGBufferInitialDataSizeCallback &&InitialDataSizeCallback)
FRDGBufferRef	CreateByteAddressBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, uint32 NumBytes, const void *InitialData, uint64 InitialDataSize, ERDGInitialDataFlags InitialDataFlags)
FRDGBufferRef	CreateByteAddressBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, FRDGBufferNumElementsCallback &&NumElementsCallback, FRDGBufferInitialDataCallback &&InitialDataCallback, FRDGBufferInitialDataSizeCallback &&InitialDataSizeCallback)
FRDGBufferRef	CreateUploadBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, uint32 BytesPerElement, uint32 NumElements, const void *InitialData, uint64 InitialDataSize, ERDGInitialDataFlags InitialDataFlags)
FRDGBufferRef	CreateVertexBuffer (FRDGBuilder &GraphBuilder, const TCHAR *Name, const FRDGBufferDesc &Desc, const void *InitialData, uint64 InitialDataSize, ERDGInitialDataFlags InitialDataFlags)
bool	AllocatePooledBuffer (const FRDGBufferDesc &Desc, TRefCountPtr< FRDGPooledBuffer > &Out, const TCHAR *Name, ERDGPooledBufferAlignment Alignment)
TRefCountPtr< FRDGPooledBuffer >	AllocatePooledBuffer (const FRDGBufferDesc &Desc, const TCHAR *Name, ERDGPooledBufferAlignment Alignment)
bool	AllocatePooledTexture (const FRDGTextureDesc &Desc, TRefCountPtr< IPooledRenderTarget > &Out, const TCHAR *Name)
TRefCountPtr< IPooledRenderTarget >	AllocatePooledTexture (const FRDGTextureDesc &Desc, const TCHAR *Name)

Function Documentation

AddClearDepthStencilPass() [1/2]

void AddClearDepthStencilPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture,
		bool	bClearDepth,
		float	Depth,
		bool	bClearStencil,
		uint8	Stencil
	)

Adds a render graph pass to clear a depth stencil target. Prefer to use clear actions if possible.

AddClearDepthStencilPass() [2/2]

void AddClearDepthStencilPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture,
		ERenderTargetLoadAction	DepthLoadAction = ERenderTargetLoadAction::EClear,
		ERenderTargetLoadAction	StencilLoadAction = ERenderTargetLoadAction::EClear
	)

Adds a render graph pass to clear a depth stencil target to its optimized clear value using a raster pass.

AddClearRenderTargetPass() [1/4]

void AddClearRenderTargetPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture
	)

Adds a render graph pass to clear a render target to its clear value (single mip, single slice)

AddClearRenderTargetPass() [2/4]

void AddClearRenderTargetPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture,
		const FLinearColor &	ClearColor
	)

Adds a render graph pass to clear a render target (single mip, single slice). Uses render pass clear actions if the clear color matches the fast clear color.

AddClearRenderTargetPass() [3/4]

void AddClearRenderTargetPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture,
		const FLinearColor &	ClearColor,
		FIntRect	Viewport
	)

Adds a render graph pass to clear a part of a render target (single mip, single slice). Draws a quad to the requested viewport.

AddClearRenderTargetPass() [4/4]

void AddClearRenderTargetPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture,
		const FRDGTextureClearInfo &	TextureClearInfo
	)

Adds a render graph pass to clear a render target to its clear value.

AddClearStencilPass()

void AddClearStencilPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	Texture
	)

Adds a render graph pass to clear the stencil portion of a depth / stencil target to its fast clear value.

AddClearUAVFloatPass()

void AddClearUAVFloatPass	(	FRDGBuilder &	GraphBuilder,
		FRDGBufferUAVRef	BufferUAV,
		float	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [1/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		ERHIFeatureLevel::Type	FeatureLevel,
		FRDGTextureUAVRef	TextureUAV,
		const uint32(&)	ClearValues[4],
		FRDGBufferSRVRef	RectMinMaxBufferSRV,
		uint32	NumRects
	)

Clears parts of UAV specified by an array of screen rects. If no rects are specific, then it falls back to a standard UAV clear.

AddClearUAVPass() [2/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGBufferUAVRef	BufferUAV,
		uint32	Value,
		ERDGPassFlags	ComputePassFlags = ERDGPassFlags::Compute
	)

Adds a render graph pass to clear a texture or buffer UAV with a single typed value.

AddClearUAVPass() [3/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FIntPoint &	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [4/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FLinearColor &	ClearColor,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [5/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const float(&)	ClearValues[4],
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [6/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FUintVector4 &	ClearValues,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [7/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FVector &	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [8/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FVector2D &	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [9/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FVector4d &	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [10/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const FVector4f &	ClearValues,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [11/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		const uint32(&)	ClearValues[4],
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [12/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		float	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddClearUAVPass() [13/13]

void AddClearUAVPass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureUAVRef	TextureUAV,
		uint32	Value,
		ERDGPassFlags	ComputePassFlags
	)

AddCopyBufferPass() [1/2]

void AddCopyBufferPass	(	FRDGBuilder &	GraphBuilder,
		FRDGBufferRef	DstBuffer,
		FRDGBufferRef	SrcBuffer
	)

AddCopyBufferPass() [2/2]

void AddCopyBufferPass	(	FRDGBuilder &	GraphBuilder,
		FRDGBufferRef	DstBuffer,
		uint64	DstOffset,
		FRDGBufferRef	SrcBuffer,
		uint64	SrcOffset,
		uint64	NumBytes
	)

Adds a render graph pass to copy SrcBuffer content into DstBuffer.

AddCopyTexturePass()

void AddCopyTexturePass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	InputTexture,
		FRDGTextureRef	OutputTexture,
		const FRHICopyTextureInfo &	CopyInfo
	)

Adds a render graph pass to copy a region from one texture to another. Uses RHICopyTexture under the hood. Formats of the two textures must match. The output and output texture regions be within the respective extents.

AddDrawTexturePass()

RENDERCORE_API void AddDrawTexturePass	(	FRDGBuilder &	GraphBuilder,
		const FGlobalShaderMap *	ShaderMap,
		FRDGTextureRef	InputTexture,
		FRDGTextureRef	OutputTexture,
		const FRDGDrawTextureInfo &	DrawInfo
	)

AddEnqueueCopyPass() [1/2]

void AddEnqueueCopyPass	(	FRDGBuilder &	GraphBuilder,
		FRHIGPUBufferReadback *	Readback,
		FRDGBufferRef	SourceBuffer,
		uint32	NumBytes
	)

Adds a pass to readback contents of an RDG buffer.

AddEnqueueCopyPass() [2/2]

void AddEnqueueCopyPass	(	FRDGBuilder &	GraphBuilder,
		FRHIGPUTextureReadback *	Readback,
		FRDGTextureRef	SourceTexture,
		FResolveRect	Rect = FResolveRect(),
		uint32	SourceSlice = 0
	)

Adds a pass to readback contents of an RDG texture.

AddResummarizeHTilePass()

void AddResummarizeHTilePass	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureRef	DepthTexture
	)

Adds a render graph pass to resummarize the htile plane.

AllocatePooledBuffer() [1/2]

TRefCountPtr< FRDGPooledBuffer > AllocatePooledBuffer	(	const FRDGBufferDesc &	Desc,
		const TCHAR *	Name,
		ERDGPooledBufferAlignment	Alignment
	)

AllocatePooledBuffer() [2/2]

bool AllocatePooledBuffer	(	const FRDGBufferDesc &	Desc,
		TRefCountPtr< FRDGPooledBuffer > &	Out,
		const TCHAR *	Name,
		ERDGPooledBufferAlignment	Alignment
	)

AllocatePooledTexture() [1/2]

TRefCountPtr< IPooledRenderTarget > AllocatePooledTexture	(	const FRDGTextureDesc &	Desc,
		const TCHAR *	Name
	)

AllocatePooledTexture() [2/2]

bool AllocatePooledTexture	(	const FRDGTextureDesc &	Desc,
		TRefCountPtr< IPooledRenderTarget > &	Out,
		const TCHAR *	Name
	)

ClearUnusedGraphResourcesImpl() [1/2]

void ClearUnusedGraphResourcesImpl	(	const FShaderParameterBindings &	ShaderBindings,
		const FShaderParametersMetadata *	ParametersMetadata,
		void *	InoutParameters,
		std::initializer_list< FRDGResourceRef >	ExcludeList
	)

Clears all render graph tracked resources that are not bound by a shader. Excludes any resources on the ExcludeList from being cleared regardless of whether the shader binds them or not. This is needed for resources that are used outside of shader bindings such as indirect arguments buffers.

ClearUnusedGraphResourcesImpl() [2/2]

void ClearUnusedGraphResourcesImpl	(	TArrayView< const FShaderParameterBindings * >	ShaderBindingsList,
		const FShaderParametersMetadata *	ParametersMetadata,
		void *	InoutParameters,
		std::initializer_list< FRDGResourceRef >	ExcludeList
	)

Similar to the function above, but takes a list of shader bindings and only clears if none of the shaders contain the resource.

CreateByteAddressBuffer() [1/2]

FRDGBufferRef CreateByteAddressBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		FRDGBufferNumElementsCallback &&	NumElementsCallback,
		FRDGBufferInitialDataCallback &&	InitialDataCallback,
		FRDGBufferInitialDataSizeCallback &&	InitialDataSizeCallback
	)

A variant where NumElements, InitialData, and InitialDataSize are supplied through callbacks. This allows creating a buffer with information unknown at creation time. Though, data must be ready before the most recent RDG pass that references the buffer is executed. For byte address buffers, NumElements must be Size / 4.

CreateByteAddressBuffer() [2/2]

FRDGBufferRef CreateByteAddressBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		uint32	NumBytes,
		const void *	InitialData,
		uint64	InitialDataSize,
		ERDGInitialDataFlags	InitialDataFlags = ERDGInitialDataFlags::None
	)

Creates a byte address buffer with initial data by creating an upload pass.

CreateStructuredBuffer() [1/2]

FRDGBufferRef CreateStructuredBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		uint32	BytesPerElement,
		FRDGBufferNumElementsCallback &&	NumElementsCallback,
		FRDGBufferInitialDataCallback &&	InitialDataCallback,
		FRDGBufferInitialDataSizeCallback &&	InitialDataSizeCallback
	)

A variant where NumElements, InitialData, and InitialDataSize are supplied through callbacks. This allows creating a buffer with information unknown at creation time. Though, data must be ready before the most recent RDG pass that references the buffer is executed.

CreateStructuredBuffer() [2/2]

FRDGBufferRef CreateStructuredBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		uint32	BytesPerElement,
		uint32	NumElements,
		const void *	InitialData,
		uint64	InitialDataSize,
		ERDGInitialDataFlags	InitialDataFlags = ERDGInitialDataFlags::None
	)

Creates a structured buffer with initial data by creating an upload pass.

CreateTextureMSAA()

RENDERCORE_API FRDGTextureMSAA CreateTextureMSAA	(	FRDGBuilder &	GraphBuilder,
		FRDGTextureDesc	Desc,
		const TCHAR *	NameMultisampled,
		const TCHAR *	NameResolved,
		ETextureCreateFlags	ResolveFlagsToAdd
	)

CreateUploadBuffer()

FRDGBufferRef CreateUploadBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		uint32	BytesPerElement,
		uint32	NumElements,
		const void *	InitialData,
		uint64	InitialDataSize,
		ERDGInitialDataFlags	InitialDataFlags
	)

CreateVertexBuffer()

FRDGBufferRef CreateVertexBuffer	(	FRDGBuilder &	GraphBuilder,
		const TCHAR *	Name,
		const FRDGBufferDesc &	Desc,
		const void *	InitialData,
		uint64	InitialDataSize,
		ERDGInitialDataFlags	InitialDataFlags = ERDGInitialDataFlags::None
	)

Creates a vertex buffer with initial data by creating an upload pass.

IMPLEMENT_GLOBAL_SHADER() [1/3]

IMPLEMENT_GLOBAL_SHADER	(	FClearUAVRectsPS	,
		"/Engine/Private/ClearReplacementShaders.usf"	,
		"ClearTextureRWPS"	,
		SF_Pixel
	)

IMPLEMENT_GLOBAL_SHADER() [2/3]

IMPLEMENT_GLOBAL_SHADER	(	FDrawTexturePS	,
		"/Engine/Private/Tools/DrawTexture.usf"	,
		"DrawTexturePS"	,
		SF_Pixel
	)

IMPLEMENT_GLOBAL_SHADER() [3/3]

IMPLEMENT_GLOBAL_SHADER	(	FInitIndirectArgs1DCS	,
		"/Engine/Private/Tools/SetupIndirectArgs.usf"	,
		"InitIndirectArgs1DCS"	,
		SF_Compute
	)

RegisterExternalTextureWithFallback()

FRDGTextureRef RegisterExternalTextureWithFallback	(	FRDGBuilder &	GraphBuilder,
		const TRefCountPtr< IPooledRenderTarget > &	ExternalPooledTexture,
		const TRefCountPtr< IPooledRenderTarget > &	FallbackPooledTexture
	)

Register external texture with fallback if the resource is invalid.

CAUTION: use this function very wisely. It may actually remove shader parameter validation failure when a pass is actually trying to access a resource not yet or no longer available.