Naming convention for semaphores

[Raikiri]

I was reading this article https://docs.vulkan.org/guide/latest/swapchain_semaphore_reuse.html and thought it was very helpful, but I think understanding it is harder than it needs to be due to a naming convention issue.

The problem is that semaphores are primitives that are signalled at the end of one operation and waited on before another operation starts. But in the current naming convention all semaphores are named after the operation that signals them. For example, submit_semaphore is signalled by vkQueueSubmit but from its name it's not clear whether it's waited by vkQueueSubmit or is signalled by it, and it's also not clear who waits for that semaphore.

I think it could be made much easier to understand if each semaphore was following a naming convention where both the operation that signals it and the operation that waits for it are in its name, for example submit_semaphore becomes submit_to_present and acquire_semaphore becomes acquire_to_submit. Following this convention, it's immediately obvious that acquire does not have a semaphore it's waiting for, that acquire_to_submit separates it from submission, that submit_to_present separates submission to presenting and that presenting does not signal anything, because there's no semaphore named present_to_something.

Note that the same naming convention has proven to work much better for matrices, when object_to_world is used instead of object_matrix, it also works much better for functions, barriers and other entities that in some sense mediate two other entities but that's another story.

[artem-lunarg]

@Raikiri Personally I have a different opinion here, but lets see if there is more feedback, since it can be subjective. So, I also use matrix convention you mentioned above, the matrix unambigiously define "from" and "to". It's a bit more compliated with semaphores. It is more easily to see that's not true with timeline semaphores - there can be multiple waiters. In general that's not necessarily true with binary semaphores too. Just as an example, if there is some conditional logic, then a semaphore signaled by the first submit can be waited on either by another submit or by the present request. I agree, it is common when a binary semaphore has a specific waiter.

The naming convention in the article is pretty common in other vulkan projects, so for some people it can be familiar. The convention is used in a small pseudocode example. The entire snippet can be put on a single screen (< 50 lines) and the semaphore variable is used in 2 places in each snippet. I don't think there is an issue with naming convention here, but there can be different preferences.

[artem-lunarg]

For example, submit_semaphore is signalled by vkQueueSubmit but from its name it's not clear whether it's waited by vkQueueSubmit or is signalled by it, and it's also not clear who waits for that semaphore.

In order to support the above reasoning here's a snippet of code from the article. I think it's obvious who signals and who waits, and the variable name is not a problem. It's just different problem spaces, bigger vulkan projects vs few lines pseudocode snippet.

    VkSubmitInfo submit_info
    submit_info.pSignalSemaphores = &submit_semaphore
    vkQueueSubmit(queue, &submit_info)

    // WARNING: submit_semaphore may still be in use by one of the previous presentation operations
    VkPresentInfo present_info
    present_info.pWaitSemaphores = &submit_semaphore
    vkQueuePresentKHR(queue, &present_info)