telemetry and timing updates

apps/RenderCadenceCompositor/README.md

@@ -35,7 +35,7 @@ DeckLinkOutputThread
   never renders
 ```
 
-Startup builds one settled output reserve before DeckLink scheduled playback starts: the completed-frame reserve must reach the configured depth and remain ready for the configured settle window. When DeckLink input is available, startup also waits briefly for three ready input frames before the render thread starts so the first render ticks are deliberate rather than lucky.
+Startup builds a small output preroll reserve before DeckLink scheduled playback starts. When DeckLink input is available, startup also waits briefly for three ready input frames before the render thread starts so the first render ticks are deliberate rather than lucky.
 
 ## Current Scope
 
@@ -53,7 +53,7 @@ Included now:
 - render-thread-owned input texture upload
 - async PBO readback
 - latest-N system-memory frame exchange
-- settled completed-frame output reserve before DeckLink preroll, with DeckLink scheduled depth still targeted at four
+- bounded completed-frame output preroll reserve before DeckLink playback, with DeckLink scheduled depth still targeted at four
 - background Slang compile of `shaders/happy-accident`
 - app-owned display/render layer model for shader build readiness
 - app-owned submission of a completed shader artifact
@@ -198,7 +198,6 @@ Currently consumed fields:
 - `autoReload`
 - `maxTemporalHistoryFrames`
 - `previewFps`
-- `startupSettleMs`
 - `enableExternalKeying`
 
 The loaded config is treated as a read-only startup snapshot. Subsystems that need config should receive this snapshot or a narrowed config struct from app orchestration; they should not reload files independently.
@@ -238,7 +237,7 @@ DeckLink output is an optional edge service in this app.
 Startup order is:
 
 1. start render thread
-2. build a settled completed-frame output reserve at normal render cadence
+2. build a bounded completed-frame output preroll reserve at normal render cadence
 3. try to attach DeckLink output
 4. start telemetry and HTTP either way
 
@@ -286,7 +285,7 @@ Input telemetry:
 - `renderFrameMaxMs`: maximum observed render-thread draw duration for this process
 - `readbackQueueMs`: time spent queueing the most recent async BGRA8 PBO readback
 - `completedReadbackCopyMs`: time spent mapping/copying the most recent completed readback into system-memory frame storage
-- `completedDrops`: completed unscheduled system-memory frames dropped by latest-N acquire paths; expected to stay flat in the cadence compositor output path
+- `completedDrops`: completed unscheduled system-memory frames dropped; expected to stay flat in the cadence compositor output path
 - `acquireMisses`: times render/readback could not acquire a writable system-memory frame slot; completed frames waiting for playout are preserved instead of being displaced
 - `inputConsumeMisses`: render ticks where no ready input frame was available to upload
 - `inputUploadMisses`: input texture upload attempts that reused the previous GL input texture

apps/RenderCadenceCompositor/RenderCadenceCompositor.cpp

@@ -20,6 +20,10 @@
 
 namespace
 {
+constexpr std::size_t kDeckLinkTargetBufferedFrames = 4;
+constexpr std::size_t kReadbackDepth = 6;
+constexpr std::size_t kWritableOutputReserveFrames = kReadbackDepth + 2;
+
 class ComInitGuard
 {
 public:
@@ -95,7 +99,11 @@ int main(int argc, char** argv)
 		frameExchangeConfig.height);
 	frameExchangeConfig.pixelFormat = VideoIOPixelFormat::Bgra8;
 	frameExchangeConfig.rowBytes = VideoIORowBytes(frameExchangeConfig.pixelFormat, frameExchangeConfig.width);
-	frameExchangeConfig.capacity = 12;
+	frameExchangeConfig.capacity =
+		appConfig.warmupCompletedFrames +
+		kDeckLinkTargetBufferedFrames +
+		kWritableOutputReserveFrames;
+	frameExchangeConfig.maxCompletedFrames = appConfig.warmupCompletedFrames;
 
 	SystemFrameExchange frameExchange(frameExchangeConfig);
 
@@ -128,6 +136,10 @@ int main(int argc, char** argv)
 			"Unsupported DeckLink outputVideoFormat/outputFrameRate in config/runtime-host.json; render cadence will use parsed frame-rate fallback: " +
 				appConfig.outputVideoFormat + " / " + appConfig.outputFrameRate);
 	}
+	else
+	{
+		appConfig.deckLink.outputVideoMode = outputVideoMode;
+	}
 
 	RenderCadenceCompositor::DeckLinkInput deckLinkInput(inputMailbox);
 	RenderCadenceCompositor::DeckLinkInputThread deckLinkInputThread(deckLinkInput);
@@ -186,7 +198,7 @@ int main(int argc, char** argv)
 	renderConfig.frameDurationMilliseconds = outputVideoModeResolved
 		? RenderCadenceCompositor::FrameDurationMillisecondsFromDisplayMode(outputVideoMode.displayMode, fallbackFrameDurationMilliseconds)
 		: fallbackFrameDurationMilliseconds;
-	renderConfig.pboDepth = 6;
+	renderConfig.pboDepth = kReadbackDepth;
 
 	RenderThread renderThread(frameExchange, &inputMailbox, renderConfig);
 

apps/RenderCadenceCompositor/app/AppConfig.cpp

@@ -29,9 +29,8 @@ AppConfig DefaultAppConfig()
 	config.autoReload = true;
 	config.maxTemporalHistoryFrames = 12;
 	config.previewFps = 30.0;
-	config.warmupCompletedFrames = 8;
+	config.warmupCompletedFrames = 4;
 	config.warmupTimeout = std::chrono::seconds(3);
-	config.startupSettle = std::chrono::seconds(5);
 	config.prerollTimeout = std::chrono::seconds(3);
 	config.prerollPoll = std::chrono::milliseconds(2);
 	config.runtimeShaderId = "happy-accident";

apps/RenderCadenceCompositor/app/AppConfig.h

@@ -30,9 +30,8 @@ struct AppConfig
 	bool autoReload = true;
 	std::size_t maxTemporalHistoryFrames = 12;
 	double previewFps = 30.0;
-	std::size_t warmupCompletedFrames = 8;
+	std::size_t warmupCompletedFrames = 4;
 	std::chrono::milliseconds warmupTimeout = std::chrono::seconds(3);
-	std::chrono::milliseconds startupSettle = std::chrono::seconds(5);
 	std::chrono::milliseconds prerollTimeout = std::chrono::seconds(3);
 	std::chrono::milliseconds prerollPoll = std::chrono::milliseconds(2);
 	std::string runtimeShaderId = "happy-accident";

apps/RenderCadenceCompositor/app/AppConfigProvider.cpp

@@ -134,9 +134,6 @@ bool AppConfigProvider::Load(const std::filesystem::path& path, std::string& err
 	ApplySize(root, "maxTemporalHistoryFrames", mConfig.maxTemporalHistoryFrames);
 	ApplyDouble(root, "previewFps", mConfig.previewFps);
 	ApplyBool(root, "enableExternalKeying", mConfig.deckLink.externalKeyingEnabled);
-	std::size_t startupSettleMilliseconds = static_cast<std::size_t>(mConfig.startupSettle.count());
-	ApplySize(root, "startupSettleMs", startupSettleMilliseconds);
-	mConfig.startupSettle = std::chrono::milliseconds(startupSettleMilliseconds);
 
 	mLoadedFromFile = true;
 	error.clear();

apps/RenderCadenceCompositor/app/RenderCadenceApp.h

@@ -163,23 +163,24 @@ private:
 		mVideoOutputEnabled = true;
 		mVideoOutputStatus = "DeckLink scheduled output running.";
 		Log("app", mVideoOutputStatus);
+		Log(
+			"app",
+			"DeckLink output mode: " + mOutput.State().outputDisplayModeName +
+				", frame budget " + std::to_string(mOutput.State().frameBudgetMilliseconds) + " ms.");
 	}
 
 	bool BuildSettledOutputReserve(std::string& error)
 	{
-		const auto reserveTimeout = mConfig.warmupTimeout + mConfig.startupSettle + mConfig.warmupTimeout;
+		const auto reserveTimeout = mConfig.warmupTimeout;
 		Log("app",
-			"Building settled output reserve: waiting for " + std::to_string(mConfig.warmupCompletedFrames) +
-			" completed frame(s) to remain ready for " + std::to_string(mConfig.startupSettle.count()) + " ms.");
-		if (mFrameExchange.WaitForStableCompletedDepth(
-			mConfig.warmupCompletedFrames,
-			mConfig.startupSettle,
-			reserveTimeout))
+			"Building output preroll reserve: waiting for " + std::to_string(mConfig.warmupCompletedFrames) +
+			" completed frame(s).");
+		if (mFrameExchange.WaitForCompletedDepth(mConfig.warmupCompletedFrames, reserveTimeout))
 		{
 			return true;
 		}
 
-		error = "Timed out waiting for settled output reserve.";
+		error = "Timed out waiting for output preroll reserve.";
 		return false;
 	}
 

apps/RenderCadenceCompositor/control/RuntimeStateJson.h

@@ -251,7 +251,6 @@ inline std::string RuntimeStateToJson(const RuntimeStateJsonInput& input)
 	writer.KeyUInt("maxTemporalHistoryFrames", static_cast<uint64_t>(input.config.maxTemporalHistoryFrames));
 	writer.KeyDouble("previewFps", input.config.previewFps);
 	writer.KeyBool("enableExternalKeying", input.config.deckLink.externalKeyingEnabled);
-	writer.KeyUInt("startupSettleMs", static_cast<uint64_t>(input.config.startupSettle.count()));
 	writer.KeyString("inputVideoFormat", input.config.inputVideoFormat);
 	writer.KeyString("inputFrameRate", input.config.inputFrameRate);
 	writer.KeyString("outputVideoFormat", input.config.outputVideoFormat);

apps/RenderCadenceCompositor/frames/SystemFrameExchange.cpp

@@ -69,6 +69,7 @@ bool SystemFrameExchange::PublishCompleted(const SystemFrame& frame)
 	slot.state = SystemFrameSlotState::Completed;
 	slot.frameIndex = frame.frameIndex;
 	mCompletedIndices.push_back(frame.index);
+	TrimCompletedLocked();
 	++mCounters.completedFrames;
 	mCondition.notify_all();
 	return true;
@@ -231,6 +232,38 @@ bool SystemFrameExchange::AcquireFreeLocked(SystemFrame& frame)
 	return false;
 }
 
+bool SystemFrameExchange::DropOldestCompletedLocked()
+{
+	while (!mCompletedIndices.empty())
+	{
+		const std::size_t index = mCompletedIndices.front();
+		mCompletedIndices.pop_front();
+		if (index >= mSlots.size() || mSlots[index].state != SystemFrameSlotState::Completed)
+			continue;
+
+		Slot& slot = mSlots[index];
+		slot.state = SystemFrameSlotState::Free;
+		slot.frameIndex = 0;
+		++slot.generation;
+		++mCounters.completedDrops;
+		mCondition.notify_all();
+		return true;
+	}
+
+	return false;
+}
+
+void SystemFrameExchange::TrimCompletedLocked()
+{
+	if (mConfig.maxCompletedFrames == 0)
+		return;
+	while (CompletedCountLocked() > mConfig.maxCompletedFrames)
+	{
+		if (!DropOldestCompletedLocked())
+			return;
+	}
+}
+
 bool SystemFrameExchange::IsValidLocked(const SystemFrame& frame) const
 {
 	return frame.index < mSlots.size() && mSlots[frame.index].generation == frame.generation;

apps/RenderCadenceCompositor/frames/SystemFrameExchange.h

@@ -40,6 +40,8 @@ private:
 	};
 
 	bool AcquireFreeLocked(SystemFrame& frame);
+	bool DropOldestCompletedLocked();
+	void TrimCompletedLocked();
 	bool IsValidLocked(const SystemFrame& frame) const;
 	void FillFrameLocked(std::size_t index, SystemFrame& frame);
 	std::size_t CompletedCountLocked() const;

apps/RenderCadenceCompositor/frames/SystemFrameTypes.h

@@ -20,6 +20,7 @@ struct SystemFrameExchangeConfig
 	VideoIOPixelFormat pixelFormat = VideoIOPixelFormat::Bgra8;
 	unsigned rowBytes = 0;
 	std::size_t capacity = 0;
+	std::size_t maxCompletedFrames = 0;
 };
 
 struct SystemFrame

apps/RenderCadenceCompositor/telemetry/CadenceTelemetry.h

@@ -53,6 +53,12 @@ struct CadenceTelemetrySnapshot
 	bool deckLinkBufferedAvailable = false;
 	uint64_t deckLinkBuffered = 0;
 	double deckLinkScheduleCallMilliseconds = 0.0;
+	bool deckLinkScheduleLeadAvailable = false;
+	int64_t deckLinkPlaybackStreamTime = 0;
+	uint64_t deckLinkPlaybackFrameIndex = 0;
+	uint64_t deckLinkNextScheduleFrameIndex = 0;
+	int64_t deckLinkScheduleLeadFrames = 0;
+	uint64_t deckLinkScheduleRealignments = 0;
 };
 
 class CadenceTelemetry
@@ -92,6 +98,12 @@ public:
 		snapshot.deckLinkBufferedAvailable = outputMetrics.actualBufferedFramesAvailable;
 		snapshot.deckLinkBuffered = outputMetrics.actualBufferedFrames;
 		snapshot.deckLinkScheduleCallMilliseconds = outputMetrics.scheduleCallMilliseconds;
+		snapshot.deckLinkScheduleLeadAvailable = outputMetrics.scheduleLeadAvailable;
+		snapshot.deckLinkPlaybackStreamTime = outputMetrics.playbackStreamTime;
+		snapshot.deckLinkPlaybackFrameIndex = outputMetrics.playbackFrameIndex;
+		snapshot.deckLinkNextScheduleFrameIndex = outputMetrics.nextScheduleFrameIndex;
+		snapshot.deckLinkScheduleLeadFrames = outputMetrics.scheduleLeadFrames;
+		snapshot.deckLinkScheduleRealignments = outputMetrics.scheduleRealignmentCount;
 
 		if (mHasLastSample && seconds > 0.0)
 		{

apps/RenderCadenceCompositor/telemetry/CadenceTelemetryJson.h

@@ -61,6 +61,16 @@ inline void WriteCadenceTelemetryJson(JsonWriter& writer, const CadenceTelemetry
 	else
 		writer.Null();
 	writer.KeyDouble("scheduleCallMs", snapshot.deckLinkScheduleCallMilliseconds);
+	writer.KeyBool("deckLinkScheduleLeadAvailable", snapshot.deckLinkScheduleLeadAvailable);
+	writer.Key("deckLinkScheduleLeadFrames");
+	if (snapshot.deckLinkScheduleLeadAvailable)
+		writer.Int(snapshot.deckLinkScheduleLeadFrames);
+	else
+		writer.Null();
+	writer.KeyUInt("deckLinkPlaybackFrameIndex", snapshot.deckLinkPlaybackFrameIndex);
+	writer.KeyUInt("deckLinkNextScheduleFrameIndex", snapshot.deckLinkNextScheduleFrameIndex);
+	writer.KeyInt("deckLinkPlaybackStreamTime", snapshot.deckLinkPlaybackStreamTime);
+	writer.KeyUInt("deckLinkScheduleRealignments", snapshot.deckLinkScheduleRealignments);
 	writer.EndObject();
 }
 

apps/RenderCadenceCompositor/video/DeckLinkOutput.cpp

@@ -15,6 +15,7 @@ bool DeckLinkOutput::Initialize(const DeckLinkOutputConfig& config, CompletionCa
 	mCompletionCallback = completionCallback;
 
 	VideoFormatSelection formats;
+	formats.output = config.outputVideoMode;
 	if (!mSession.DiscoverDevicesAndModes(formats, error))
 		return false;
 	if (!mSession.SelectPreferredFormats(formats, config.outputAlphaRequired, error))
@@ -76,6 +77,12 @@ DeckLinkOutputMetrics DeckLinkOutput::Metrics() const
 	metrics.actualBufferedFramesAvailable = state.actualDeckLinkBufferedFramesAvailable;
 	metrics.actualBufferedFrames = state.actualDeckLinkBufferedFrames;
 	metrics.scheduleCallMilliseconds = state.deckLinkScheduleCallMilliseconds;
+	metrics.scheduleLeadAvailable = state.deckLinkScheduleLeadAvailable;
+	metrics.playbackStreamTime = state.deckLinkPlaybackStreamTime;
+	metrics.playbackFrameIndex = state.deckLinkPlaybackFrameIndex;
+	metrics.nextScheduleFrameIndex = state.deckLinkNextScheduleFrameIndex;
+	metrics.scheduleLeadFrames = state.deckLinkScheduleLeadFrames;
+	metrics.scheduleRealignmentCount = state.deckLinkScheduleRealignmentCount;
 	return metrics;
 }
 

apps/RenderCadenceCompositor/video/DeckLinkOutput.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "DeckLinkDisplayMode.h"
 #include "DeckLinkSession.h"
 #include "VideoIOTypes.h"
 
@@ -12,6 +13,7 @@ namespace RenderCadenceCompositor
 {
 struct DeckLinkOutputConfig
 {
+	VideoFormat outputVideoMode;
 	bool externalKeyingEnabled = false;
 	bool outputAlphaRequired = false;
 };
@@ -26,6 +28,12 @@ struct DeckLinkOutputMetrics
 	bool actualBufferedFramesAvailable = false;
 	uint64_t actualBufferedFrames = 0;
 	double scheduleCallMilliseconds = 0.0;
+	bool scheduleLeadAvailable = false;
+	int64_t playbackStreamTime = 0;
+	uint64_t playbackFrameIndex = 0;
+	uint64_t nextScheduleFrameIndex = 0;
+	int64_t scheduleLeadFrames = 0;
+	uint64_t scheduleRealignmentCount = 0;
 };
 
 class DeckLinkOutput

apps/RenderCadenceCompositor/video/DeckLinkOutputThread.h

@@ -77,7 +77,11 @@ private:
 		while (!mStopping)
 		{
 			const auto exchangeMetrics = mExchange.Metrics();
-			if (exchangeMetrics.scheduledCount >= mConfig.targetBufferedFrames)
+			const auto outputMetrics = mOutput.Metrics();
+			const std::size_t bufferedFrames = outputMetrics.actualBufferedFramesAvailable
+				? static_cast<std::size_t>(outputMetrics.actualBufferedFrames)
+				: exchangeMetrics.scheduledCount;
+			if (bufferedFrames >= mConfig.targetBufferedFrames)
 			{
 				std::this_thread::sleep_for(mConfig.idleSleep);
 				continue;