public class PoolingChunkManager : ChunkManager
Provides a base implementation for a pooling based Chunk Manager.
The pooling system is very simple, so you may wish to create your own manager class
that implements a more
advanced system, though also note that using a pooling system with a streaming solution
may be counter productive in
some cases, as the point of using a streaming solution is generally to reduce memory
usage.
This is an overridable class, so you can inherit from it to provide custom
pooling behaviour. When doing so, all you should need to do is override the
ShouldAddChunkSetToPool method.
When queried, this method should return a value indicating if the
World Cell's chunk set should be added to the pool.
In some instances, you may want to remove chunk sets that have been added to the pool
yourself. The pool object can be accessed via the
user object, which can be accessed via the RegisteredUsers property and the userID
given to the user when it registered with the
Chunk Manager (make sure to cast the user object to PoolingChunkManagerUser). For
information on how to interact with the pool, take a look at
the ChunkSetPool class.
When removing chunk sets from a pool, you should make sure that the manager isn't
already in the middle of an action
that manipulates a pool, as it may cause problems. To do this, query the
PoolManipulationInProgress property
and if it returns true, yield for at least one frame. Keep performing this check until
it returns false. Once that happens, set the PoolManipulationInProgress
property to true so that the base methods for attaching and detaching chunks will
halt execution until you
finish your removal operation. Once you finish removing the chunks, set PoolManipulationInProgress
back to false.
This pooling class and any other ones based off it will not utilize the ChunkReuseJudge
in the pooling logic, therefore
the objects will only be pooled and reused with cells that utilize the same Streamable
Grid Cell. If you want your pool to
make use of the ChunkReuseJudge, you will need to make a custom pooling Chunk Manager
that does not
derive from this class.
This component is usable with
both Game Objects and non Game Object Chunks, however there are certain methods of
the Chunk Manager class
that are by default, configured to work with Game Objects. Those methods include:
GetChunkPosition - For retrieving the Vector3Double position of a chunk. Only called
if the LOD using this controller has 'Chunks Use
Positional Data' enabled (this setting can be found on your Streamable Grid asset).
SetChunkPosition - For setting the chunk position to a Vector3Double value. Only called
if the LOD using this controller has 'Chunks Use
Positional Data' enabled (this setting can be found on your Streamable Grid asset).
SetChunkActiveState - For setting the state of the chunk to active or deactive. This
method is called only if Auto Activate/Deactivate
Cell Chunks is enabled in your World inspector, for any LODs that use this controller.
If you anticipate any of these methods being called, you will need to create a custom
class deriving from this one, and in that class override
the methods that will be called, so that they function correctly with your custom
chunks.
Additional Note: This component contains its own special class (PoolingChunkManagerUser)
which enables multiple
users to use the pooling manager at the same time. The data associated with each user
is stored in this user object and retrieved
using the userID passed into each method.
This user object contains information pertaining to the user, such as the
ILODGroup object associated with the user, the chunkStreamerUserID of
the user (in reference to the Chunk Streamer it uses), and the pool of the user. You
can access the user object via the
RegisteredUsers property and userID,
like so: RegisteredUsers[userID], however you will need to cast it to a PoolingChunkManagerUser
or a custom user class that
derives from it in order to access the pool.
You may also create your own custom user object class which
derives from PoolingChunkManagerUser, in order to store custom data or add custom
methods.
In fact, this strategy is utilized by some of the other Chunk Managers in the kit.
Simply override the
CreateNewUser method and return your custom user object.
The properties, methods, and constructors of this PoolingChunkManagerUser class have
been included on this webpage along side
the other members of the PoolingChunkManager class. You can easily identify them as
their member names include
a PoolingChunkManagerUser prefix. You can use these as a reference when creating custom
PoolingChunkManagerUser classes.
| Name | Type | Description |
|---|---|---|
| PoolManipulationInProgress | bool |
Gets a value indicating whether an operation is Currently in progress that manipulates
the underlying
pool. Any action you perform that manipulates the pool (removes or adds objects from
it) should be performed
in a coroutine, so that you can yield the execution of your action until this property
returns false.
|
| PoolingChunkManagerUser.Pool | ChunkSetPool |
A ChunkSetPool object for this user. This pool is actually a container for a set of pools, with one pool per Streamable Grid Cell. |
public PoolingChunkManagerUser(ChunkManager chunkManager, ILODGroup LODGroup, int chunkStreamerUserID, int maxChunkSetsPerPool) : base(chunkManager, LODGroup, chunkStreamerUserID)
Creates an instance of this user object. If you are overriding the PoolingChunkManager
class and
not overriding the PoolingChunkManagerUser, you can create a new instance of this
user object via this
constructor, which can be returned in the ChunkManager's CreateNewUser method.
If you are overriding PoolingChunkManagerUser, your custom user class will need constructors
with at least these parameters
(but can also have more), and they must also call the base constructor, which is accomplished
by placing
: (chunkManager, LODGroup, chunkStreamerUserID, maxChunkSetsPerPool) after your constructor
declaration.
Note, this constructor can only be used from a class deriving from PoolingChunkManager
or PoolingChunkManagerUser.
| Name | Type | Description |
|---|---|---|
| chunkManager | ChunkManager |
The parent Chunk Manager instance creating the user object |
| LODGroup | ILODGroup |
The LOD Group the user object is being created for. |
| chunkStreamerUserID | int |
The User ID of the LOD Group that was assigned to it by the Chunk Streamer when it was registered with it. |
| maxChunkSetsPerPool | int |
The maximum number of Chunk Sets allowed in each pool, i.e., its capacity. |
protected sealed override IEnumerator<YieldInstruction> AttachChunksAlreadyInSceneToCells(List<WorldCell> cells, ChunkManagerUser user)
Searches for existing scene object in a pool, and if it finds all scene objects belonging to a cell, it attaches them and removes the cell from the list.
| Name | Type | Description |
|---|---|---|
| cells | List<WorldCell> |
The cells whose objects need to be attached. |
| user | ChunkManagerUser |
The user requesting the attachment. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
protected sealed override void AttachChunksAlreadyInSceneToCellsInSingleFrame(List<WorldCell> cells, ChunkManagerUser user)
Searches for existing scene object in a pool, and if it finds all scene objects belonging to a cell, it attaches them and removes the cell from the list.
| Name | Type | Description |
|---|---|---|
| cells | List<WorldCell> |
The cells whose objects need to be attached. |
| user | ChunkManagerUser |
The user requesting the attachment. |
protected sealed override ChunkManagerUser CreateNewUser(ILODGroup LODGroup, int chunkStreamerUserID)
Creates a new PoolingChunkManagerUser, which is a custom type which derives
from ChunkManagerUser. This user object contains an object pool used specifically
by this class.
If you create a class that derives from PoolingChunkManager, you may want to create
a custom
user type that holds more data, depending on your needs. In that case, your custom
user type should inherit from
PoolingChunkManagerUser and you should override this method to return an instance
of
your custom type.
| Name | Type | Description |
|---|---|---|
| LODGroup | ILODGroup |
The lod group being registered. |
| chunkStreamerUserID | int |
When the LODGroup registered with the manager, the manager automatically registered the LODGroup with the Chunk Streamer associated with it. This is the user ID assigned to the LODGroup by that Chunk Streamer. |
ChunkManagerUser
A new user object created using the worldAssociatedWithUser as input.
protected sealed override IEnumerator<YieldInstruction> DetachAndProcessChunksToKeepInScene(List<WorldCell> cells, ChunkManagerUser user)
Detaches and pools the objects associated with the input cells over a period of frames. If there is not enough room in the pool for all of a cell's objects, they are not removed (so will be unloaded by the Chunk Streamer). Cells with objects that are sucessfully pooled are removed from the list. passed in list.
| Name | Type | Description |
|---|---|---|
| deactivatedCells | List<WorldCell> |
The cells whose objects need to be detached and processed. |
| user | ChunkManagerUser |
The user requesting the detachment and processing. |
IEnumerator<YieldInstruction>
An IEnumerator<YieldInstruction> that can be iterated over or used as a coroutine.
See the
YieldInstruction page for more info.
public sealed override void OnUserDeRegistering(ChunkManagerUser user)
Overriden to remove pooled objects belonging to the user just before it is de registered.
| Name | Type | Description |
|---|---|---|
| user | ChunkManagerUser |
The user that is about to be de registered |
public virtual void ShouldAddChunkSetToPool(WorldCell cell, PoolingChunkManagerUser userCellBelongsTo)
Queried to determine if the input cell's Asset Chunk Set should be added to the pool. This method is only queried when there is room in the pool for the Asset Chunk Set (i.e., it is not at capacity), so if you return true from the method, you can be guaranteed that the chunks will be added. If not overriden, it will always return true.
| Name | Type | Description |
|---|---|---|
| cell | WorldCell |
The cell which needs to be processed. |
| userCellBelongsTo | PoolingChunkManagerUser |
The user the cell belongs to. |