/// <summary>
/// Convert the <c>XRCpuImage</c> to one of the supported formats using the specified
/// <paramref name="conversionParams"/>. The conversion is performed asynchronously. Use the returned
/// <see cref="AsyncConversion"/> to check for the status of the conversion, and retrieve the data
/// when complete.
/// </summary>
/// <remarks>
/// It is safe to <c>Dispose</c> the <c>XRCpuImage</c> before the asynchronous operation has completed.
/// </remarks>
/// <param name="conversionParams">The parameters to use for the conversion.</param>
/// <returns>A <see cref="AsyncConversion"/> which can be used to check the status of the
/// conversion operation and get the resulting data.</returns>
/// <seealso cref="FormatSupported"/>
public AsyncConversion ConvertAsync(ConversionParams conversionParams)
{
ValidateNativeHandleAndThrow();
ValidateConversionParamsAndThrow(conversionParams);
return(new AsyncConversion(m_Api, m_NativeHandle, conversionParams));
}
private void UpdateOutputHandler(object sender, EventArgs e)
{
Note[] notes = null;
var CP = new ConversionParams();
CP.DefaultDuration = (int)numberBoxDuration.Value;
CP.DefaultCommaPause = (int)numberBoxComma.Value;
CP.DefaultPause = (int)numberBoxPause.Value;
CP.DefaultSemiColonPause = (int)numberBoxSemicolonPause.Value;
if (radioCode.Checked)
{
notes = SequenceConversion.CSharpCodeToNoteArray(textBoxSource.Text, CP);
}
else if (radioMusicSheet.Checked)
{
notes = SequenceConversion.MusicSheetToNoteArray(textBoxSource.Text, CP);
}
else if (radioPowerShell.Checked)
{
notes = SequenceConversion.PowerShellToNoteArray(textBoxSource.Text, CP);
}
else if (radioBash.Checked)
{
notes = SequenceConversion.BashToNoteArray(textBoxSource.Text, CP);
}
textBoxOutput.Text = SequenceConversion.NoteArrayToSequence(notes);
}
static unsafe void OnAsyncConversionComplete(
AsyncConversionStatus status, ConversionParams conversionParams, IntPtr dataPtr,
int dataLength, IntPtr context)
{
var handle = GCHandle.FromIntPtr(context);
var onComplete = (Action <AsyncConversionStatus, ConversionParams, NativeArray <byte> >)handle.Target;
if (onComplete != null)
{
var data = NativeArrayUnsafeUtility.ConvertExistingDataToNativeArray <byte>(
(void *)dataPtr, dataLength, Allocator.None);
#if ENABLE_UNITY_COLLECTIONS_CHECKS
var safetyHandle = AtomicSafetyHandle.Create();
NativeArrayUnsafeUtility.SetAtomicSafetyHandle(ref data, safetyHandle);
#endif
onComplete(status, conversionParams, data);
#if ENABLE_UNITY_COLLECTIONS_CHECKS
AtomicSafetyHandle.Release(safetyHandle);
#endif
}
handle.Free();
}
/// <summary>
/// Method to be implemented by the provider to convert the image with handle
/// <paramref name="nativeHandle"/> using the provided <paramref cref="conversionParams"/>.
/// </summary>
/// <param name="nativeHandle">A unique identifier for the camera image to convert.</param>
/// <param name="conversionParams">The parameters to use during the conversion.</param>
/// <param name="destinationBuffer">A buffer to write the converted image to.</param>
/// <param name="bufferLength">The number of bytes available in the buffer.</param>
/// <returns>
/// <c>true</c> if the image was converted and stored in <paramref name="destinationBuffer"/>.
/// </returns>
/// <exception cref="System.NotSupportedException">Thrown if the implementation does not support camera
/// image.</exception>
public virtual bool TryConvert(
int nativeHandle,
ConversionParams conversionParams,
IntPtr destinationBuffer,
int bufferLength)
{
throw new NotSupportedException("Camera image conversion is not supported by this implementation");
}
/// <summary>
/// Method to be implemented by the provider. It is similar to
/// <see cref="ConvertAsync(int, ConversionParams)"/> but takes a delegate to invoke when the
/// request is complete, rather than returning a request id.
/// </summary>
/// <remarks>
/// If the first parameter to <paramref name="callback"/> is
/// <see cref="AsyncConversionStatus.Ready"/>, the <c>dataPtr</c> parameter must be valid
/// for the duration of the invocation. The data can be destroyed immediately upon return. The
/// <paramref name="context"/> parameter must be passed back to the <paramref name="callback"/>.
/// </remarks>
/// <param name="nativeHandle">A unique identifier for the camera image to convert.</param>
/// <param name="conversionParams">The parameters to use during the conversion.</param>
/// <param name="callback">A delegate which must be invoked when the request is complete, whether the
/// conversion was successfully or not.</param>
/// <param name="context">A native pointer which must be passed back unaltered to
/// <paramref name="callback"/>.</param>
/// <exception cref="System.NotSupportedException">Thrown if the implementation does not support camera
/// image.</exception>
public virtual void ConvertAsync(
int nativeHandle,
ConversionParams conversionParams,
OnImageRequestCompleteDelegate callback,
IntPtr context)
{
throw new NotSupportedException("Camera image conversion is not supported by this implementation");
}
/// <summary>
/// Start the image conversion using this class to interact with the asynchronous conversion and results.
/// </summary>
/// <param name="api">The CPU image API performing the image conversion.</param>
/// <param name="nativeHandle">The native handle for the camera image.</param>
/// <param name="conversionParams">The parameters for image conversion.</param>
internal AsyncConversion(XRCpuImage.Api api, int nativeHandle, ConversionParams conversionParams)
{
m_Api = api;
m_RequestId = m_Api.ConvertAsync(nativeHandle, conversionParams);
this.conversionParams = conversionParams;
#if ENABLE_UNITY_COLLECTIONS_CHECKS
m_SafetyHandle = AtomicSafetyHandle.Create();
#endif
}
/// <summary>
/// <para>Convert the <c>XRCpuImage</c> to one of the supported formats using the specified
/// <paramref name="conversionParams"/>. The conversion is performed asynchronously, and
/// <paramref name="onComplete"/> is invoked when the conversion is complete, whether successful or not.</para>
/// <para>The <c>NativeArray</c> provided in the <paramref name="onComplete"/> delegate is only valid during
/// the invocation and is disposed immediately upon return.</para>
/// </summary>
/// <param name="conversionParams">The parameters to use for the conversion.</param>
/// <param name="onComplete">A delegate to invoke when the conversion operation completes. The delegate is
/// always invoked, regardless of whether the conversion succeeded.</param>
/// <seealso cref="FormatSupported"/>
public void ConvertAsync(
ConversionParams conversionParams,
Action <AsyncConversionStatus, ConversionParams, NativeArray <byte> > onComplete)
{
ValidateNativeHandleAndThrow();
ValidateConversionParamsAndThrow(conversionParams);
var handle = GCHandle.Alloc(onComplete);
var context = GCHandle.ToIntPtr(handle);
m_Api.ConvertAsync(m_NativeHandle, conversionParams, s_OnAsyncConversionCompleteDelegate, context);
}
/// <summary>
/// Convert the `XRCpuImage` to one of the supported formats using the specified
/// <paramref name="conversionParams"/>.
/// </summary>
/// <param name="conversionParams">The parameters for the image conversion.</param>
/// <param name="destinationBuffer">A pointer to memory to which to write the converted image.</param>
/// <param name="bufferLength">The number of bytes pointed to by <paramref name="destinationBuffer"/>. Must be
/// greater than or equal to the value returned by
/// <see cref="GetConvertedDataSize(ConversionParams)"/>.</param>
/// <exception cref="System.ArgumentException">Thrown if the <paramref name="bufferLength"/> is smaller than
/// the data size required by the conversion.</exception>
/// <exception cref="System.InvalidOperationException">Thrown if the conversion failed.</exception>
/// <seealso cref="FormatSupported"/>
public void Convert(ConversionParams conversionParams, IntPtr destinationBuffer, int bufferLength)
{
ValidateNativeHandleAndThrow();
ValidateConversionParamsAndThrow(conversionParams);
int requiredDataSize = GetConvertedDataSize(conversionParams);
if (bufferLength < requiredDataSize)
{
throw new ArgumentException($"Conversion requires {requiredDataSize} bytes but only provided {bufferLength} bytes.", nameof(bufferLength));
}
if (!m_Api.TryConvert(m_NativeHandle, conversionParams, destinationBuffer, bufferLength))
{
throw new InvalidOperationException("Conversion failed.");
}
}
/// <summary>
/// Ensure the conversion parameters are valid.
/// </summary>
/// <param name="conversionParams">The conversion parameters to validate.</param>
/// <exception cref="System.ArgumentOutOfRangeException">Thrown if the input image rect exceeds the actual
/// image dimensions or if the output dimensions exceed the input dimensions.</exception>
/// <exception cref="System.ArgumentException">Thrown if the texture format is not suppported.</exception>
/// <seealso cref="FormatSupported"/>
void ValidateConversionParamsAndThrow(ConversionParams conversionParams)
{
if ((conversionParams.inputRect.x + conversionParams.inputRect.width > width) ||
(conversionParams.inputRect.y + conversionParams.inputRect.height > height))
{
throw new ArgumentOutOfRangeException(
nameof(conversionParams),
"Input rect must be completely within the original image.");
}
if ((conversionParams.outputDimensions.x > conversionParams.inputRect.width) ||
(conversionParams.outputDimensions.y > conversionParams.inputRect.height))
{
throw new ArgumentOutOfRangeException($"Output dimensions must be less than or equal to the inputRect's dimensions: ({conversionParams.outputDimensions.x}x{conversionParams.outputDimensions.y} > {conversionParams.inputRect.width}x{conversionParams.inputRect.height}).");
}
if (!FormatSupported(conversionParams.outputFormat))
{
throw new ArgumentException("TextureFormat not supported.", nameof(conversionParams));
}
}
/// <summary>
/// Method to be implemented by the provider to create an asynchronous request to convert a camera image,
/// similar to <see cref="TryConvert"/> except the conversion should happen on a thread other than the
/// calling (main) thread.
/// </summary>
/// <param name="nativeHandle">A unique identifier for the camera image to convert.</param>
/// <param name="conversionParams">The parameters to use during the conversion.</param>
/// <returns>A unique identifier for this request.</returns>
/// <exception cref="System.NotSupportedException">Thrown if the implementation does not support camera
/// image.</exception>
public virtual int ConvertAsync(
int nativeHandle,
ConversionParams conversionParams)
{
throw new NotSupportedException("Camera image conversion is not supported by this implementation");
}
/// <summary>
/// Convert the `XRCpuImage` to one of the supported formats using the specified
/// <paramref name="conversionParams"/>.
/// </summary>
/// <param name="conversionParams">The parameters for the image conversion.</param>
/// <param name="destinationBuffer">The destination buffer for the converted data. The buffer must be
/// large enough to hold the converted data, that is, at least as large as the value returned by
/// <see cref="GetConvertedDataSize(ConversionParams)"/>.</param>
/// <exception cref="System.ArgumentException">Thrown if the <paramref name="destinationBuffer"/>
/// has insufficient space for the converted data.</exception>
/// <exception cref="System.InvalidOperationException">Thrown if the conversion failed.</exception>
/// <seealso cref="FormatSupported"/>
public unsafe void Convert(ConversionParams conversionParams, NativeSlice <byte> destinationBuffer)
{
Convert(conversionParams, new IntPtr(destinationBuffer.GetUnsafePtr()), destinationBuffer.Length);
}
/// <summary>
/// Get the number of bytes required to store a converted image with the given parameters.
/// </summary>
/// <param name="conversionParams">The desired conversion parameters.</param>
/// <returns>The number of bytes required to store the converted image.</returns>
/// <exception cref="System.ArgumentException">Thrown if the desired format is not supported.</exception>
/// <exception cref="System.ArgumentOutOfRangeException">Thrown if the desired dimensions exceed the native
/// image dimensions.</exception>
/// <exception cref="System.InvalidOperationException">Thrown if the image is invalid.</exception>
/// <seealso cref="FormatSupported"/>
public int GetConvertedDataSize(ConversionParams conversionParams)
{
return(GetConvertedDataSize(
conversionParams.outputDimensions,
conversionParams.outputFormat));
}
