Class MutableRuntimeReferenceImageLibrary

A reference image library that can be constructed and modified at runtime.

Inheritance
Object
RuntimeReferenceImageLibrary
MutableRuntimeReferenceImageLibrary
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 AR Subsystems package 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.
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 handle is IntPtr.Zero.

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 state has a non-zero IntPtr (non-zero means the concrete class should have overriden this method).

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 foreach statement.

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
TextureFormat

The supported format at index.

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
TextureFormat

The supported format at index.

IsTextureFormatSupported(TextureFormat)

Determines whether the given format is supported.

Declaration
public bool IsTextureFormatSupported(TextureFormat format)
Parameters
Type Name Description
TextureFormat format

The TextureFormat to test.
Returns
Type Description
Boolean

true if format is supported for image addition; otherwise, false.

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
NativeSlice<Byte> imageBytes

The raw image bytes in format.
Vector2Int sizeInPixels

The width and height of the image, in pixels.
TextureFormat format

The format of imageBytes. Test for and enumerate supported formats with supportedTextureFormatCount, GetSupportedTextureFormatAt(Int32), and IsTextureFormatSupported(TextureFormat).
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.
JobHandle inputDeps

(Optional) input dependencies for the add image job.
Returns
Type Description
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 imageBytes does not contain any bytes.
ArgumentException

Thrown if referenceImage.guid is not Guid.Empty.
ArgumentNullException

Thrown if referenceImage.name is null.
ArgumentOutOfRangeException

Thrown if referenceImage.specifySize is true and referenceImage.size.x contains a value less than or equal to zero.
InvalidOperationException

Thrown if the format is not supported. You can query for support using IsTextureFormatSupported(TextureFormat).
ArgumentOutOfRangeException

Thrown if sizeInPixels.x or sizeInPixels.y is less than or equal to zero.

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
NativeSlice<Byte> imageBytes

The raw image bytes in format. Assume the bytes will be valid until the job completes.
Vector2Int sizeInPixels

The width and height of the image, in pixels.
TextureFormat format

The format of imageBytes. The format has already been validated with IsTextureFormatSupported(TextureFormat).
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.
JobHandle inputDeps

Input dependencies for the add image job.
Returns
Type Description
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
NativeSlice<Byte> imageBytes

The raw image bytes in format.
Vector2Int sizeInPixels

The width and height of the image, in pixels.
TextureFormat format

The format of imageBytes. Test for and enumerate supported formats with supportedTextureFormatCount, GetSupportedTextureFormatAt(Int32), and IsTextureFormatSupported(TextureFormat).
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.
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 imageBytes does not contain any bytes.
ArgumentException

Thrown if referenceImage's guid is not Empty.
ArgumentNullException

Thrown if referenceImage's name is null.
ArgumentOutOfRangeException

Thrown if referenceImage's specifySize is true but referenceImage.size contains values less than or equal to zero.
InvalidOperationException

Thrown if the format is not supported. You can query for support using IsTextureFormatSupported(TextureFormat).
ArgumentOutOfRangeException

Thrown if sizeInPixels contains values less than or equal to zero.

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
NativeSlice<Byte> imageBytes

The raw image bytes in format. You can assume the bytes are valid until the job completes.
Vector2Int sizeInPixels

The width and height of the image, in pixels.
TextureFormat format

The format of imageBytes. The format has already been validated with IsTextureFormatSupported(TextureFormat).
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.
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 true, then this method should be implemented by the derived class.

See Also