#include <BKE_blendfile.hh>

Inherits blender::NonCopyable, and blender::NonMovable.

Classes
struct	IDAddOptions

Public Types
enum	IDAddOperations { NOP = 0 , MAKE_LOCAL = 1 << 0 , SET_FAKE_USER = 1 << 1 , SET_CLIPBOARD_MARK = 1 << 4 , CLEAR_DEPENDENCIES = 1 << 8 , ADD_DEPENDENCIES = 1 << 9 , DUPLICATE_DEPENDENCIES = 1 << 10 , MASK_INHERITED = (MAKE_LOCAL \| CLEAR_DEPENDENCIES \| ADD_DEPENDENCIES \| DUPLICATE_DEPENDENCIES) , MASK_PER_ID_USAGE }

Public Member Functions
	PartialWriteContext ()=delete

	PartialWriteContext (StringRefNull reference_root_filepath)

	~PartialWriteContext ()

ID *	id_add (const ID id, IDAddOptions options, blender::FunctionRef< IDAddOperations(LibraryIDLinkCallbackData cb_data, IDAddOptions options)> dependencies_filter_cb=nullptr)

ID *	id_create (short id_type, StringRefNull id_name, Library *library, IDAddOptions options)

void	id_delete (const ID *id)

void	remove_unused (bool clear_extra_user=false)

void	clear ()

bool	is_valid ()

bool	write (const char *write_filepath, int write_flags, int remap_mode, ReportList &reports)

bool	write (const char *write_filepath, ReportList &reports)

Public Attributes
Main	bmain = {}

Detailed Description

Partial blendfile writing.

This wrapper around the Main struct is designed to have a very short life span, during which it will contain independent copies of the IDs that are added to it.

In general, the G_MAIN data should not change while such a context exists, otherwise mapping info between the context content and the G_MAIN content cannot be kept up-to-date.

The context can then be written to disk, and destroyed.

It also has advanced ways to handle ID dependencies (and libraries for linked IDs), by allowing specific handling for each dependency individually. By using the dependencies_filter_cb optional parameter of id_add, it is possible to skip (ignore) certain dependencies, or make linked ones local in the context, etc.

Design task: #122061

Definition at line 179 of file BKE_blendfile.hh.

Member Enumeration Documentation

◆ IDAddOperations

enum blender::bke::blendfile::PartialWriteContext::IDAddOperations

Control how to handle IDs and their dependencies when they are added to this context.

Note: For linked IDs, if MAKE_LOCAL is not used, the library ID pointer is not considered nor handled as a regular dependency. Instead, the library is always added to the context data, and never duplicated. Also, library matching always happens based on absolute filepath.

Warning: Heterogeneous usages of these operations flags during a same PartialWriteContext session may not generate expected results. Typically, once an ID has been added to the context as 'matching' counterpart of the source Main (i.e. sharing the same session UID), it will not be re-processed further if found again as dependency of another ID, or added explicitly as root ID. So e.g. if an ID is added (explicitly or implicitly) but none of its dependencies are (using CLEAR_DEPENDENCIES), re-adding the same ID (explicitly or implicitly) with e.g. ADD_DEPENDENCIES set will not add its dependencies. This is not expected to be an issue in current use-cases.

Enumerator
NOP
MAKE_LOCAL	Do not keep linked info (library and/or liboverride references). Warning By default, when ADD_DEPENDENCIES is defined, this will also apply to all dependencies as well. Note Often required when only a small subset of the ID dependencies are also added to the context (i.e. many of the added data's ID pointers are set to `nullptr`). Otherwise, some areas not expecting nullptr (like LibOverride data) may assert or error on load of the partial written blendfile.
SET_FAKE_USER	Set the 'fake user' flag to the added ID. Ensures that it is never auto-removed from the context, and always written to disk.
SET_CLIPBOARD_MARK	Set the 'clipboard' flag to the added ID. Ensures that it is treated as potential source data for a 'paste ID' operation.
CLEAR_DEPENDENCIES	Clear all dependency IDs that are not in the partial write context. Mutually exclusive with ADD_DEPENDENCIES. WARNING: This also means that dependencies like obdata, shape-keys or actions are not duplicated either. NOTE: Either CLEAR_DEPENDENCIES or ADD_DEPENDENCIES must be specified in the final operation flags for all ID dependencies. This can be achieved by
ADD_DEPENDENCIES	Also add (or reuse if already there) dependency IDs into the partial write context. Mutually exclusive with CLEAR_DEPENDENCIES.
DUPLICATE_DEPENDENCIES	For each explicitly added IDs (i.e. these with a fake user), ensure all of their dependencies are independent copies, instead of being shared with other explicitly added IDs. Only relevant with ADD_DEPENDENCIES. Warning Implies that the `session_uid` of these duplicated dependencies will be different than their source data.
MASK_INHERITED	Operation flags that are (by default) inherited by all dependencies. Note This will be (partially) superseded by masked-out values from #MASK_PER_ID_USAGES below.
MASK_PER_ID_USAGE	Operation flags that are defined by the #dependencies_filter_cb callback, if given. Note This mask is applied on top of the filter from MASK_INHERITED, for ID dependencies of explicitly added data.

Definition at line 232 of file BKE_blendfile.hh.

Constructor & Destructor Documentation

◆ PartialWriteContext() [1/2]

blender::bke::blendfile::PartialWriteContext::PartialWriteContext ( )

delete

◆ PartialWriteContext() [2/2]

blender::bke::blendfile::PartialWriteContext::PartialWriteContext ( StringRefNull reference_root_filepath )

Definition at line 1717 of file blendfile.cc.

References BKE_main_idmap_create(), BKE_main_init(), bmain, Main::filepath, Main::id_map, MAIN_IDMAP_TYPE_NAME, MAIN_IDMAP_TYPE_UID, and STRNCPY.

◆ ~PartialWriteContext()

blender::bke::blendfile::PartialWriteContext::~PartialWriteContext ( )

Definition at line 1731 of file blendfile.cc.

References BKE_main_destroy(), BKE_main_idmap_destroy(), BLI_assert, bmain, and Main::next.

Member Function Documentation

◆ clear()

void blender::bke::blendfile::PartialWriteContext::clear ( )

Fully empty the partial write context.

Definition at line 2085 of file blendfile.cc.

References BKE_main_clear(), BKE_main_idmap_clear(), and bmain.

◆ id_add()

ID * blender::bke::blendfile::PartialWriteContext::id_add	(	const ID *	id,
		PartialWriteContext::IDAddOptions	options,
		blender::FunctionRef< IDAddOperations(LibraryIDLinkCallbackData *cb_data, IDAddOptions options)>	dependencies_filter_cb = nullptr )

Add a copy of the given ID to the partial write context.

Note: The duplicated ID will have the same session_uid as its source. In case a matching ID already exists in the context, it is returned instead of duplicating it again.

Parameters

options	Control how the added ID (and its dependencies) are handled. See #IDAddOptions and IDAddOperations above for details. If no #dependencies_filter_cb callback is specified, #options.operations must contain either CLEAR_DEPENDENCIES or ADD_DEPENDENCIES.
dependencies_filter_cb	Optional, a callback called for each ID usages, which returns specific operations flags for each ID usage. Currently, only accepted return values are the ones included in MASK_PER_ID_USAGE. Returned flags must always contain either CLEAR_DEPENDENCIES or ADD_DEPENDENCIES.

Returns: The pointer to the duplicated ID in the partial write context.

Definition at line 1865 of file blendfile.cc.

References blender::Map< Key, Value, InlineBufferCapacity, ProbingStrategy, Hash, IsEqual, Slot, Allocator >::add(), ADD_DEPENDENCIES, blender::Vector< T, InlineBufferCapacity, Allocator >::append(), BKE_id_owner_get(), BKE_library_foreach_ID_link(), BKE_main_idmap_lookup_uid(), BLI_assert, bmain, LibraryIDLinkCallbackData::cb_flag, CLEAR_DEPENDENCIES, CLOG_ERROR, CLOG_WARN, DUPLICATE_DEPENDENCIES, ID_FLAG_EMBEDDED_DATA, LibraryIDLinkCallbackData::id_pointer, IDWALK_CB_EMBEDDED, IDWALK_CB_EMBEDDED_NOT_OWNING, IDWALK_CB_INTERNAL, IDWALK_CB_LOOPBACK, IDWALK_CB_NEVER_NULL, IDWALK_DO_INTERNAL_RUNTIME_POINTERS, IDWALK_RET_NOP, LIB_ID_MAKELOCAL_FORCE_LOCAL, LIB_ID_MAKELOCAL_INDIRECT, LIB_ID_MAKELOCAL_LIBOVERRIDE_CLEAR, LOG_PARTIALWRITE, blender::Map< Key, Value, InlineBufferCapacity, ProbingStrategy, Hash, IsEqual, Slot, Allocator >::lookup(), MAKE_LOCAL, MASK_INHERITED, MASK_PER_ID_USAGE, ID::name, options, LibraryIDLinkCallbackData::owner_id, ID::session_uid, and UNUSED_VARS_NDEBUG.

Referenced by copy_material_exec(), blender::ed::outliner::outliner_id_copy_tag(), pose_copy_exec(), and view3d_copybuffer_exec().

◆ id_create()

ID * blender::bke::blendfile::PartialWriteContext::id_create	(	short	id_type,
		const blender::StringRefNull	id_name,
		Library *	library,
		PartialWriteContext::IDAddOptions	options )

Add and return a new ID into the partial write context.

NOTE: Since this ID is created in the partial write buffer, by definition it has no matching counterpart in the current G_MAIN. Therefore, there is no need to add it to matching_uid_map_, and its session_uid is not guaranteed to be constant (as it may be preempted later by another ID added from the current G_MAIN).

Parameters

options Control how the created ID is handled. See #IDAddOptions and IDAddOperations above for details, note that the only relevant operation flags currently are the SET_FAKE_USER and SET_CLIPBOARD_MARK ones.

Definition at line 2028 of file blendfile.cc.

References BKE_id_new_in_lib(), BKE_main_idmap_insert_id(), bmain, Library_Runtime::filepath_abs, Main::id_map, id_name(), ID_TAG_TEMP_MAIN, id_us_min(), options, Library::runtime, and ID::tag.

◆ id_delete()

void blender::bke::blendfile::PartialWriteContext::id_delete ( const ID * id )

Delete the copy of the given ID from the partial write context.

Note: The search is based on the ID.session_uid of the given ID. This means that if duplicate_depencies option was used when adding the ID, these independent dependencies duplicates cannot be removed directly from the context. Use remove_unused for this.; No dependencies will be removed. Use remove_unused to remove all unused IDs from the current context.

Definition at line 2047 of file blendfile.cc.

References BKE_id_delete(), BKE_main_idmap_lookup_uid(), BKE_main_idmap_remove_id(), and bmain.

◆ is_valid()

bool blender::bke::blendfile::PartialWriteContext::is_valid ( )

Debug: Check if the current partial write context is fully valid.

Currently, check if any ID in the context still has relations to IDs not in the context.

Returns: false if the context is invalid.

Definition at line 2091 of file blendfile.cc.

References blender::Set< Key, InlineBufferCapacity, ProbingStrategy, Hash, IsEqual, Slot, Allocator >::add(), BKE_library_foreach_ID_link(), bmain, CLOG_ERROR, blender::Set< Key, InlineBufferCapacity, ProbingStrategy, Hash, IsEqual, Slot, Allocator >::contains(), FOREACH_MAIN_ID_BEGIN, FOREACH_MAIN_ID_END, IDWALK_CB_EMBEDDED, IDWALK_CB_EMBEDDED_NOT_OWNING, IDWALK_READONLY, IDWALK_RET_NOP, is_valid(), LOG_PARTIALWRITE, ID::name, and ID::session_uid.

Referenced by is_valid(), and write().

◆ remove_unused()

void blender::bke::blendfile::PartialWriteContext::remove_unused ( bool clear_extra_user = false )

Remove all unused IDs from the current context.

Parameters

clear_extra_user If true, the runtime tag ensuring that IDs are written on disk will be cleared. In other words, only IDs flagged with 'fake user' and their dependencies will be kept. Allows to also remove IDs that were added to this context during the same editing session, and were not flagged as 'fake user'.

Definition at line 2055 of file blendfile.cc.

References BKE_id_multi_tagged_delete(), BKE_lib_query_unused_ids_tag(), BKE_main_idmap_remove_id(), bmain, CLOG_INFO, LibQueryUnusedIDsData::do_local_ids, FOREACH_MAIN_ID_BEGIN, FOREACH_MAIN_ID_END, ID_TAG_DOIT, id_us_clear_real(), INDEX_ID_NULL, LOG_PARTIALWRITE, parameters, and ID::tag.

◆ write() [1/2]

bool blender::bke::blendfile::PartialWriteContext::write	(	const char *	write_filepath,
		int	write_flags,
		int	remap_mode,
		ReportList &	reports )

Write the content of the current context as a blendfile on disk.

Returns: true on success.

Definition at line 2153 of file blendfile.cc.

References BKE_id_delete(), BKE_library_make_local(), BLI_assert, BLI_assert_msg, BLO_write_file(), bmain, is_valid(), Main::libraries, LISTBASE_FOREACH, BlendFileWriteParams::remap_mode, and STREQ.

Referenced by write().

◆ write() [2/2]

bool blender::bke::blendfile::PartialWriteContext::write	(	const char *	write_filepath,
		ReportList &	reports )

Definition at line 2183 of file blendfile.cc.

References BLO_WRITE_PATH_REMAP_RELATIVE, and write().

Member Data Documentation

◆ bmain

Main blender::bke::blendfile::PartialWriteContext::bmain = {}

The temp Main itself, storing all IDs copied into this partial write context.

Definition at line 182 of file BKE_blendfile.hh.

Referenced by clear(), id_add(), id_create(), id_delete(), is_valid(), PartialWriteContext(), remove_unused(), write(), and ~PartialWriteContext().

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ IDAddOperations

Constructor & Destructor Documentation

◆ PartialWriteContext() [1/2]

◆ PartialWriteContext() [2/2]

◆ ~PartialWriteContext()

Member Function Documentation

◆ clear()

◆ id_add()

◆ id_create()

◆ id_delete()

◆ is_valid()

◆ remove_unused()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ bmain