 |
UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
|
|
UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
|
#include <EditorBulkData.h>
Classes | |
| struct | FSharedBufferWithID |
Protected Types | |
| enum class | ETornOff |
Protected Member Functions | |
| COREUOBJECT_API | FEditorBulkData (const FEditorBulkData &Other, ETornOff) |
Friends | |
| struct | FTocEntry |
The goal of this class is to provide an editor time version of BulkData that will work with the asset virtualization system.
Assuming that the DDC is hot, the virtualized payloads are accessed relatively infrequently, usually when the package is being edited in the editor in some manner. So the payload access is designed around this. If the data is frequently accessed when running the editor then the user would not gain from having it virtualized as they would end up pulling it immediately anyway.
The biggest difference with normal bulkdata is that the access times might be significantly longer if the payload is not readily available which is why the only way to access the payload is by a TFuture or a callback so that the caller is forced to consider how to handle the potential stall and hopefully organize their code in such a way that the time lag is not noticeable to the user.
The second biggest difference is that the caller will own the payload memory once it is returned to them, unlike the old bulkdata class which would retain ownership. Which forces the calling code to be in control of when the memory is actually allocated and for how long. With the old bulkdata class a single access would leave that memory allocated in a non-obvious way and would lead to memory bloats within the editor.
The method ::GetGuid can be used to access a unique identifier for the payload, currently it is based on the payload itself, so that two objects with the same payload would both have the same Guid. The intent is that we would be able to share local copies of the payload between branches to reduce the cost of having multiple branches with similar data on the same machine.
Updating the bulkdata: Unlike the older bulkdata system, EditorBulkData does not support any lock/unlock mechanism, instead the internal data is updated via a single call to UpdatePayload and the data is retrieved via a single call to GetPayload.
For examples see the "System.CoreUObject.Serialization.EditorBulkData.UpdatePayload" test found in Engine\Source\Runtime\CoreUObject\Private\Tests\Serialization\EditorBulkDataTests.cpp.
Thread Safety:
The class should be thread safe in that you can call the public methods on multiple threads at once and expect things to work. However if you were to call GetPayloadSize() before calling GetPayload() on one thread it would be possible for a call to UpdatePayload() to occur on another thread in between those two calls, meaning that the size you got might not be the correct size as the payload returned. If you need that level of thread safety it would be up to you to manage it at a higher level. It would however be safe to pass a copy of your FEditorBulkData to a background task rather than a reference. The copy would either be able to load the payload from disk, pull it from virtualized storage or if the source bulkdata is holding the payload in memory it will just take a reference to that payload rather than making a copy. In this way you can be sure of the state of the FEditorBulkData on the background task as future edits to the original bulkdata will not affect it. The base class with no type
|
strongprotected |
|
default |
| UE::Serialization::FEditorBulkData::~FEditorBulkData | ( | ) |
| UE::Serialization::FEditorBulkData::FEditorBulkData | ( | FEditorBulkData && | Other | ) |
| UE::Serialization::FEditorBulkData::FEditorBulkData | ( | const FEditorBulkData & | Other | ) |
|
protected |
| bool UE::Serialization::FEditorBulkData::CanSaveForRegistry | ( | ) | const |
Return true if the bulkdata has a source location that persists between editor processes (package file or virtualization).
|
inline |
Make a torn-off copy of this bulk data.
| void UE::Serialization::FEditorBulkData::CreateFromBulkData | ( | FBulkData & | BulkData, |
| const FGuid & | Guid, | ||
| UObject * | Owner | ||
| ) |
Convenience method to make it easier to convert from FBulkData to FEditorBulkData and sets the Guid
| BulkData | The bulkdata object to create from. |
| Guid | A guid associated with the bulkdata object which will be used to identify the payload. This MUST remain the same between sessions so that the payloads key remains consistent! |
Fix legacy content that created the Id from non-unique Guids. Run on objects created before FUE5MainStreamObjectVersion::VirtualizedBulkDataHaveUniqueGuids
| void UE::Serialization::FEditorBulkData::DetachFromDisk | ( | FArchive * | Ar, |
| bool | bEnsurePayloadIsLoaded | ||
| ) |
Removes the ability for the bulkdata object to load it's payload from disk (if it was doing so)
| Ar | The archive that the bulkdata is being detached from. This should match AttachedAr. |
| bEnsurePayloadIsLoaded | If true and the bulkdata currently is storing it's payload as a package on disk then the payload should be loaded into memory so that it can be accessed in the future. If false then the payload is not important and does not need to be loaded. |
| bool UE::Serialization::FEditorBulkData::DoesPayloadNeedLoading | ( | ) | const |
Returns if the payload would require loading in order to be accessed. Returns false if the payload is already in memory or of zero length
| void UE::Serialization::FEditorBulkData::GetBulkDataVersions | ( | FArchive & | InlineArchive, |
| FPackageFileVersion & | OutUEVersion, | ||
| int32 & | OutLicenseeUEVersion, | ||
| FCustomVersionContainer & | OutCustomVersions | ||
| ) | const |
Get the versions used in the file containing the payload.
| InlineArchive | The archive that was used to load this object |
| TFuture< FCompressedBuffer > UE::Serialization::FEditorBulkData::GetCompressedPayload | ( | ) | const |
Returns an immutable FCompressedBuffer reference to the payload data.
Note that depending on the internal storage formats, the payload might not actually be compressed, but that will be handled by the FCompressedBuffer interface. Call FCompressedBuffer::Decompress() to get access to the payload in FSharedBuffer format.
| FCustomVersionContainer UE::Serialization::FEditorBulkData::GetCustomVersions | ( | FArchive & | InlineArchive | ) |
| FGuid UE::Serialization::FEditorBulkData::GetIdentifier | ( | ) | const |
Returns a unique identifier for the object itself.
| TFuture< FSharedBuffer > UE::Serialization::FEditorBulkData::GetPayload | ( | ) | const |
Returns an immutable FCompressedBuffer reference to the payload data.
| const FIoHash & UE::Serialization::FEditorBulkData::GetPayloadId | ( | ) | const |
Returns an unique identifier for the content of the payload.
|
inline |
Returns the size of the payload in bytes.
|
inline |
Returns true if the bulkdata object contains a valid payload greater than zero bytes in size.
|
inline |
Return whether the BulkData has legacy payload id that needs to be updated from loaded payload before it can be used in DDC.
| bool UE::Serialization::FEditorBulkData::IsMemoryOnlyPayload | ( | ) | const |
Return whether the BulkData is an in-memory payload without a persistent source location.
| bool UE::Serialization::FEditorBulkData::LocationMatches | ( | const FEditorBulkData & | Other | ) | const |
Return whether *this has the same source for the bulkdata (e.g. identical file locations if from file) as Other
| FEditorBulkData & UE::Serialization::FEditorBulkData::operator= | ( | const FEditorBulkData & | Other | ) |
| FEditorBulkData & UE::Serialization::FEditorBulkData::operator= | ( | FEditorBulkData && | Other | ) |
| void UE::Serialization::FEditorBulkData::Reset | ( | ) |
Reset to a truly empty state
| void UE::Serialization::FEditorBulkData::Serialize | ( | FArchive & | Ar, |
| UObject * | Owner, | ||
| bool | bAllowRegister = true |
||
| ) |
Used to serialize the bulkdata to/from a FArchive
| Ar | The archive to serialize the bulkdata. |
| Owner | The UObject that contains the bulkdata object, if this is a nullptr then the bulkdata will assume that it must serialize the payload immediately to memory as it will not be able to identify it's package path. |
| bAllowRegistry | Legacy parameter to skip registration when loading BulkData we know we will need to modify the identifier of. Should always be true for non-legacy serialization. |
Beyond this point UpdatedFlags will be modified to avoid serializing some flags
So any code actually using UpdatedFlags should come before this section of code
Used to serialize the bulkdata to/from a limited cache system used by the BulkDataRegistry.
| void UE::Serialization::FEditorBulkData::SetCompressionOptions | ( | ECompressedBufferCompressor | Compressor, |
| ECompressedBufferCompressionLevel | CompressionLevel | ||
| ) |
Sets the compression options to be applied to the payload during serialization.
These settings will continue to be used until the bulkdata object is reset, a subsequent call to SetCompressionOptions is made or the owning package is serialized to disk.
| Compressor | The Oodle compressor to use. |
| CompressionLevel | The Oodle compression level to use. |
| void UE::Serialization::FEditorBulkData::SetCompressionOptions | ( | ECompressionOptions | Option | ) |
Sets the compression options to be applied to the payload during serialization.
These settings will continue to be used until the bulkdata object is reset, a subsequent call to SetCompressionOptions is made or the owning package is serialized to disk.
| Option | The high level option to use. |
| COREUOBJECT_API void UE::Serialization::FEditorBulkData::SetVirtualizationOptOut | ( | bool | bOptOut | ) |
| void UE::Serialization::FEditorBulkData::TearOff | ( | ) |
| void UE::Serialization::FEditorBulkData::UnloadData | ( | ) |
Unloads the data (if possible) but leaves it in a state where the data can be reloaded
| void UE::Serialization::FEditorBulkData::UpdatePayload | ( | FCompressedBuffer | InPayload, |
| UObject * | Owner = nullptr |
||
| ) |
Replaces the existing payload (if any) with a new one. Note that FCompressedBuffers already know the FIoHash of the raw payload and so we do not recalculate it, making this method much faster for larger payloads than the other overloads.
| InPayload | The payload that this bulkdata object should reference. |
| Owner | The object that owns the bulkdata, or null to not associate with a UObject. |
| void UE::Serialization::FEditorBulkData::UpdatePayload | ( | FSharedBuffer | InPayload, |
| UObject * | Owner = nullptr |
||
| ) |
Replaces the existing payload (if any) with a new one. It is important to consider the ownership model of the payload being passed in to the method.
To pass in a raw pointer use 'FSharedBuffer::...(Data, Size)' to create a valid FSharedBuffer. Use 'FSharedBuffer::MakeView' if you want to retain ownership on the data being passed in, and use 'FSharedBuffer::TakeOwnership' if you are okay with the bulkdata object taking over ownership of it. The bulkdata object must own its internal buffer, so if you pass in a non-owned FSharedBuffer (ie by using 'FSharedBuffer::MakeView') then a clone of the data will be created internally and assigned to the bulkdata object.
| InPayload | The payload that this bulkdata object should reference. |
| Owner | The object that owns the bulkdata, or null to not associate with a UObject. |
| void UE::Serialization::FEditorBulkData::UpdatePayload | ( | FSharedBufferWithID | InPayload, |
| UObject * | Owner = nullptr |
||
| ) |
Allows the existing payload to be replaced with a new one.
To pass in a raw pointer use 'FSharedBuffer::...(Data, Size)' to create a valid FSharedBuffer. Use 'FSharedBuffer::MakeView' if you want to retain ownership on the data being passed in, and use 'FSharedBuffer::TakeOwnership' if you are okay with the bulkdata object taking over ownership of it. The bulkdata object must own its internal buffer, so if you pass in a non-owned FSharedBuffer (ie by using 'FSharedBuffer::MakeView') then a clone of the data will be created internally and assigned to the bulkdata object.
Use this override if you want compute PayloadId before updating the bulkdata
| InPayload | The payload to update the bulkdata with |
| Owner | The object that owns the bulkdata, or null to not associate with a UObject. |
| void UE::Serialization::FEditorBulkData::UpdatePayloadId | ( | ) |
Load the payload and set the correct payload id, if the bulkdata has a PlaceholderPayloadId.
Update the Owner of this BulkData in the BulkDataRegistry to include the Owner information. Has no effect if the BulkData is not valid for registration. The Owner information is lost and this function must be called again if the BulkData's payload information is modified.
1.9.8