Struct BlobBuilder

Creates blob assets.

Namespace: Unity.Entities
Syntax
public struct BlobBuilder : IDisposable
Remarks

A blob asset is an immutable data structure stored in unmanaged memory. Blob assets can contain primitive types, strings, structs, arrays, and arrays of arrays. Arrays and structs must only contain blittable types. Strings must be of type BlobString (or a specialized unmanaged string type such as Unity.Collections.NativeString64).

To use a BlobBuilder object to create a blob asset:

  1. Declare the structure of the blob asset as a struct.
  2. Create a BlobBuilder object.
  3. Call the ConstructRoot<T>() method, where T is the struct definng the asset structure.
  4. Initialize primitive values defined at the root level of the asset.
  5. Allocate memory for arrays, structs, and BlobString instances at the root.
  6. Initialize the values of those arrays, structs, and strings.
  7. Continue allocating memory and initializing values until you have fully constructed the asset.
  8. Call CreateBlobAssetReference<T>(Allocator) to create a reference to the blob asset in memory.
  9. Dispose the BlobBuilder object.

Use the BlobAssetReference<T> returned by CreateBlobAssetReference<T>(Allocator) to reference the blob asset. You can use a BlobAssetReference<T> as a field of an IComponentData struct. More than one entity can reference the same blob asset.

Call Dispose() to free the memory allocated for a blob asset.

Blob assets cannot be modified once created. Instead, you must create a new blob asset, update any references to the old one and then dispose of it.

Examples

Constructors

BlobBuilder(Allocator, Int32)

Constructs a BlobBuilder object.

Declaration
public BlobBuilder(Allocator allocator, int chunkSize = 65536)
Parameters
Type Name Description
Allocator allocator

The type of allocator to use for the BlobBuilder's internal, temporary data. Use Temp unless the BlobBuilder exists across more than four Unity frames.
Int32 chunkSize

(Optional) The minimum amount of memory to allocate while building an asset. The default value should suit most use cases. A smaller chunkSize results in more allocations; a larger chunkSize could increase the BlobBuilder's total memory allocation (which is freed when you dispose of the BlobBuilder.

Methods

Allocate<T>(ref BlobArray<T>, Int32)

Allocates enough memory to store length elements of struct T.

Declaration
public BlobBuilderArray<T> Allocate<T>(ref BlobArray<T> ptr, int length)
    where T : struct
Parameters
Type Name Description
BlobArray<T> ptr

A reference to a BlobArray field in a blob asset.
Int32 length

The number of elements to allocate.
Returns
Type Description
BlobBuilderArray<T>

A reference to the newly allocated array as a mutable BlobBuilderArray instance.
Type Parameters
Name Description
T

The struct data type.

Allocate<T>(ref BlobPtr<T>)

Allocates enough memory to store a struct of type T.

Declaration
public T Allocate<T>(ref BlobPtr<T> ptr)
    where T : struct
Parameters
Type Name Description
BlobPtr<T> ptr

A reference to a blob pointer field in a blob asset.
Returns
Type Description
T

A reference to the newly allocated struct.
Type Parameters
Name Description
T

The struct data type.

Construct<T>(ref BlobArray<T>, T[])

Copies an array of structs to an array in a blob asset after allocating the necessary memory.

Declaration
public BlobBuilderArray<T> Construct<T>(ref BlobArray<T> blobArray, params T[] data)
    where T : struct
Parameters
Type Name Description
BlobArray<T> blobArray

A reference to a BlobArray field in a blob asset.
T[] data

An array containing structs of type T.
Returns
Type Description
BlobBuilderArray<T>

A reference to the newly constructed array as a mutable BlobBuilderArray instance.
Type Parameters
Name Description
T

The struct data type.

ConstructRoot<T>()

Creates the top-level fields of a single blob asset.

Declaration
public T ConstructRoot<T>()
    where T : struct
Returns
Type Description
T

A reference to the blob data under construction.
Type Parameters
Name Description
T

A struct that defines the structure of the blob asset.
Remarks

This function allocates memory for the top-level fields of a blob asset and returns a reference to it. Use this root reference to initialize field values and to allocate memory for arrays and structs.

CreateBlobAssetReference<T>(Allocator)

Completes construction of the blob asset and returns a reference to the asset in unmanaged memory.

Declaration
public BlobAssetReference<T> CreateBlobAssetReference<T>(Allocator allocator)
    where T : struct
Parameters
Type Name Description
Allocator allocator

The type of memory to allocate. Unless the asset has a very short life span, use Persistent.
Returns
Type Description
BlobAssetReference<T>
Type Parameters
Name Description
T

The data type of the struct used to construct the asset's root. Use the same struct type that you used when calling ConstructRoot<T>().
Remarks

Use the BlobAssetReference<T> to access the blob asset. When the asset is no longer needed, callDispose() to destroy the blob asset and free its allocated memory.

Dispose()

Disposes of this BlobBuilder instance and frees its temporary memory allocations.

Declaration
public void Dispose()
Remarks

Call Dispose() after calling CreateBlobAssetReference<T>(Allocator).

SetPointer<T>(ref BlobPtr<T>, ref T)

Sets a BlobPtr to point to the given object inside the blob.

Declaration
public T SetPointer<T>(ref BlobPtr<T> ptr, ref T obj)
    where T : struct
Parameters
Type Name Description
BlobPtr<T> ptr

A reference to a blob pointer field in a blob asset.
T obj

The struct that exists in the blob that you want to point to.
Returns
Type Description
T

A reference to obj.
Type Parameters
Name Description
T

Extension Methods