Class MutableRuntimeReferenceImageLibrary

A reference image library that can be constructed and modified at runtime. By contrast, an XRReferenceImageLibrary can only be constructed at edit-time and is immutable at runtime.

Inheritance
Object
RuntimeReferenceImageLibrary
MutableRuntimeReferenceImageLibrary
Inherited Members
Namespace: UnityEngine.XR.ARSubsystems
Syntax
public abstract class MutableRuntimeReferenceImageLibrary : RuntimeReferenceImageLibrary, IReferenceImageLibrary
Remarks

Subsystem 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

Methods

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
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 texture's format is not supported. You can query for support using XRImageTrackingSubsystem.IsTextureFormatSupported.
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

See Also