Class MutableRuntimeReferenceImageLibrary
A reference image library that can be constructed and modified at runtime.
Inherited Members
Namespace: UnityEngine.XR.ARSubsystems
Syntax
public abstract class MutableRuntimeReferenceImageLibrary : RuntimeReferenceImageLibrary, IReferenceImageLibrary
Remarks
This differs from an XRReferenceImageLibrary, which can only be constructed in the Editor and is immutable at runtime.
Important
Implementors: XRImageTrackingSubsystem providers must implement this class for their provider if
supportsMutableLibrary is true
to provide the functionality
to support runtime mutable libraries.
This is not something consumers of the UnityEngine.XR.ARSubsystems namespace should implement.
Properties
supportedTextureFormatCount
The number of texture formats that are supported for image addition.
Declaration
public abstract int supportedTextureFormatCount { get; }
Property Value
Type | Description |
---|---|
Int32 |
supportsValidation
(Read Only) True
if this MutableRuntimeReferenceImageLibrary supports the validation of images
when added via ScheduleAddImageWithValidationJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle).
Declaration
public virtual bool supportsValidation { get; }
Property Value
Type | Description |
---|---|
Boolean |
Remarks
Important
Implementors: If this is true
, then your implementation must also override:
Methods
CreateAddJobState(IntPtr, JobHandle)
Derived classes should call this to create an AddReferenceImageJobState to be returned by its implementation of ScheduleAddImageWithValidationJobImpl(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle).
Declaration
protected AddReferenceImageJobState CreateAddJobState(IntPtr handle, JobHandle jobHandle)
Parameters
Type | Name | Description |
---|---|---|
IntPtr | handle | A handle to the job state. This should be unique to this job state. |
Unity.Jobs.JobHandle | jobHandle | The JobHandle associated with the add job state. |
Returns
Type | Description |
---|---|
AddReferenceImageJobState | Returns a new AddReferenceImageJobState that contains information about the state of an add image job. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if supportsValidation is true and
|
GetAddReferenceImageJobStatus(AddReferenceImageJobState)
Get the status of an AddReferenceImageJobState.
Declaration
protected virtual AddReferenceImageJobStatus GetAddReferenceImageJobStatus(AddReferenceImageJobState state)
Parameters
Type | Name | Description |
---|---|---|
AddReferenceImageJobState | state | The state whose status should be retrieved. |
Returns
Type | Description |
---|---|
AddReferenceImageJobStatus | Returns the AddReferenceImageJobStatus of an existing AddReferenceImageJobState. |
Remarks
Important
Implementors: If supportsValidation is true
, then you must also implement this method.
Exceptions
Type | Condition |
---|---|
NotImplementedException | Thrown if the |
GetEnumerator()
Gets an enumerator for this collection of reference images. This allows this image library to act as a collection in a foreach
statement.
The MutableRuntimeReferenceImageLibrary.Enumerator is a struct
, so no garbage is generated.
Declaration
public MutableRuntimeReferenceImageLibrary.Enumerator GetEnumerator()
Returns
Type | Description |
---|---|
MutableRuntimeReferenceImageLibrary.Enumerator | An enumerator that can be used in a |
GetSupportedTextureFormatAt(Int32)
Returns the supported texture format at index
. Useful for enumerating the supported texture formats for image addition.
Declaration
public TextureFormat GetSupportedTextureFormatAt(int index)
Parameters
Type | Name | Description |
---|---|---|
Int32 | index | The index of the format to retrieve. |
Returns
Type | Description |
---|---|
UnityEngine.TextureFormat | The supported format at |
GetSupportedTextureFormatAtImpl(Int32)
Derived methods should return the TextureFormat at the given index
.
index
has already been validated to be within [0..supportedTextureFormatCount].
Declaration
protected abstract TextureFormat GetSupportedTextureFormatAtImpl(int index)
Parameters
Type | Name | Description |
---|---|---|
Int32 | index | The index of the format to retrieve. |
Returns
Type | Description |
---|---|
UnityEngine.TextureFormat | The supported format at |
IsTextureFormatSupported(TextureFormat)
Determines whether the given format
is supported.
Declaration
public bool IsTextureFormatSupported(TextureFormat format)
Parameters
Type | Name | Description |
---|---|---|
UnityEngine.TextureFormat | format | The TextureFormat to test. |
Returns
Type | Description |
---|---|
Boolean |
|
ScheduleAddImageJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)
Asynchronously adds an image to this library.
Declaration
[Obsolete("Use ScheduleAddImageWithValidationJob instead. (2020-10-20)")]
public JobHandle ScheduleAddImageJob(NativeSlice<byte> imageBytes, Vector2Int sizeInPixels, TextureFormat format, XRReferenceImage referenceImage, JobHandle inputDeps = default(JobHandle))
Parameters
Type | Name | Description |
---|---|---|
Unity.Collections.NativeSlice<Byte> | imageBytes | The raw image bytes in |
UnityEngine.Vector2Int | sizeInPixels | The width and height of the image, in pixels. |
UnityEngine.TextureFormat | format | The format of |
XRReferenceImage | referenceImage | The XRReferenceImage data associated with the image to add to the library.
This includes information like physical dimensions, associated |
Unity.Jobs.JobHandle | inputDeps | (Optional) input dependencies for the add image job. |
Returns
Type | Description |
---|---|
Unity.Jobs.JobHandle | A JobHandle which can be used to chain together multiple tasks or to query for completion. Can be safely discarded. |
Remarks
Image addition can take some time (several frames) due to extra processing that must occur to insert the image into the library. This is done using the Unity Job System. The returned JobHandle can be used to chain together multiple tasks or to query for completion, but can be safely discarded if you do not need it.
This job, like all Unity jobs, can have dependencies (using the inputDeps
). This can be useful,
for example, if imageBytes
is the output of another job. If you are adding multiple
images to the library, it is not necessary to pass a previous ScheduleAddImageJob
JobHandle as the input
dependency to the next ScheduleAddImageJob
; they can be processed concurrently.
The imageBytes
must be valid until this job completes. The caller is responsible for managing its memory.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if |
ArgumentException | Thrown if |
ArgumentNullException | Thrown if |
ArgumentOutOfRangeException | Thrown if |
InvalidOperationException | Thrown if the |
ArgumentOutOfRangeException | Thrown if |
ScheduleAddImageJobImpl(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)
This method should schedule a Unity Job which adds an image to this reference image library.
Declaration
protected abstract JobHandle ScheduleAddImageJobImpl(NativeSlice<byte> imageBytes, Vector2Int sizeInPixels, TextureFormat format, XRReferenceImage referenceImage, JobHandle inputDeps)
Parameters
Type | Name | Description |
---|---|---|
Unity.Collections.NativeSlice<Byte> | imageBytes | The raw image bytes in |
UnityEngine.Vector2Int | sizeInPixels | The width and height of the image, in pixels. |
UnityEngine.TextureFormat | format | The format of |
XRReferenceImage | referenceImage | The XRReferenceImage data associated with the image to add to the library. This includes information like physical dimensions, associated Texture2D (optional), and string name. |
Unity.Jobs.JobHandle | inputDeps | Input dependencies for the add image job. |
Returns
Type | Description |
---|---|
Unity.Jobs.JobHandle | A JobHandle which can be used to chain together multiple tasks or to query for completion. |
See Also
ScheduleAddImageWithValidationJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)
Asynchronously adds an image to this library.
Declaration
public AddReferenceImageJobState ScheduleAddImageWithValidationJob(NativeSlice<byte> imageBytes, Vector2Int sizeInPixels, TextureFormat format, XRReferenceImage referenceImage, JobHandle inputDeps = default(JobHandle))
Parameters
Type | Name | Description |
---|---|---|
Unity.Collections.NativeSlice<Byte> | imageBytes | The raw image bytes in |
UnityEngine.Vector2Int | sizeInPixels | The width and height of the image, in pixels. |
UnityEngine.TextureFormat | format | The format of |
XRReferenceImage | referenceImage | The XRReferenceImage data associated with the image to add to the library. This includes information like physical dimensions, associated Texture2D (optional), and string name. The guid must be set to zero (Empty). A new guid is automatically generated for the new image. |
Unity.Jobs.JobHandle | inputDeps | (Optional) Input dependencies for the add image job. |
Returns
Type | Description |
---|---|
AddReferenceImageJobState | Returns an AddReferenceImageJobState that can be used to query the status of the job. The AddReferenceImageJobState can be used to determine whether the image was successfully added. Invalid images will be not be added to the reference image library. |
Remarks
Image addition can take some time (for example, several frames) due to the processing that must occur to insert the image into the library. This is done using the Unity Job System. The returned AddReferenceImageJobState allows your to query for the status of the job, and, if the job completed, whether it was successful. The job state includes the JobHandle which can be used to chain together multiple tasks.
This job, like all Unity jobs, can have dependencies (using the
inputDeps
). This can be useful, for example, if imageBytes
is the
output of another job. If you are adding multiple images to the library, it is not necessary to pass a
previous ScheduleAddImageWithValidationJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)'s JobHandle
as the input dependency to the next
ScheduleAddImageWithValidationJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle).
The imageBytes
must be valid until this job completes. The caller is responsible for
managing its memory. You can use the resulting JobHandle
to schedule a job that deallocates the
imageBytes
.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if |
ArgumentException | |
ArgumentNullException | Thrown if |
ArgumentOutOfRangeException | Thrown if |
InvalidOperationException | Thrown if the |
ArgumentOutOfRangeException | Thrown if |
ScheduleAddImageWithValidationJobImpl(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)
This method should schedule a Unity Job which adds an image to this reference image library.
Declaration
protected virtual AddReferenceImageJobState ScheduleAddImageWithValidationJobImpl(NativeSlice<byte> imageBytes, Vector2Int sizeInPixels, TextureFormat format, XRReferenceImage referenceImage, JobHandle inputDeps)
Parameters
Type | Name | Description |
---|---|---|
Unity.Collections.NativeSlice<Byte> | imageBytes | The raw image bytes in |
UnityEngine.Vector2Int | sizeInPixels | The width and height of the image, in pixels. |
UnityEngine.TextureFormat | format | The format of |
XRReferenceImage | referenceImage | The XRReferenceImage data associated with the image to add to the library. This includes information like physical dimensions, associated Texture2D (optional), and string name. |
Unity.Jobs.JobHandle | inputDeps | A JobHandle that represents input dependencies for the add image job. |
Returns
Type | Description |
---|---|
AddReferenceImageJobState | Returns an AddReferenceImageJobState which contains the state of the asynchronous image addition. |
Exceptions
Type | Condition |
---|---|
NotImplementedException | Thrown by this base class implementation. If
supportsValidation is |