feat: IMaaContext.WaitFreezes()

MaaXYZ/MaaFramework#1095

MaaXYZ/MaaFramework@3952704

Author: moomiji

docs/articles/overview-of-wrapper-and-api.md

@@ -184,6 +184,7 @@ IMaaDisposable Derived:
 | IMaaContext.RunAction() | `MaaContextRunAction` |
 | IMaaContext.RunRecognitionDirect() | `MaaContextRunRecognitionDirect` |
 | IMaaContext.RunActionDirect() | `MaaContextRunActionDirect` |
+| IMaaContext.WaitFreezes() | `MaaContextWaitFreezes` |
 | IMaaContext.OverridePipeline() | `MaaContextOverridePipeline` |
 | IMaaContext.OverrideNext() | `MaaContextOverrideNext` |
 | IMaaContext.OverrideImage() | `MaaContextOverrideImage` |

src/MaaFramework.Binding.Native/Interop/Framework/Instance/MaaContext.cs

@@ -49,6 +49,10 @@ public static partial class MaaContext
     [LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
     public static partial MaaActId MaaContextRunActionDirect(MaaContextHandle context, string actionType, string actionParam, MaaRectHandle box, string recoDetail);
 
+    [LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
+    [return: MarshalAs(UnmanagedType.U1)]
+    public static partial bool MaaContextWaitFreezes(MaaContextHandle context, MaaSize time, MaaRectHandle roi, string waitFreezesParam);
+
     [LibraryImport("MaaFramework", StringMarshalling = StringMarshalling.Utf8)]
     [return: MarshalAs(UnmanagedType.U1)]
     public static partial bool MaaContextOverridePipeline(MaaContextHandle context, string pipelineOverride);

src/MaaFramework.Binding.Native/MaaContext.cs

@@ -158,6 +158,28 @@ public MaaContext(MaaContextHandle contextHandle, MaaTasker tasker)
             : ActionDetail.Query<MaaRectBuffer>(actionId, Tasker);
     }
 
+    /// <inheritdoc/>
+    public bool WaitFreezes(TimeSpan time, IMaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}")
+        => WaitFreezes((MaaSize)time.TotalMilliseconds, (MaaRectBuffer)recognitionBox, waitFreezesParam);
+
+    /// <inheritdoc cref="IMaaContext.WaitFreezes(TimeSpan, IMaaRectBuffer, string)"/>
+    public bool WaitFreezes(TimeSpan time, MaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}")
+        => WaitFreezes((MaaSize)time.TotalMilliseconds, recognitionBox, waitFreezesParam);
+
+    /// <inheritdoc/>
+    public bool WaitFreezes(MaaSize millisecondsTime, IMaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}")
+        => WaitFreezes(millisecondsTime, (MaaRectBuffer)recognitionBox, waitFreezesParam);
+
+    /// <inheritdoc cref="IMaaContext.WaitFreezes(ulong, IMaaRectBuffer, string)"/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaContextWaitFreezes"/>.
+    /// </remarks>
+    public bool WaitFreezes(MaaSize millisecondsTime, MaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}")
+    {
+        ArgumentNullException.ThrowIfNull(recognitionBox);
+        return MaaContextWaitFreezes(Handle, millisecondsTime, recognitionBox.Handle, waitFreezesParam);
+    }
+
     /// <inheritdoc/>
     /// <remarks>
     ///     Wrapper of <see cref="MaaContextOverridePipeline"/>.

src/MaaFramework.Binding/IMaaContext.cs

@@ -76,6 +76,27 @@ public interface IMaaContext : ICloneable
     /// <exception cref="ArgumentNullException"/>
     ActionDetail? RunActionDirect(string type, [StringSyntax("Json")] string param, IMaaRectBuffer recognitionBox, [StringSyntax("Json")] string recognitionDetail = "");
 
+    /// <summary>
+    ///     Waits for screen to stabilize (freeze).
+    /// </summary>
+    /// <param name="millisecondsTime">The wait time in milliseconds.</param>
+    /// <param name="recognitionBox">The recognition hit box, used when target is Self to calculate ROI.</param>
+    /// <param name="waitFreezesParam">The wait parameters.<para>Supports time, target, target_offset, threshold, method, rate_limit, timeout.</para></param>
+    /// <returns><see langword="true"/> if the operation was executed successfully; otherwise, <see langword="false"/>.</returns>
+    /// <remarks>
+    ///     <paramref name="millisecondsTime"/> and <paramref name="waitFreezesParam"/>.time are mutually exclusive.
+    /// </remarks>
+    bool WaitFreezes(MaaSize millisecondsTime, IMaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}");
+
+    /// <param name="time">The wait time.</param>
+    /// <param name="recognitionBox">The recognition hit box, used when target is Self to calculate ROI.</param>
+    /// <param name="waitFreezesParam">The wait parameters.<para>Supports time, target, target_offset, threshold, method, rate_limit, timeout.</para></param>
+    /// <remarks>
+    ///     <paramref name="time"/> and <paramref name="waitFreezesParam"/>.time are mutually exclusive.
+    /// </remarks>
+    /// <inheritdoc cref="WaitFreezes(ulong, IMaaRectBuffer, string)"/>
+    bool WaitFreezes(TimeSpan time, IMaaRectBuffer recognitionBox, [StringSyntax("Json")] string waitFreezesParam = "{}");
+
     /// <summary>
     ///     Overrides a pipeline.
     /// </summary>