VK_PIPELINE_STAGE_2_TRANSFER_BIT is missing documentation in 7.1.2.

[martty]

Only VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT is mentioned - since these are equivalent, a brief note of this equivalence would be sufficient.

[oddhack]

TRANSFER_BIT is a legacy alias for ALL_TRANSFER_BIT, so it is present in the headers for backwards compatibility but not described in the spec, just as e.g. VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT_KHR. We don't want to do this for all the aliases, of which there are many.

But the way the spec is structured does mean you have to infer that it's an alias by looking at the numeric values of the flags, which is not friendly - for the 32-bit enums the alias is directly expressed in the enumerant declaration, but not for the 64-bit enums like this one. At one point in the past, we injected comments into the headers stating this, so we would have had something like:

// VK_PIPELINE_STAGE_2_TRANSFER_BIT is an alias for VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT
static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT = 0x00001000ULL;

and perhaps we could restore that, if it would be helpful. Or it may be possible to change the declaration to

static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT = VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT;

@Tobski do you have any thoughts on this? It's been so long since we made the generator changes for 64-bit enums that I actually do not recall why we did it the specific way we did, but we may have gone overboard with conciseness.

[Tobski]

I don't recall why we did what we did at the time, but changing the declaration to

static const VkPipelineStageFlagBits2 VK_PIPELINE_STAGE_2_TRANSFER_BIT = VK_PIPELINE_STAGE_2_ALL_TRANSFER_BIT;

seems like the simplest choice

[oddhack]

@martty we discussed in our telecon just now and agreed to modify the generators to make the aliasing more explicit in the API definitions included in the spec, as suggested above, which will make the treatment consistent with the 32-bit enums everywhere. I will handle that but it will take some time.

[martty]

Thank you, that sounds good.