Class MutableRuntimeReferenceImageLibrary

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

Inheritance

Object

RuntimeReferenceImageLibrary

MutableRuntimeReferenceImageLibrary

Inherited Members

RuntimeReferenceImageLibrary.Item[Int32]

RuntimeReferenceImageLibrary.count

RuntimeReferenceImageLibrary.GetReferenceImageAt(Int32)

Namespace: UnityEngine.XR.ARSubsystems

Syntax

public abstract class MutableRuntimeReferenceImageLibrary : RuntimeReferenceImageLibrary, IReferenceImageLibrary

Remarks

This differs from an XRReferenceImageLibrary, which can only be constructed at edit-time and is immutable at runtime.

Note for 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 ARSubsystems 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) Whether 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

Note to implementors:

If this is true, then your implementation must also override:

• ScheduleAddImageWithValidationJobImpl(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)
• GetAddReferenceImageJobStatus(AddReferenceImageJobState)

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 containing 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

Note to 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. May 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 may 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

ScheduleAddImageJob(NativeSlice<Byte>, Vector2Int, TextureFormat, XRReferenceImage, JobHandle)

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 (e.g., 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 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 may 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 representing 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

CreateRuntimeLibrary(XRReferenceImageLibrary)