Flutter Engine
The Flutter Engine
Public Member Functions | Static Public Member Functions | List of all members
skgpu::graphite::MtlRenderCommandEncoder Class Reference

#include <MtlRenderCommandEncoder.h>

Inheritance diagram for skgpu::graphite::MtlRenderCommandEncoder:
skgpu::graphite::Resource

Public Member Functions

const char * getResourceType () const override
 
void setLabel (NSString *label)
 
void pushDebugGroup (NSString *string)
 
void popDebugGroup ()
 
void insertDebugSignpost (NSString *string)
 
void setRenderPipelineState (id< MTLRenderPipelineState > pso)
 
void setTriangleFillMode (MTLTriangleFillMode fillMode)
 
void setFrontFacingWinding (MTLWinding winding)
 
void setViewport (const MTLViewport &viewport)
 
void setVertexBuffer (id< MTLBuffer > buffer, NSUInteger offset, NSUInteger index)
 
void setVertexBufferOffset (NSUInteger offset, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
 
void ios (8.3)
 
void tvos (9.0))
 
void setFragmentBuffer (id< MTLBuffer > buffer, NSUInteger offset, NSUInteger index)
 
void setFragmentBufferOffset (NSUInteger offset, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
 
void ios (8.3)
 
void tvos (9.0))
 
void setVertexBytes (const void *bytes, NSUInteger length, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
 
void ios (8.3)
 
void tvos (9.0))
 
void setFragmentBytes (const void *bytes, NSUInteger length, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
 
void ios (8.3)
 
void tvos (9.0))
 
void setFragmentTexture (id< MTLTexture > texture, NSUInteger index)
 
void setFragmentSamplerState (id< MTLSamplerState > sampler, NSUInteger index)
 
void setBlendColor (float blendConst[4])
 
void setStencilReferenceValue (uint32_t referenceValue)
 
void setDepthStencilState (id< MTLDepthStencilState > depthStencilState)
 
void setScissorRect (const MTLScissorRect &scissorRect)
 
void drawPrimitives (MTLPrimitiveType primitiveType, NSUInteger vertexStart, NSUInteger vertexCount)
 
void drawPrimitives (MTLPrimitiveType primitiveType, NSUInteger vertexStart, NSUInteger vertexCount, NSUInteger instanceCount, NSUInteger baseInstance) SK_API_AVAILABLE(macos(10.11)
 
void ios (9.0)
 
void tvos (9.0))
 
void drawPrimitives (MTLPrimitiveType primitiveType, id< MTLBuffer > indirectBuffer, NSUInteger indirectBufferOffset) SK_API_AVAILABLE(macos(10.11)
 
void ios (9.0)
 
void tvos (9.0))
 
void drawIndexedPrimitives (MTLPrimitiveType primitiveType, NSUInteger indexCount, MTLIndexType indexType, id< MTLBuffer > indexBuffer, NSUInteger indexBufferOffset)
 
void drawIndexedPrimitives (MTLPrimitiveType primitiveType, NSUInteger indexCount, MTLIndexType indexType, id< MTLBuffer > indexBuffer, NSUInteger indexBufferOffset, NSUInteger instanceCount, NSInteger baseVertex, NSUInteger baseInstance) SK_API_AVAILABLE(macos(10.11)
 
void ios (9.0)
 
void tvos (9.0))
 
void drawIndexedPrimitives (MTLPrimitiveType primitiveType, MTLIndexType indexType, id< MTLBuffer > indexBuffer, NSUInteger indexBufferOffset, id< MTLBuffer > indirectBuffer, NSUInteger indirectBufferOffset) SK_API_AVAILABLE(macos(10.11)
 
void ios (9.0)
 
void tvos (9.0))
 
void endEncoding ()
 
- Public Member Functions inherited from skgpu::graphite::Resource
 Resource (const Resource &)=delete
 
 Resource (Resource &&)=delete
 
Resourceoperator= (const Resource &)=delete
 
Resourceoperator= (Resource &&)=delete
 
void ref () const
 
void unref () const
 
void refCommandBuffer () const
 
void unrefCommandBuffer () const
 
Ownership ownership () const
 
skgpu::Budgeted budgeted () const
 
size_t gpuMemorySize () const
 
UniqueID uniqueID () const
 
virtual const char * getResourceType () const =0
 
std::string getLabel () const
 
void setLabel (std::string_view label)
 
bool wasDestroyed () const
 
const GraphiteResourceKeykey () const
 
void setKey (const GraphiteResourceKey &key)
 
void dumpMemoryStatistics (SkTraceMemoryDump *traceMemoryDump) const
 
virtual void prepareForReturnToCache (const std::function< void()> &takeRef)
 

Static Public Member Functions

static sk_sp< MtlRenderCommandEncoderMake (const SharedContext *sharedContext, id< MTLCommandBuffer > commandBuffer, MTLRenderPassDescriptor *descriptor)
 

Additional Inherited Members

- Protected Member Functions inherited from skgpu::graphite::Resource
 Resource (const SharedContext *, Ownership, skgpu::Budgeted, size_t gpuMemorySize, bool commandBufferRefsAsUsageRefs=false)
 
virtual ~Resource ()
 
const SharedContextsharedContext () const
 
virtual void onDumpMemoryStatistics (SkTraceMemoryDump *traceMemoryDump, const char *dumpName) const
 
void setDeleteASAP ()
 

Detailed Description

Wraps a MTLRenderCommandEncoder object and associated tracked state

Definition at line 22 of file MtlRenderCommandEncoder.h.

Member Function Documentation

◆ drawIndexedPrimitives() [1/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawIndexedPrimitives ( MTLPrimitiveType  primitiveType,
MTLIndexType  indexType,
id< MTLBuffer >  indexBuffer,
NSUInteger  indexBufferOffset,
id< MTLBuffer >  indirectBuffer,
NSUInteger  indirectBufferOffset 
)

◆ drawIndexedPrimitives() [2/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawIndexedPrimitives ( MTLPrimitiveType  primitiveType,
NSUInteger  indexCount,
MTLIndexType  indexType,
id< MTLBuffer >  indexBuffer,
NSUInteger  indexBufferOffset 
)
inline

Definition at line 214 of file MtlRenderCommandEncoder.h.

216 {
217 [(*fCommandEncoder) drawIndexedPrimitives:primitiveType
218 indexCount:indexCount
219 indexType:indexType
220 indexBuffer:indexBuffer
221 indexBufferOffset:indexBufferOffset];
222 }
void drawIndexedPrimitives(MTLPrimitiveType primitiveType, NSUInteger indexCount, MTLIndexType indexType, id< MTLBuffer > indexBuffer, NSUInteger indexBufferOffset)

◆ drawIndexedPrimitives() [3/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawIndexedPrimitives ( MTLPrimitiveType  primitiveType,
NSUInteger  indexCount,
MTLIndexType  indexType,
id< MTLBuffer >  indexBuffer,
NSUInteger  indexBufferOffset,
NSUInteger  instanceCount,
NSInteger  baseVertex,
NSUInteger  baseInstance 
)

◆ drawPrimitives() [1/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawPrimitives ( MTLPrimitiveType  primitiveType,
id< MTLBuffer >  indirectBuffer,
NSUInteger  indirectBufferOffset 
)

◆ drawPrimitives() [2/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawPrimitives ( MTLPrimitiveType  primitiveType,
NSUInteger  vertexStart,
NSUInteger  vertexCount 
)
inline

Definition at line 190 of file MtlRenderCommandEncoder.h.

191 {
192 [(*fCommandEncoder) drawPrimitives:primitiveType
193 vertexStart:vertexStart
194 vertexCount:vertexCount];
195 }
void drawPrimitives(MTLPrimitiveType primitiveType, NSUInteger vertexStart, NSUInteger vertexCount)

◆ drawPrimitives() [3/3]

void skgpu::graphite::MtlRenderCommandEncoder::drawPrimitives ( MTLPrimitiveType  primitiveType,
NSUInteger  vertexStart,
NSUInteger  vertexCount,
NSUInteger  instanceCount,
NSUInteger  baseInstance 
)

◆ endEncoding()

void skgpu::graphite::MtlRenderCommandEncoder::endEncoding ( )
inline

Definition at line 252 of file MtlRenderCommandEncoder.h.

252 {
253 [(*fCommandEncoder) endEncoding];
254 }

◆ getResourceType()

const char * skgpu::graphite::MtlRenderCommandEncoder::getResourceType ( ) const
inlineoverridevirtual

Implements skgpu::graphite::Resource.

Definition at line 38 of file MtlRenderCommandEncoder.h.

38{ return "Metal Render Command Encoder"; }

◆ insertDebugSignpost()

void skgpu::graphite::MtlRenderCommandEncoder::insertDebugSignpost ( NSString *  string)
inline

Definition at line 50 of file MtlRenderCommandEncoder.h.

50 {
51 [(*fCommandEncoder) insertDebugSignpost:string];
52 }

◆ ios() [1/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 8.  3)

◆ ios() [2/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 8.  3)

◆ ios() [3/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 8.  3)

◆ ios() [4/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 8.  3)

◆ ios() [5/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 9.  0)

◆ ios() [6/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 9.  0)

◆ ios() [7/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 9.  0)

◆ ios() [8/8]

void skgpu::graphite::MtlRenderCommandEncoder::ios ( 9.  0)

◆ Make()

static sk_sp< MtlRenderCommandEncoder > skgpu::graphite::MtlRenderCommandEncoder::Make ( const SharedContext sharedContext,
id< MTLCommandBuffer >  commandBuffer,
MTLRenderPassDescriptor *  descriptor 
)
inlinestatic

Definition at line 24 of file MtlRenderCommandEncoder.h.

26 {
27 // Inserting a pool here so the autorelease occurs when we return and the
28 // only remaining ref is the retain below.
29 @autoreleasepool {
30 // Adding a retain here to keep our own ref separate from the autorelease pool
31 sk_cfp<id<MTLRenderCommandEncoder>> encoder =
32 sk_ret_cfp([commandBuffer renderCommandEncoderWithDescriptor:descriptor]);
33 return sk_sp<MtlRenderCommandEncoder>(new MtlRenderCommandEncoder(sharedContext,
34 std::move(encoder)));
35 }
36 }
const SharedContext * sharedContext() const
Definition: Resource.h:189

◆ popDebugGroup()

void skgpu::graphite::MtlRenderCommandEncoder::popDebugGroup ( )
inline

Definition at line 47 of file MtlRenderCommandEncoder.h.

47 {
48 [(*fCommandEncoder) popDebugGroup];
49 }

◆ pushDebugGroup()

void skgpu::graphite::MtlRenderCommandEncoder::pushDebugGroup ( NSString *  string)
inline

Definition at line 44 of file MtlRenderCommandEncoder.h.

44 {
45 [(*fCommandEncoder) pushDebugGroup:string];
46 }

◆ setBlendColor()

void skgpu::graphite::MtlRenderCommandEncoder::setBlendColor ( float  blendConst[4])
inline

Definition at line 160 of file MtlRenderCommandEncoder.h.

160 {
161 [(*fCommandEncoder) setBlendColorRed: blendConst[0]
162 green: blendConst[1]
163 blue: blendConst[2]
164 alpha: blendConst[3]];
165 }

◆ setDepthStencilState()

void skgpu::graphite::MtlRenderCommandEncoder::setDepthStencilState ( id< MTLDepthStencilState >  depthStencilState)
inline

Definition at line 173 of file MtlRenderCommandEncoder.h.

173 {
174 if (depthStencilState != fCurrentDepthStencilState) {
175 [(*fCommandEncoder) setDepthStencilState:depthStencilState];
176 fCurrentDepthStencilState = depthStencilState;
177 }
178 }
void setDepthStencilState(id< MTLDepthStencilState > depthStencilState)

◆ setFragmentBuffer()

void skgpu::graphite::MtlRenderCommandEncoder::setFragmentBuffer ( id< MTLBuffer >  buffer,
NSUInteger  offset,
NSUInteger  index 
)
inline

Definition at line 103 of file MtlRenderCommandEncoder.h.

103 {
104 SkASSERT(buffer != nil);
105 SkASSERT(index < kMaxExpectedBuffers);
106 if (@available(macOS 10.11, iOS 8.3, tvOS 9.0, *)) {
107 if (fCurrentFragmentBuffer[index] == buffer) {
108 this->setFragmentBufferOffset(offset, index);
109 return;
110 }
111 }
112 if (fCurrentFragmentBuffer[index] != buffer || fCurrentFragmentOffset[index] != offset) {
113 [(*fCommandEncoder) setFragmentBuffer:buffer
115 atIndex:index];
116 fCurrentFragmentBuffer[index] = buffer;
117 fCurrentFragmentOffset[index] = offset;
118 }
119 }
#define SkASSERT(cond)
Definition: SkAssert.h:116
void setFragmentBufferOffset(NSUInteger offset, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
void setFragmentBuffer(id< MTLBuffer > buffer, NSUInteger offset, NSUInteger index)
DEF_SWITCHES_START aot vmservice shared library Name of the *so containing AOT compiled Dart assets for launching the service isolate vm snapshot The VM snapshot data that will be memory mapped as read only SnapshotAssetPath must be present isolate snapshot The isolate snapshot data that will be memory mapped as read only SnapshotAssetPath must be present cache dir Path to the cache directory This is different from the persistent_cache_path in embedder which is used for Skia shader cache icu native lib Path to the library file that exports the ICU data vm service The hostname IP address on which the Dart VM Service should be served If not defaults to or::depending on whether ipv6 is specified vm service A custom Dart VM Service port The default is to pick a randomly available open port disable vm Disable the Dart VM Service The Dart VM Service is never available in release mode disable vm service Disable mDNS Dart VM Service publication Bind to the IPv6 localhost address for the Dart VM Service Ignored if vm service host is set endless trace buffer
Definition: switches.h:126
SeparatedVector2 offset

◆ setFragmentBufferOffset()

void skgpu::graphite::MtlRenderCommandEncoder::setFragmentBufferOffset ( NSUInteger  offset,
NSUInteger  index 
)

◆ setFragmentBytes()

void skgpu::graphite::MtlRenderCommandEncoder::setFragmentBytes ( const void *  bytes,
NSUInteger  length,
NSUInteger  index 
)

◆ setFragmentSamplerState()

void skgpu::graphite::MtlRenderCommandEncoder::setFragmentSamplerState ( id< MTLSamplerState >  sampler,
NSUInteger  index 
)
inline

Definition at line 151 of file MtlRenderCommandEncoder.h.

151 {
152 SkASSERT(index < kMaxExpectedTextures);
153 if (fCurrentSampler[index] != sampler) {
154 [(*fCommandEncoder) setFragmentSamplerState: sampler
155 atIndex: index];
156 fCurrentSampler[index] = sampler;
157 }
158 }
void setFragmentSamplerState(id< MTLSamplerState > sampler, NSUInteger index)

◆ setFragmentTexture()

void skgpu::graphite::MtlRenderCommandEncoder::setFragmentTexture ( id< MTLTexture >  texture,
NSUInteger  index 
)
inline

Definition at line 143 of file MtlRenderCommandEncoder.h.

143 {
144 SkASSERT(index < kMaxExpectedTextures);
145 if (fCurrentTexture[index] != texture) {
146 [(*fCommandEncoder) setFragmentTexture:texture
147 atIndex:index];
148 fCurrentTexture[index] = texture;
149 }
150 }
void setFragmentTexture(id< MTLTexture > texture, NSUInteger index)
FlTexture * texture

◆ setFrontFacingWinding()

void skgpu::graphite::MtlRenderCommandEncoder::setFrontFacingWinding ( MTLWinding  winding)
inline

Definition at line 68 of file MtlRenderCommandEncoder.h.

68 {
69 [(*fCommandEncoder) setFrontFacingWinding:winding];
70 }

◆ setLabel()

void skgpu::graphite::MtlRenderCommandEncoder::setLabel ( NSString *  label)
inline

Definition at line 40 of file MtlRenderCommandEncoder.h.

40 {
41 [(*fCommandEncoder) setLabel:label];
42 }

◆ setRenderPipelineState()

void skgpu::graphite::MtlRenderCommandEncoder::setRenderPipelineState ( id< MTLRenderPipelineState >  pso)
inline

Definition at line 54 of file MtlRenderCommandEncoder.h.

54 {
55 if (fCurrentRenderPipelineState != pso) {
56 [(*fCommandEncoder) setRenderPipelineState:pso];
57 fCurrentRenderPipelineState = pso;
58 }
59 }
void setRenderPipelineState(id< MTLRenderPipelineState > pso)

◆ setScissorRect()

void skgpu::graphite::MtlRenderCommandEncoder::setScissorRect ( const MTLScissorRect &  scissorRect)
inline

Definition at line 180 of file MtlRenderCommandEncoder.h.

180 {
181 if (fCurrentScissorRect.x != scissorRect.x ||
182 fCurrentScissorRect.y != scissorRect.y ||
183 fCurrentScissorRect.width != scissorRect.width ||
184 fCurrentScissorRect.height != scissorRect.height) {
185 [(*fCommandEncoder) setScissorRect:scissorRect];
186 fCurrentScissorRect = scissorRect;
187 }
188 }
void setScissorRect(const MTLScissorRect &scissorRect)

◆ setStencilReferenceValue()

void skgpu::graphite::MtlRenderCommandEncoder::setStencilReferenceValue ( uint32_t  referenceValue)
inline

Definition at line 167 of file MtlRenderCommandEncoder.h.

167 {
168 if (referenceValue != fCurrentStencilReferenceValue) {
169 [(*fCommandEncoder) setStencilReferenceValue:referenceValue];
170 fCurrentStencilReferenceValue = referenceValue;
171 }
172 }
void setStencilReferenceValue(uint32_t referenceValue)

◆ setTriangleFillMode()

void skgpu::graphite::MtlRenderCommandEncoder::setTriangleFillMode ( MTLTriangleFillMode  fillMode)
inline

Definition at line 61 of file MtlRenderCommandEncoder.h.

61 {
62 if (fCurrentTriangleFillMode != fillMode) {
63 [(*fCommandEncoder) setTriangleFillMode:fillMode];
64 fCurrentTriangleFillMode = fillMode;
65 }
66 }
void setTriangleFillMode(MTLTriangleFillMode fillMode)

◆ setVertexBuffer()

void skgpu::graphite::MtlRenderCommandEncoder::setVertexBuffer ( id< MTLBuffer >  buffer,
NSUInteger  offset,
NSUInteger  index 
)
inline

Definition at line 76 of file MtlRenderCommandEncoder.h.

76 {
77 SkASSERT(buffer != nil);
78 SkASSERT(index < kMaxExpectedBuffers);
79 if (@available(macOS 10.11, iOS 8.3, tvOS 9.0, *)) {
80 if (fCurrentVertexBuffer[index] == buffer) {
81 this->setVertexBufferOffset(offset, index);
82 return;
83 }
84 }
85 if (fCurrentVertexBuffer[index] != buffer || fCurrentVertexOffset[index] != offset) {
86 [(*fCommandEncoder) setVertexBuffer:buffer
88 atIndex:index];
89 fCurrentVertexBuffer[index] = buffer;
90 fCurrentVertexOffset[index] = offset;
91 }
92 }
void setVertexBuffer(id< MTLBuffer > buffer, NSUInteger offset, NSUInteger index)
void setVertexBufferOffset(NSUInteger offset, NSUInteger index) SK_API_AVAILABLE(macos(10.11)

◆ setVertexBufferOffset()

void skgpu::graphite::MtlRenderCommandEncoder::setVertexBufferOffset ( NSUInteger  offset,
NSUInteger  index 
)

◆ setVertexBytes()

void skgpu::graphite::MtlRenderCommandEncoder::setVertexBytes ( const void *  bytes,
NSUInteger  length,
NSUInteger  index 
)

◆ setViewport()

void skgpu::graphite::MtlRenderCommandEncoder::setViewport ( const MTLViewport &  viewport)
inline

Definition at line 72 of file MtlRenderCommandEncoder.h.

72 {
73 [(*fCommandEncoder) setViewport:viewport];
74 }
void setViewport(const MTLViewport &viewport)

◆ tvos() [1/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 94 of file MtlRenderCommandEncoder.h.

94 {
95 SkASSERT(index < kMaxExpectedBuffers);
96 if (fCurrentVertexOffset[index] != offset) {
97 [(*fCommandEncoder) setVertexBufferOffset:offset
98 atIndex:index];
99 fCurrentVertexOffset[index] = offset;
100 }
101 }

◆ tvos() [2/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 121 of file MtlRenderCommandEncoder.h.

121 {
122 SkASSERT(index < kMaxExpectedBuffers);
123 if (fCurrentFragmentOffset[index] != offset) {
124 [(*fCommandEncoder) setFragmentBufferOffset:offset
125 atIndex:index];
126 fCurrentFragmentOffset[index] = offset;
127 }
128 }

◆ tvos() [3/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 131 of file MtlRenderCommandEncoder.h.

131 {
132 [(*fCommandEncoder) setVertexBytes:bytes
134 atIndex:index];
135 }
void setVertexBytes(const void *bytes, NSUInteger length, NSUInteger index) SK_API_AVAILABLE(macos(10.11)
size_t length

◆ tvos() [4/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 137 of file MtlRenderCommandEncoder.h.

137 {
138 [(*fCommandEncoder) setFragmentBytes:bytes
140 atIndex:index];
141 }
void setFragmentBytes(const void *bytes, NSUInteger length, NSUInteger index) SK_API_AVAILABLE(macos(10.11)

◆ tvos() [5/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 199 of file MtlRenderCommandEncoder.h.

199 {
200 [(*fCommandEncoder) drawPrimitives:primitiveType
201 vertexStart:vertexStart
202 vertexCount:vertexCount
203 instanceCount:instanceCount
204 baseInstance:baseInstance];
205 }

◆ tvos() [6/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 208 of file MtlRenderCommandEncoder.h.

208 {
209 [(*fCommandEncoder) drawPrimitives:primitiveType
210 indirectBuffer:indirectBuffer
211 indirectBufferOffset:indirectBufferOffset];
212 }

◆ tvos() [7/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 229 of file MtlRenderCommandEncoder.h.

229 {
230 [(*fCommandEncoder) drawIndexedPrimitives:primitiveType
231 indexCount:indexCount
232 indexType:indexType
233 indexBuffer:indexBuffer
234 indexBufferOffset:indexBufferOffset
235 instanceCount:instanceCount
236 baseVertex:baseVertex
237 baseInstance:baseInstance];
238 }

◆ tvos() [8/8]

void skgpu::graphite::MtlRenderCommandEncoder::tvos ( 9.  0)
inline

Definition at line 243 of file MtlRenderCommandEncoder.h.

243 {
244 [(*fCommandEncoder) drawIndexedPrimitives:primitiveType
245 indexType:indexType
246 indexBuffer:indexBuffer
247 indexBufferOffset:indexBufferOffset
248 indirectBuffer:indirectBuffer
249 indirectBufferOffset:indirectBufferOffset];
250 }

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