track

package
v0.19.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 5, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package track provides resource state tracking infrastructure.

TrackerIndex provides dense indexing for efficient O(1) access to resource tracking state. Unlike resource IDs (which use epochs and may be sparse), tracker indices are always dense (0, 1, 2, ...) for efficient array access.

Architecture

Each Device owns a TrackerIndexAllocators which manages separate allocators for each resource type. When a resource is created, it gets a TrackerIndex from the appropriate allocator. When destroyed, the index is returned for reuse.

Thread Safety

SharedTrackerIndexAllocator provides thread-safe allocation/deallocation. The underlying TrackerIndexAllocator uses mutex-based synchronization.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BufferState 

type BufferState struct {
	// contains filtered or unexported fields
}

BufferState holds the tracked state for a single buffer.

func (BufferState) Usage 

func (s BufferState) Usage() BufferUses

Usage returns the current usage.

type BufferTracker 

type BufferTracker struct {
	// contains filtered or unexported fields
}

BufferTracker tracks buffer usage states for a device. Used to validate usage transitions and generate barriers.

func NewBufferTracker 

func NewBufferTracker() *BufferTracker

NewBufferTracker creates a new buffer tracker.

func (*BufferTracker) GetUsage 

func (t *BufferTracker) GetUsage(index TrackerIndex) BufferUses

GetUsage returns the current usage of a buffer.

func (*BufferTracker) InsertSingle 

func (t *BufferTracker) InsertSingle(index TrackerIndex, usage BufferUses)

InsertSingle tracks a new buffer with initial usage.

func (*BufferTracker) IsTracked 

func (t *BufferTracker) IsTracked(index TrackerIndex) bool

IsTracked returns true if the buffer is being tracked.

func (*BufferTracker) Merge 

func (t *BufferTracker) Merge(scope *BufferUsageScope) []PendingTransition

Merge merges usage from scope into tracker, returning needed transitions. This is called during queue submit to synchronize command buffer state with device state.

func (*BufferTracker) Remove 

func (t *BufferTracker) Remove(index TrackerIndex)

Remove stops tracking a buffer.

func (*BufferTracker) SetUsage 

func (t *BufferTracker) SetUsage(index TrackerIndex, usage BufferUses)

SetUsage updates the usage of a tracked buffer.

func (*BufferTracker) Size 

func (t *BufferTracker) Size() int

Size returns the number of tracked buffers.

type BufferUsageScope 

type BufferUsageScope struct {
	// contains filtered or unexported fields
}

BufferUsageScope tracks buffer usage within a command buffer or pass. Each command buffer has its own scope that gets merged into the device tracker on submit.

func NewBufferUsageScope 

func NewBufferUsageScope() *BufferUsageScope

NewBufferUsageScope creates a new usage scope.

func (*BufferUsageScope) Clear 

func (s *BufferUsageScope) Clear()

Clear resets the scope for reuse.

func (*BufferUsageScope) GetUsage 

func (s *BufferUsageScope) GetUsage(index TrackerIndex) BufferUses

GetUsage returns the current usage in this scope.

func (*BufferUsageScope) IsUsed 

func (s *BufferUsageScope) IsUsed(index TrackerIndex) bool

IsUsed returns true if the buffer is used in this scope.

func (*BufferUsageScope) SetUsage 

func (s *BufferUsageScope) SetUsage(index TrackerIndex, usage BufferUses) error

SetUsage sets the usage for a buffer in this scope. Returns error if the buffer already has an incompatible usage.

type BufferUses 

type BufferUses uint32

BufferUses represents internal buffer usage states for tracking. These are more granular than gputypes.BufferUsage for precise barrier insertion. 

const (
	BufferUsesNone         BufferUses = 0
	BufferUsesCopySrc      BufferUses = 1 << 0  // Being read by copy operation
	BufferUsesCopyDst      BufferUses = 1 << 1  // Being written by copy operation
	BufferUsesIndex        BufferUses = 1 << 2  // Bound as index buffer
	BufferUsesVertex       BufferUses = 1 << 3  // Bound as vertex buffer
	BufferUsesUniform      BufferUses = 1 << 4  // Bound in bind group for reading
	BufferUsesStorageRead  BufferUses = 1 << 5  // Storage buffer read-only
	BufferUsesStorageWrite BufferUses = 1 << 6  // Storage buffer read-write
	BufferUsesIndirect     BufferUses = 1 << 7  // Indirect command buffer
	BufferUsesMapRead      BufferUses = 1 << 8  // Mapped for CPU read
	BufferUsesMapWrite     BufferUses = 1 << 9  // Mapped for CPU write
	BufferUsesQueryResolve BufferUses = 1 << 10 // Query result destination
)

Buffer usage flags for state tracking.

func (BufferUses) Contains 

func (u BufferUses) Contains(other BufferUses) bool

Contains returns true if all flags in other are present in u.

func (BufferUses) IsCompatible 

func (u BufferUses) IsCompatible(other BufferUses) bool

IsCompatible returns true if two usages can coexist without a barrier. Read-only usages are compatible with each other. Write usages require exclusive access.

func (BufferUses) IsEmpty 

func (u BufferUses) IsEmpty() bool

IsEmpty returns true if no usage flags are set.

func (BufferUses) IsReadOnly 

func (u BufferUses) IsReadOnly() bool

IsReadOnly returns true if the usage contains only read-only operations.

func (BufferUses) ToBufferUsage 

func (u BufferUses) ToBufferUsage() gputypes.BufferUsage

ToBufferUsage converts internal uses to gputypes.BufferUsage for HAL.

type PendingTransition 

type PendingTransition struct {
	Index TrackerIndex
	Usage StateTransition
}

PendingTransition represents a state transition that needs a barrier.

func (PendingTransition) IntoHAL 

func (p PendingTransition) IntoHAL(buffer hal.Buffer) hal.BufferBarrier

IntoHAL converts a pending transition to a HAL buffer barrier.

type ResourceMetadata 

type ResourceMetadata struct {
	// contains filtered or unexported fields
}

ResourceMetadata tracks which resources are owned/present.

func NewResourceMetadata 

func NewResourceMetadata() ResourceMetadata

NewResourceMetadata creates new metadata.

func (*ResourceMetadata) Clear 

func (m *ResourceMetadata) Clear()

Clear resets the metadata.

func (*ResourceMetadata) Count 

func (m *ResourceMetadata) Count() int

Count returns the number of owned resources.

func (*ResourceMetadata) IsOwned 

func (m *ResourceMetadata) IsOwned(index TrackerIndex) bool

IsOwned returns true if the resource is owned.

func (*ResourceMetadata) SetOwned 

func (m *ResourceMetadata) SetOwned(index TrackerIndex, owned bool)

SetOwned marks a resource as owned/not owned.

type SharedTrackerIndexAllocator 

type SharedTrackerIndexAllocator struct {
	// contains filtered or unexported fields
}

SharedTrackerIndexAllocator is a thread-safe wrapper for sharing between device and resources. It's essentially a reference-counted pointer to a TrackerIndexAllocator.

func NewSharedTrackerIndexAllocator 

func NewSharedTrackerIndexAllocator() *SharedTrackerIndexAllocator

NewSharedTrackerIndexAllocator creates a new shared allocator.

func (*SharedTrackerIndexAllocator) Alloc 

func (s *SharedTrackerIndexAllocator) Alloc() TrackerIndex

Alloc allocates a new tracker index.

func (*SharedTrackerIndexAllocator) Free 

func (s *SharedTrackerIndexAllocator) Free(idx TrackerIndex)

Free releases a tracker index for reuse.

func (*SharedTrackerIndexAllocator) HighWaterMark 

func (s *SharedTrackerIndexAllocator) HighWaterMark() TrackerIndex

HighWaterMark returns the highest index ever allocated.

func (*SharedTrackerIndexAllocator) Size 

func (s *SharedTrackerIndexAllocator) Size() int

Size returns the number of currently allocated indices.

type StateTransition 

type StateTransition struct {
	From BufferUses
	To   BufferUses
}

StateTransition represents a from→to state change.

func (StateTransition) NeedsBarrier 

func (t StateTransition) NeedsBarrier() bool

NeedsBarrier returns true if this transition requires a barrier.

type TrackerIndex 

type TrackerIndex uint32

TrackerIndex is a dense index for efficient resource state tracking. Unlike resource IDs (which use epochs and may be sparse), tracker indices are always dense (0, 1, 2, ...) for efficient array access. 

const InvalidTrackerIndex TrackerIndex = ^TrackerIndex(0)

InvalidTrackerIndex represents an unassigned tracker index. Using max uint32 ensures it won't conflict with valid indices.

func (TrackerIndex) IsValid 

func (i TrackerIndex) IsValid() bool

IsValid returns true if this is a valid tracker index.

type TrackerIndexAllocator 

type TrackerIndexAllocator struct {
	// contains filtered or unexported fields
}

TrackerIndexAllocator allocates dense tracker indices. Indices are reused after being freed to maintain density.

func NewTrackerIndexAllocator 

func NewTrackerIndexAllocator() *TrackerIndexAllocator

NewTrackerIndexAllocator creates a new allocator.

func (*TrackerIndexAllocator) Alloc 

func (a *TrackerIndexAllocator) Alloc() TrackerIndex

Alloc allocates a new tracker index. Reuses released indices when available for optimal density.

func (*TrackerIndexAllocator) Free 

func (a *TrackerIndexAllocator) Free(idx TrackerIndex)

Free releases a tracker index for reuse. Safe to call with InvalidTrackerIndex (no-op).

func (*TrackerIndexAllocator) HighWaterMark 

func (a *TrackerIndexAllocator) HighWaterMark() TrackerIndex

HighWaterMark returns the highest index ever allocated. Useful for sizing tracking arrays.

func (*TrackerIndexAllocator) Reset 

func (a *TrackerIndexAllocator) Reset()

Reset clears the allocator, invalidating all previously allocated indices. Use with caution - all resources using old indices become invalid.

func (*TrackerIndexAllocator) Size 

func (a *TrackerIndexAllocator) Size() int

Size returns the number of currently allocated indices. This equals the total allocated minus the freed count.

type TrackerIndexAllocators 

type TrackerIndexAllocators struct {
	Buffers          *SharedTrackerIndexAllocator
	Textures         *SharedTrackerIndexAllocator
	TextureViews     *SharedTrackerIndexAllocator
	Samplers         *SharedTrackerIndexAllocator
	BindGroups       *SharedTrackerIndexAllocator
	BindGroupLayouts *SharedTrackerIndexAllocator
	RenderPipelines  *SharedTrackerIndexAllocator
	ComputePipelines *SharedTrackerIndexAllocator
}

TrackerIndexAllocators manages all tracker index allocators for a device. Each resource type has its own allocator to maintain separate namespaces.

func NewTrackerIndexAllocators 

func NewTrackerIndexAllocators() *TrackerIndexAllocators

NewTrackerIndexAllocators creates allocators for all resource types.

type TrackingData 

type TrackingData struct {
	// contains filtered or unexported fields
}

TrackingData holds per-resource tracking information. This struct is embedded in each tracked resource (Buffer, Texture, etc.) to provide efficient O(1) access to tracking state.

Lifecycle

  1. Created with NewTrackingData during resource creation
  2. Index() used during command encoding for state tracking
  3. Release() called during resource destruction to recycle the index

Thread Safety

TrackingData is safe for concurrent use. The index is immutable after creation, and Release() uses atomic operations to prevent double-free.

func NewTrackingData 

func NewTrackingData(allocator *SharedTrackerIndexAllocator) *TrackingData

NewTrackingData creates tracking data and allocates an index. The allocator must not be nil.

func (*TrackingData) Index 

func (t *TrackingData) Index() TrackerIndex

Index returns the tracker index. Returns InvalidTrackerIndex if the tracking data was created with a nil allocator or has been released.

func (*TrackingData) IsReleased 

func (t *TrackingData) IsReleased() bool

IsReleased returns true if Release() has been called.

func (*TrackingData) Release 

func (t *TrackingData) Release()

Release frees the tracker index for reuse. Called when the resource is destroyed. Safe to call multiple times (subsequent calls are no-ops).

type TrackingDataInit 

type TrackingDataInit interface {
	// InitTracking initializes the tracking data for this resource.
	InitTracking(allocator *SharedTrackerIndexAllocator)
}

TrackingDataInit is a convenience interface for resources that need tracking data initialization.

type UsageConflictError 

type UsageConflictError struct {
	Index    TrackerIndex
	Existing BufferUses
	New      BufferUses
}

UsageConflictError is returned when incompatible usages are detected.

func (*UsageConflictError) Error 

func (e *UsageConflictError) Error() string

Error implements the error interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.