Skip to content

doc: Improve documentation of WebRTC #1060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 8, 2024
Merged

doc: Improve documentation of WebRTC #1060

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2624896
Improve documentation of WebRTC
miyabi Dec 5, 2024
63c9a48
Improve examples
miyabi Dec 6, 2024
fc412f0
Update Runtime/Scripts/WebRTC.cs
miyabi Dec 7, 2024
e788e47
Update Runtime/Scripts/WebRTC.cs
miyabi Dec 7, 2024
e0d48e3
Update Runtime/Scripts/WebRTC.cs
miyabi Dec 7, 2024
ecff9a5
Update Runtime/Scripts/WebRTC.cs
miyabi Dec 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 90 additions & 22 deletions Runtime/Scripts/WebRTC.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -621,8 +621,17 @@ public enum NativeLoggingSeverity
};

/// <summary>
///
/// Provides utilities and management functions for integrating WebRTC functionality.
/// </summary>
/// <remarks>
/// `WebRTC` class provides a set of static methods and properties to manage the WebRTC functionality.
/// </remarks>
/// <example>
/// <code lang="cs"><![CDATA[
/// StartCoroutine(WebRTC.Update());
/// ]]></code>
/// </example>
/// <seealso cref="WebRTCSettings"/>
public static class WebRTC
{
#if UNITY_IOS
Expand Down Expand Up @@ -663,9 +672,17 @@ internal static void InitializeInternal(bool limitTextureSize = true, bool enabl
}

/// <summary>
///
/// Updates the texture data for all video tracks at the end of each frame.
/// </summary>
/// <returns></returns>
/// <remarks>
/// `Update` method updates the texture data for all video tracks at the end of each frame.
/// </remarks>
/// <returns>`IEnumerator` to facilitate coroutine execution.</returns>
/// <example>
/// <code lang="cs"><![CDATA[
/// StartCoroutine(WebRTC.Update());
/// ]]></code>
/// </example>
public static IEnumerator Update()
{
var instruction = new WaitForEndOfFrame();
Expand Down Expand Up @@ -705,15 +722,22 @@ public static IEnumerator Update()
}

/// <summary>
/// Executes any pending tasks generated asynchronously during the WebRTC runtime.
/// Executes any pending tasks generated asynchronously during the WebRTC runtime.
/// </summary>
/// <remarks>
/// `ExecutePendingTasks` method processes pending tasks generated during WebRTC operations, up to a specified timeout.
/// </remarks>
/// <param name="millisecondTimeout">
/// The amount of time in milliseconds that the task queue can take before task execution will cease.
/// The amount of time in milliseconds that the task queue can take before task execution will cease.
/// </param>
/// <returns>
/// <c>true</c> if all pending tasks were completed within <see cref="millisecondTimeout"/> milliseconds and <c>false</c>
/// otherwise.
/// `true` if all pending tasks were completed within <see cref="millisecondTimeout"/> milliseconds and `false` otherwise.
/// </returns>
/// <example>
/// <code lang="cs"><![CDATA[
/// WebRTC.ExecutePendingTasks(100);
/// ]]></code>
/// </example>
public static bool ExecutePendingTasks(int millisecondTimeout)
{
if (s_syncContext is ExecutableUnitySynchronizationContext executableContext)
Expand All @@ -725,7 +749,7 @@ public static bool ExecutePendingTasks(int millisecondTimeout)
}

/// <summary>
///
/// Controls whether texture size constraints are applied during WebRTC streaming.
/// </summary>
public static bool enableLimitTextureSize
{
Expand All @@ -734,8 +758,8 @@ public static bool enableLimitTextureSize
}

/// <summary>
/// Get & set the logger to use when logging debug messages inside the WebRTC package.
/// By default will use Debug.unityLogger.
/// Logger that is used for capturing debug messages within the WebRTC package.
/// Defaults to Debug.unityLogger.
/// </summary>
/// <exception cref="ArgumentNullException">Throws if setting a null logger.</exception>
public static ILogger Logger
Expand All @@ -756,10 +780,18 @@ public static ILogger Logger
}

/// <summary>
/// Configure native logging settings for WebRTC.
/// Configures native logging settings for WebRTC.
/// </summary>
/// <remarks>
/// `ConfigureNativeLogging` method is used to enable or disable native logging and set the native logging level.
/// </remarks>
/// <param name="enableNativeLogging">Enables or disable native logging.</param>
/// <param name="nativeLoggingSeverity">Sets the native logging level.</param>
/// <example>
/// <code lang="cs"><![CDATA[
/// WebRTC.ConfigureNativeLogging(true, NativeLoggingSeverity.Warning);
/// ]]></code>
/// </example>
public static void ConfigureNativeLogging(bool enableNativeLogging, NativeLoggingSeverity nativeLoggingSeverity)
{
if (enableNativeLogging)
Expand Down Expand Up @@ -860,9 +892,18 @@ internal static RTCError ValidateTextureSize(int width, int height, RuntimePlatf
}

/// <summary>
///
/// Validates the specified graphics format to ensure it is supported.
/// </summary>
/// <param name="format"></param>
/// <remarks>
/// `ValidateGraphicsFormat` method checks whether the provided `GraphicsFormat` is compatible with the current graphics device.
/// This method throws an `ArgumentException` if the format is not supported.
/// </remarks>
/// <param name="format">`GraphicsFormat` value to be validated.</param>
/// <example>
/// <code lang="cs"><![CDATA[
/// WebRTC.ValidateGraphicsFormat(format);
/// ]]></code>
/// </example>
public static void ValidateGraphicsFormat(GraphicsFormat format)
{
// can't recognize legacy format
Expand All @@ -883,21 +924,40 @@ public static void ValidateGraphicsFormat(GraphicsFormat format)
}

/// <summary>
///
/// Determines the appropriate RenderTextureFormat for a given GraphicsDeviceType.
/// </summary>
/// <param name="type"></param>
/// <returns></returns>
/// <remarks>
/// `GetSupportedRenderTextureFormat` method determines the appropriate `RenderTextureFormat` for a given `GraphicsDeviceType`.
/// </remarks>
/// <param name="type">`GraphicsDeviceType` for which `RenderTextureFormat` is being determined.</param>
/// <returns>`RenderTextureFormat` value for the specified `GraphicsDeviceType`.</returns>
/// <example>
/// <code lang="cs"><![CDATA[
/// RenderTextureFormat format = WebRTC.GetSupportedRenderTextureFormat(GraphicsDeviceType.Direct3D11);
/// ]]></code>
/// </example>
public static RenderTextureFormat GetSupportedRenderTextureFormat(GraphicsDeviceType type)
{
var graphicsFormat = GetSupportedGraphicsFormat(type);
return GraphicsFormatUtility.GetRenderTextureFormat(graphicsFormat);
}

/// <summary>
///
/// Determines the appropriate GraphicsFormat for a given GraphicsDeviceType.
/// </summary>
/// <param name="type"></param>
/// <returns></returns>
/// <remarks>
/// `GetSupportedGraphicsFormat` method determines the appropriate `GraphicsFormat` for a given `GraphicsDeviceType`.
/// </remarks>
/// <param name="type">`GraphicsDeviceType` for which `GraphicsFormat` is being determined.</param>
/// <returns>`GraphicsFormat` value for the specified `GraphicsDeviceType`.</returns>
/// <example>
/// <code lang="cs"><![CDATA[
/// int width = WebRTCSettings.StreamSize.x;
/// int height = WebRTCSettings.StreamSize.y;
/// GraphicsFormat format = WebRTC.GetSupportedGraphicsFormat(GraphicsDeviceType.Direct3D11);
/// RenderTexture texture = new RenderTexture(width, height, 0, format);
/// ]]></code>
/// </example>
public static GraphicsFormat GetSupportedGraphicsFormat(GraphicsDeviceType type)
{
if (QualitySettings.activeColorSpace == ColorSpace.Linear)
Expand Down Expand Up @@ -937,10 +997,18 @@ public static GraphicsFormat GetSupportedGraphicsFormat(GraphicsDeviceType type)
}

/// <summary>
///
/// Determines the appropriate TextureFormat for a given GraphicsDeviceType.
/// </summary>
/// <param name="type"></param>
/// <returns></returns>
/// <remarks>
/// `GetSupportedTextureFormat` method determines the appropriate `TextureFormat` for a given `GraphicsDeviceType`.
/// </remarks>
/// <param name="type">`GraphicsDeviceType` for which `TextureFormat` is being determined.</param>
/// <returns>`TextureFormat` value for the specified `GraphicsDeviceType`.</returns>
/// <example>
/// <code lang="cs"><![CDATA[
/// TextureFormat format = WebRTC.GetSupportedTextureFormat(GraphicsDeviceType.Direct3D11);
/// ]]></code>
/// </example>
public static TextureFormat GetSupportedTextureFormat(GraphicsDeviceType type)
{
var graphicsFormat = GetSupportedGraphicsFormat(type);
Expand Down