Documenting render pass creation and descriptors #831
Conversation
There was a problem hiding this comment.
I've wrangled with this a bit before too. This looks great to me.
The guiding principle I want to use is that this spec should be usable as a reference for WebGPU programmers, and the gnarly details should stay out of the way. I think this works pretty well.
I also like the approach to make the descriptor-member definitions fairly informal. Their formal behaviors can be explained by other algorithms/rules that reference them.
Co-authored-by: Kai Ninomiya <[email protected]>
Co-authored-by: Kai Ninomiya <[email protected]>
| :: | ||
| Issue: Describe this dictionary member | ||
|
|
||
| : <dfn>depthReadOnly</dfn> |
There was a problem hiding this comment.
I wonder if we might need to require that depthReadOnly implies depthLoadOp == "load", likewise for stencil.
There was a problem hiding this comment.
since the load ops are required, they can't currently be implied
but yes, we do need some wording to ensure that depthReadOnly == true can only be used with "load".
There was a problem hiding this comment.
I think depthReadOnly (/stencil) also means depthStoreOp (/stencil) needs to be "store".
There was a problem hiding this comment.
both store ops don't make any sense for the read-only depth
There was a problem hiding this comment.
I think depthStoreOp "store" makes sense because the pass-local depth values wouldn't be able to change at all with depthReadOnly. So you "load" the original value and "store" without any changes.
There was a problem hiding this comment.
It needs OUTPUT_ATTACHMENT regardless of any of the flags here, even if you can't actually output to it at all.
There was a problem hiding this comment.
dictionary GPURenderPassDepthStencilAttachmentDescriptor {
required GPUTextureView attachment;
required (GPURenderPassDepthStencilReadOnly or GPURenderPassDepthReadWriteDescriptor) depth;
required (GPURenderPassDepthStencilReadOnly or GPURenderPassStencilReadWriteDescriptor) stencil;
};
enum GPURenderPassDepthStencilReadOnly {
"readonly"
};
dictionary GPURenderPassDepthReadWriteDescriptor {
required (GPULoadOp or float) loadValue;
required GPUStoreOp storeOp;
};
dictionary GPURenderPassStencilReadWriteDescriptor {
required (GPULoadOp or GPUStencilValue) loadValue;
required GPUStoreOp storeOp;
};maybe?
There was a problem hiding this comment.
that's fancy! Do you think we could merge those structs? i.e. having something like GPULoadOp or number, where number can dynamically be float or int
There was a problem hiding this comment.
It's certainly possible, we can just say "convert the number to GPUStencilValue" in text or something. But I would prefer to leave it this way and let IDL take care of that. Plus it couldn't be reused in GPURenderPassColorAttachmentDescriptor (except using a union/any) since the type there is totally different.
There was a problem hiding this comment.
Nice work there, thank you!
It feels cleaner to me, however, to describe the criteria for a valid descriptor with the descriptor dictionary definition.
I think that makes sense to do. We just need to be careful to avoid sending the reader to a maze of links saying what can and what can't be done.
For example, Vulkan valid usage rules are required to describe all the rules in a single list for every function. This is more difficult to write and maintain, but from the user perspective it's great to see everything in one place.
| :: | ||
| Issue: Describe this dictionary member | ||
|
|
||
| : <dfn>depthReadOnly</dfn> |
There was a problem hiding this comment.
since the load ops are required, they can't currently be implied
but yes, we do need some wording to ensure that depthReadOnly == true can only be used with "load".
|
Addressed some of the feedback, had a question about what a "single subresource" means. |
|
Took one more pass at this to address the remaining feedback and fill in a few details I had passed over previously. Please take another look! |
| :: | ||
| Issue: Describe this dictionary member | ||
|
|
||
| : <dfn>depthReadOnly</dfn> |
|
Feel free to address my comments in another PR if that's too much churn. |
|
Thanks all! All feedback should be resolved at this point. Let me know if you see anything else I've missed. |
| Issue: Describe this dictionary member | ||
| </dl> | ||
|
|
||
| <div class=validusage dfn-for=GPURenderPassDescriptor> |
There was a problem hiding this comment.
hm, these should be algorithms, but we can't actually trivially make them algorithms easily with <div algorithm class=validusage ...> because they'll just end up with the algorithm name "Valid Usage". We'll figure this out later.
|
Made some minor revisions; I think this is ready to land. |
…uweb#805)" (gpuweb#831) This reverts commit 1379f26.
This pull request is incomplete, but I wanted to verify that the pattern I'm using here is what the group would like to see. Started with simply documenting
beginRenderPass()and fell down a rabbit hole real quick.It looks like elsewhere in the spec validation of various descriptors is described in the algorithms that make use of them. It feels cleaner to me, however, to describe the criteria for a valid descriptor with the descriptor dictionary definition. Not only does this make it easier for those reading the spec later to reference, as all the rules for a type are in one place, but also allows for multiple algorithms to reference the same validation rules and makes validation of nested descriptors more palatable.
If this approach works for the group I'll be happy to flesh out this PR with a more complete set of validation rules and key descriptions.
Preview | Diff