RasterAnimationCompositionExample.cs

/*
	Icod.Terminal.RasterAnimation.Sample
	Sample application demonstrating Icod.Terminal RasterAnimation features.
	Copyright (C) 2026  Timothy J. Bruce <uniblab@hotmail.com>
*/

/*
	This program is free software: you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation, either version 3 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program.  If not, see <https://www.gnu.org/licenses/>.
*/
namespace Icod.Terminal.RasterAnimation.Sample;

using Icod.Terminal;

internal static class RasterAnimationCompositionExample {
	internal static string GetHeadlessTranscript() {
		return string.Join(
			"\n",
			[
				"Persistent-raster transaction semantics (headless; no terminal opened)",
				"Confirmation=Unspecified; Meaning=success strength was not classified; Rendered=NotClaimed",
				"Confirmation=OutputCommitted; Meaning=bytes were written and flushed; Rendered=NotClaimed",
				"Confirmation=ProtocolAcknowledged; Meaning=a correlated terminal response accepted the operation; Rendered=NotClaimed",
				"LiveQualification=NotRun; Reason=headless execution cannot establish rendered output"
			]
		) + "\n";
	}

	internal static string FormatMutationOutcome(
		string operation,
		TerminalControlMutationResult result
	) {
		ArgumentException.ThrowIfNullOrWhiteSpace( operation );
		if ( result.Succeeded ) {
			return string.Concat(
				"Operation=", operation,
				"; Status=", result.Status.ToString(),
				"; Confirmation=", result.Confirmation.ToString(),
				"; Fallback=None; Rendered=NotClaimed"
			);
		}
		return string.Concat(
			"Operation=", operation,
			"; Status=", result.Status.ToString(),
			"; Fallback=",
			string.IsNullOrWhiteSpace( result.Message )
				? "Controlled text fallback"
				: result.Message,
			"; Rendered=NotClaimed"
		);
	}

	internal static string FormatExceptionOutcome(
		string operation,
		Exception error
	) {
		ArgumentException.ThrowIfNullOrWhiteSpace( operation );
		ArgumentNullException.ThrowIfNull( error );
		string reason = error is TimeoutException
			? "Timeout after output may have committed; automatic retry is unsafe"
			: string.Concat(
				error.GetType().Name,
				" after output may have committed; automatic retry is unsafe"
			);
		return string.Concat(
			"Operation=", operation,
			"; Status=Ambiguous; Fallback=", reason,
			"; Rendered=NotClaimed"
		);
	}

	internal static string FormatCleanupOutcome(
		bool succeeded,
		string? reason = null
	) {
		return string.Concat(
			"Operation=Resource cleanup; Status=",
			succeeded ? "Available" : "Failed",
			"; Fallback=",
			succeeded
				? "None"
				: string.IsNullOrWhiteSpace( reason )
					? "Cleanup did not complete"
					: reason,
			"; Cleanup=", succeeded ? "Completed" : "Failed",
			"; Rendered=NotClaimed"
		);
	}

	internal static async ValueTask<bool> VerifyPrerequisiteAsync(
		TerminalSession session,
		CancellationToken cancellationToken = default
	) {
		ArgumentNullException.ThrowIfNull( session );
		TerminalCapabilityStatus graphics = await session.VerifyCapabilityAsync(
			TerminalCapability.PersistentRasterGraphics,
			cancellationToken
		);
		TerminalCapabilityStatus animation = session.InspectCapability(
			TerminalCapability.PersistentRasterAnimation
		);
		return graphics.IsUsable
			&& TerminalCapabilityEndpointAvailability.Available
				== animation.EndpointAvailability
			&& TerminalCapabilitySupport.Unsupported != animation.Support;
	}

	internal static ValueTask<TerminalControlMutationResult> ComposeAsync(
		TerminalRasterAnimation animation,
		TerminalRasterAnimationFrame destination,
		CancellationToken cancellationToken = default
	) {
		ArgumentNullException.ThrowIfNull( animation );
		ArgumentNullException.ThrowIfNull( destination );
		return animation.ComposeFrameAsync(
			animation.RootFrame,
			destination,
			new TerminalRasterSourceRectangle( 0, 0, 1, 1 ),
			1,
			1,
			TerminalRasterFrameCompositionMode.Replace,
			cancellationToken
		);
	}

	internal static ValueTask<TerminalControlMutationResult> UpdateRegionAsync(
		TerminalRasterAnimation animation,
		TerminalRasterAnimationFrame destination,
		CancellationToken cancellationToken = default
	) {
		ArgumentNullException.ThrowIfNull( animation );
		ArgumentNullException.ThrowIfNull( destination );
		TerminalRasterImage replacement = TerminalRasterImage.CreateRgba32(
			1,
			1,
			[ 32, 224, 160, 255 ]
		);
		return animation.UpdateFrameRegionAsync(
			destination,
			replacement,
			destinationX: 0,
			destinationY: 1,
			cancellationToken
		);
	}
}