graphics.go RawHistoryFolder
1// Package graphics provides a renderer-neutral, bounded graphics scene.
2//
3// The package stores immutable encoded asset blobs and sparse placements. A
4// scene is mutated by its owner and publishes immutable snapshots for
5// consumers. It deliberately knows nothing about terminal protocols,
6// renderers, image formats, or text state.
7package graphics
8
9import "errors"
10
11var (
12 ErrInvalidRect = errors.New("invalid rectangle")
13 ErrInvalidAsset = errors.New("invalid asset")
14 ErrInvalidPlacement = errors.New("invalid placement")
15 ErrAssetNotFound = errors.New("asset not found")
16 ErrPlacementNotFound = errors.New("placement not found")
17 ErrAssetInUse = errors.New("asset is still in use")
18 ErrTooManyAssets = errors.New("asset quota exceeded")
19 ErrTooManyPlacements = errors.New("placement quota exceeded")
20 ErrEncodedBudget = errors.New("encoded byte budget exceeded")
21 ErrDecodedPixelBudget = errors.New("decoded pixel budget exceeded")
22 ErrGenerationOverflow = errors.New("generation overflow")
23 ErrIdentifierOverflow = errors.New("identifier overflow")
24 ErrInvalidOperation = errors.New("invalid graphics operation")
25 ErrInvalidSceneLimits = errors.New("invalid scene limits")
26)
27
28// AssetID identifies an asset in a scene. Its representation is deliberately
29// private: IDs are only meaningful to the scene that issued them and are not
30// interchangeable with placement IDs.
31type AssetID struct{ value uint64 }
32
33// PlacementID identifies a sparse placement in a scene.
34type PlacementID struct{ value uint64 }
35
36// Valid reports whether the ID was issued by a scene.
37func (id AssetID) Valid() bool { return id.value != 0 }
38
39// Valid reports whether the ID was issued by a scene.
40func (id PlacementID) Valid() bool { return id.value != 0 }
41
42// String returns a stable diagnostic form of the opaque ID.
43func (id AssetID) String() string { return formatID('a', id.value) }
44
45// String returns a stable diagnostic form of the opaque ID.
46func (id PlacementID) String() string { return formatID('p', id.value) }
47
48func formatID(prefix byte, value uint64) string {
49 if value == 0 {
50 return "<invalid>"
51 }
52 var buf [1 + 20]byte
53 buf[0] = prefix
54 i := len(buf)
55 for value != 0 {
56 i--
57 buf[i] = byte('0' + value%10)
58 value /= 10
59 }
60 return string(buf[0:1]) + string(buf[i:])
61}
62
63// Limits bounds live scene resources. Zero-valued limits use the package
64// defaults; this keeps a zero-value configuration bounded as well.
65type Limits struct {
66 MaxAssets uint64
67 MaxPlacements uint64
68 MaxEncodedBytes uint64
69 MaxDecodedPixels uint64
70 MaxEncodedBytesPerAsset uint64
71 MaxDecodedPixelsPerAsset uint64
72}
73
74// Config is an alternate name for Limits for callers that prefer constructor
75// configuration terminology.
76type Config = Limits
77
78// SceneConfig is a descriptive alias for Config.
79type SceneConfig = Limits
80
81// Generation is the monotonically increasing scene generation number.
82type Generation = uint64
83
84// SnapshotRef is an explicit name for an immutable snapshot reference.
85type SnapshotRef = Snapshot
86
87// AssetInput is an alternate name for an asset registration description.
88type AssetInput = AssetBlob
89
90const (
91 DefaultMaxAssets = uint64(1024)
92 DefaultMaxPlacements = uint64(65536)
93 DefaultMaxEncodedBytes = uint64(64 << 20)
94 DefaultMaxDecodedPixels = uint64(256 << 20)
95 DefaultMaxEncodedBytesPerAsset = uint64(16 << 20)
96 DefaultMaxDecodedPixelsPerAsset = uint64(128 << 20)
97)
98
99// AssetFormat identifies the encoded pixel layout supplied by an asset.
100type AssetFormat uint8
101
102const (
103 AssetFormatUnknown AssetFormat = iota
104 AssetFormatRGB
105 AssetFormatRGBA
106 AssetFormatPNG
107)
108
109// AssetBlob is the caller-owned description of one encoded asset. AddAsset
110// copies Encoded before returning, so later caller mutations cannot alter a
111// scene or any snapshot. Format preserves the encoded pixel layout for the
112// renderer. Width and Height describe the decoded pixel extent used for
113// clipping and quota accounting. DecodedPixels, when non-zero, must equal
114// Width*Height; accounting always uses the checked product.
115type AssetBlob struct {
116 Encoded []byte
117 Format AssetFormat
118 Width, Height int64
119 DecodedPixels uint64
120}
121
122// AssetSpec is the conventional name for an asset input description.
123type AssetSpec = AssetBlob
124
125// PlacementSpec describes one sparse placement. Source defaults to the full
126// asset. Destination is a pixel rectangle. Cells optionally records the
127// cell-space extent associated with the same placement. HasCells and HasLayer
128// preserve explicit zero values when updating an existing placement.
129type PlacementSpec struct {
130 Asset AssetID
131 Source PixelRect
132 Destination PixelRect
133 Cells CellRect
134 HasCells bool
135 Layer int64
136 HasLayer bool
137}
138
139// Viewport can constrain visible fragments in pixel space, cell space, or
140// both. A zero-valued rectangle means that coordinate space is not supplied.
141type Viewport struct {
142 Pixels PixelRect
143 Cells CellRect
144}
145
146// VisibleFragment is the visible part of a placement. Source and Destination
147// are clipped together, preserving the placement's source-to-destination
148// mapping even when the destination is scaled. Cells is populated when the
149// placement and viewport carry cell geometry.
150type VisibleFragment struct {
151 PlacementID PlacementID
152 AssetID AssetID
153 Source PixelRect
154 Destination PixelRect
155 Cells CellRect
156}
157
158// Fragment is a short alias for VisibleFragment.
159type Fragment = VisibleFragment
160
161// Usage reports resources held by the current scene or an immutable snapshot.
162type Usage struct {
163 Assets uint64
164 Placements uint64
165 EncodedBytes uint64
166 DecodedPixels uint64
167}
168
169// OperationKind identifies one transactional scene operation.
170type OperationKind uint8
171
172const (
173 OperationAddAsset OperationKind = iota + 1
174 OperationRemoveAsset
175 OperationPlace
176 OperationUpdatePlacement
177 OperationRemovePlacement
178)
179
180// Operation is a sparse scene operation. Add-asset operations allocate an
181// opaque ID internally; use AddAsset directly when the ID is needed by the
182// caller for a subsequent placement.
183type Operation struct {
184 Kind OperationKind
185 Blob AssetBlob
186 Asset AssetID
187 Placement PlacementSpec
188 PlacementID PlacementID
189}
190
191// Operation aliases make operation construction readable without introducing
192// protocol-specific terminology.
193const (
194 AddAssetOperation = OperationAddAsset
195 RemoveAssetOperation = OperationRemoveAsset
196 PlaceOperation = OperationPlace
197 UpdatePlacementOperation = OperationUpdatePlacement
198 RemovePlacementOperation = OperationRemovePlacement
199)