MediaIO.ScheduleOnAnyThread

MediaIO.ScheduleOnAnyThread

#Overview

name: MediaIO.ScheduleOnAnyThread

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of MediaIO.ScheduleOnAnyThread is to control whether resource readback for media capture should be performed in a separate thread. This setting is part of the MediaIO framework in Unreal Engine 5, which is responsible for handling media input and output operations.

This setting variable is primarily used by the MediaIOFramework plugin, specifically within the MediaIOCore module. Based on the callsites, it’s clear that this setting affects the media capture process.

The value of this variable is set through a console variable (CVar) named CVarMediaIOScheduleOnAnyThread. It is initialized with a default value of 1, meaning the feature is enabled by default. The value can be changed at runtime through console commands or programmatically.

This variable interacts with other settings, notably CVarMediaIOEnableExperimentalScheduling, as seen in the UseAnyThreadCapture function. Both of these variables need to be true for the any-thread capture feature to be enabled.

Developers should be aware that this feature is marked as experimental, as indicated in the description comment. This means it may not be fully stable and could potentially change or be removed in future engine versions.

Best practices when using this variable include:

  1. Testing thoroughly when enabling or disabling this feature, as it can affect performance and behavior of media capture operations.
  2. Monitoring performance metrics to ensure that using a separate thread for resource readback is beneficial for your specific use case.
  3. Being cautious when relying on this feature in production builds, given its experimental status.

Regarding the associated variable CVarMediaIOScheduleOnAnyThread:

The purpose of CVarMediaIOScheduleOnAnyThread is to provide a programmatic way to access and modify the MediaIO.ScheduleOnAnyThread setting. It’s an instance of TAutoConsoleVariable, which allows the engine to expose this setting as a console variable.

This variable is used within the MediaIOCore module to determine whether to use any-thread capture. It’s checked in the UseAnyThreadCapture function along with other conditions.

The value of this variable is set when it’s declared, but it can be changed at runtime through console commands or programmatically using the SetValueOnAnyThread method.

CVarMediaIOScheduleOnAnyThread interacts directly with the MediaIO.ScheduleOnAnyThread setting, effectively serving as its in-code representation.

Developers should be aware that this variable is marked as render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed from the render thread.

Best practices for using this variable include:

  1. Using GetValueOnAnyThread() to read its value, as shown in the example code.
  2. Considering the implications of changing this value at runtime, as it could affect ongoing media capture operations.
  3. Coordinating changes to this variable with other related settings, such as CVarMediaIOEnableExperimentalScheduling.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Media/MediaIOFramework/Source/MediaIOCore/Private/MediaCapture.cpp:53

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarMediaIOScheduleOnAnyThread(
	TEXT("MediaIO.ScheduleOnAnyThread"), 1,
	TEXT("Whether to wait for resource readback in a separate thread. (Experimental)"),
	ECVF_RenderThreadSafe);

DECLARE_GPU_STAT(MediaCapture_ProcessCapture);
DECLARE_CYCLE_STAT(TEXT("MediaCapture RenderThread LockResource"), STAT_MediaCapture_RenderThread_LockResource, STATGROUP_Media);
DECLARE_CYCLE_STAT(TEXT("MediaCapture RenderThread CPU Capture Callback"), STAT_MediaCapture_RenderThread_CaptureCallback, STATGROUP_Media);

#Associated Variable and Callsites

This variable is associated with another variable named CVarMediaIOScheduleOnAnyThread. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Plugins/Media/MediaIOFramework/Source/MediaIOCore/Private/MediaCapture.cpp:52

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarMediaIOScheduleOnAnyThread(
	TEXT("MediaIO.ScheduleOnAnyThread"), 1,
	TEXT("Whether to wait for resource readback in a separate thread. (Experimental)"),
	ECVF_RenderThreadSafe);

DECLARE_GPU_STAT(MediaCapture_ProcessCapture);
DECLARE_CYCLE_STAT(TEXT("MediaCapture RenderThread LockResource"), STAT_MediaCapture_RenderThread_LockResource, STATGROUP_Media);

#Loc: <Workspace>/Engine/Plugins/Media/MediaIOFramework/Source/MediaIOCore/Private/MediaCapture.cpp:494

Scope (from outer to inner):

file
function     bool UMediaCapture::UseAnyThreadCapture

Source code excerpt:

	return GRHISupportsMultithreading
		&& CVarMediaIOEnableExperimentalScheduling.GetValueOnAnyThread() 
		&& CVarMediaIOScheduleOnAnyThread.GetValueOnAnyThread()
		&& SupportsAnyThreadCapture();
}

bool UMediaCapture::UpdateSceneViewport(TSharedPtr<FSceneViewport>& InSceneViewport)
{
	check(CaptureSource);