Gfx: [API Design] [II] Consistent/better naming

[mjadczak]

This fits in with #1254. It doesn't fall under any of the checklist items, but is something I noticed which would fall under "naming": when talking about descriptors in general, we have names like DescriptorPool and DescriptorSetLayoutBinding, but the individual descriptor structs are things like ComputePipelineDesc and BlendDesc. I understand that that's what these are called in the C++ Vulkan SDK, but I would argue that low-level C++ prefers terser names which I think fit less in a Rust library. I would suggest renaming these structs to *Descriptor.

The types/structs affected are:

• gfx_hal::pso::compute::ComputePipelineDesc
• gfx_hal::pso::graphics::GraphicsPipelineDesc
• gfx_hal::pso::graphics::BlendDesc
• gfx_hal::pso::input_assembler::VertexBufferDesc
• gfx_hal::pso::input_assembler::AttributeDesc
• gfx_hal::pso::input_assembler::InputAssemblerDesc
• gfx_hal::pso::output_merger::ColorBlendDesc
• gfx_hal::image::ResourceDesc
• gfx_hal::image::RenderDesc
• gfx_backend_dx12::native::BarrierDesc
• gfx_backend_dx12::native::SubpassDesc
• gfx_backend_gl::native::SubpassDesc
• gfx_backend_gl::native::AttributeDesc

There is definitely a discussion to be had as to whether keeping to the Vulkan SDK naming outweighs this, but I think that we should either denote these things as Desc or Descriptor, but not both.

There is also another reason we should use the full terms—these structs have Desc in their name but meaning "description", not "descriptor", which is confusing:

• gfx_hal::format::FormatDesc
• gfx_hal::pass:SubpassDesc

Other similar cases:

• we have Element in gfx_hal::pso::input_assembler, but have ElemOffset and ElemStride.
• gfx_backend_gl::native::VertexAttribFunction insted of VertexAttributeFunction

[kvark]

Please not that the semantics of term "descriptor" in DescriptorPool and DescriptorSetLayoutBinding has nothing to do with those structs ending with Desc. Hence we shouldn't try to make those types named consistently with each other. Perhaps, to avoid confusion we should change the suffix to something like Info?..

[mjadczak]

That's even more confusing then, I like *Info, or we could expand the word into *Description.

[mjadczak]

Having read through the Vulkan spec, and again through the HAL quad example, I think that there are even more things which are somewhat confusingly named, and don't match to Vulkan. I'll update this issue with more details.

[mjadczak]

So here are some more naming issues I've found. These are just from looking at the quad example—I haven't done any deeper exploration on these in the codebase:

Shortened field names

Some structs have shortened field names, which hurts the clarity of code somewhat. Examples are:

• DescriptorSetLayoutBinding.ty instead of type
• SubpassDesc has fields colors, depth_stencil, inputs and preserves, which relate to the attachments used in the subpass. I would either rename the fields to be more descriptive (e.g. color_attachments or color_atx, input_atx etc) or change the struct name to SubpassAttachments or SubpassAttachmentInfo (in which case I would still singularise the fields, e.g. color not colors, since it's short for color attachments).

Consistent terminology

I've noticed some modules use DirectX terminology instead of Vulkan terminology. For instance, GraphicsShaderSet has fields hull and domain. I'd propose sticking with Vulkan terminology and using tessellation_control and tessellation_evaluation (or e.g. tess_control) for hull and domain.