add documentation

return vk::Result in semaphore_t::wait_until_signalled

include/avk/avk.hpp

@@ -946,6 +946,11 @@ namespace avk
 #pragma region semaphore
 		static semaphore create_semaphore(vk::Device aDevice, const DISPATCH_LOADER_CORE_TYPE& aDispatchLoader, std::function<void(semaphore_t&)> aAlterConfigBeforeCreation = {});
 		semaphore create_semaphore(std::function<void(semaphore_t&)> aAlterConfigBeforeCreation = {});
+		/** \brief Creates a timeline semaphore
+		* \param aPayload					(optional) The initial value of the payload. Defaults to 0.
+		* \param aAlterConfigBeforeCreation (optional) Use it to alter the timeline semaphore configuration before it is actually being created.
+		* \return The created semaphore.
+		*/
 		semaphore create_timeline_semaphore(uint64_t aPayload = 0, std::function<void(semaphore_t&)> aAlterConfigBeforeCreation = {});
 #pragma endregion
 

include/avk/semaphore.hpp

@@ -49,11 +49,30 @@ namespace avk
 		const auto* handle_addr() const { return &mSemaphore.get(); }
 
 		// timeline semaphore specific functions
+
+		// returns the current value of the timeline semaphore
 		const uint64_t query_current_value() const;
+		// sets the timeline semaphore to the specified value
 		void signal(uint64_t aNewValue) const;
-		void wait_until_signalled(uint64_t aRequiredValue, std::optional<uint64_t> aTimeout = {}) const;
-		static void wait_until_signalled(const std::vector<const semaphore_t*> &aSemaphores, const std::vector<uint64_t> &aTimestamps, bool aWaitOnAll = true, std::optional<uint64_t> aTimeout = {});
-		static void wait_until_signalled(const vk::Device &d, const vk::SemaphoreWaitInfo &info, std::optional<uint64_t> aTimeout = {});
+		/** \brief Waits on host until the timiline semaphore reaches the given value or the timeout(in nanoseconds) happens.
+		* \return Value of type vk::Result containing information about whether the wait operation succeeded, or the timeout has been triggered.
+		*/
+		vk::Result wait_until_signalled(uint64_t aRequiredValue, std::optional<uint64_t> aTimeout = {}) const;
+		/** \brief Waits on host until the condition specified with the parameters is met.
+		* \param aSemaphores Vector of timeline semaphores that should be waited on. All semaphores are required to be owned by the same logical device.
+		* \param aTimestamps Vector of payload values to wait on. Is required to have the same size as aSemaphores. The n-th value in aTimestamps corresponds to the n-th entry in aSemaphores.
+		* \param aWaitOnAll (optional) If true, waits until ALL semaphores have reached their target timestamps. If false, waits until ANY semaphore has reached its target timestamp.
+		* \param aTimeout (optional) Defines a timeout (in nanoseconds) after which the function returns regardless of the semaphore state.
+		* \return Value of type vk::Result containing information about whether the wait operation succeeded, or the timeout has been triggered.
+		*/
+		static vk::Result wait_until_signalled(const std::vector<const semaphore_t*> &aSemaphores, const std::vector<uint64_t> &aTimestamps, bool aWaitOnAll = true, std::optional<uint64_t> aTimeout = {});
+		/** \brief Waits on host until the condition specified with the parameters is met.
+		* \param aDevice The logical device owning all referenced timeline semaphores.
+		* \param aInfo Struct containing all relevant information about the wait operation.
+		* \param aTimeout (optional) Defines a timeout (in nanoseconds) after which the function returns regardless of the semaphore state.
+		* \return Value of type vk::Result containing information about whether the wait operation succeeded, or the timeout has been triggered.
+		*/
+		static vk::Result wait_until_signalled(const vk::Device &aDevice, const vk::SemaphoreWaitInfo &aInfo, std::optional<uint64_t> aTimeout = {});
 
 	private:
 		// The semaphore config struct:

src/avk.cpp

@@ -7144,14 +7144,14 @@ namespace avk
 		mSemaphore.getOwner().signalSemaphore(info);
 	}
 
-	void semaphore_t::wait_until_signalled(uint64_t aRequiredValue, std::optional<uint64_t> aTimeout) const {
-		wait_until_signalled({ this }, {aRequiredValue} , true, aTimeout);
+	vk::Result semaphore_t::wait_until_signalled(uint64_t aRequiredValue, std::optional<uint64_t> aTimeout) const {
+		return wait_until_signalled({ this }, {aRequiredValue} , true, aTimeout);	// maybe avoid unnecessary vector construction by just creating SemaphoreWaitInfo in this function
 	}
 
-	void semaphore_t::wait_until_signalled(const std::vector<const semaphore_t*>& aSemaphores, const std::vector<uint64_t>& aTimestamps, bool aWaitOnAll, std::optional<uint64_t> aTimeout) {
+	vk::Result semaphore_t::wait_until_signalled(const std::vector<const semaphore_t*>& aSemaphores, const std::vector<uint64_t>& aTimestamps, bool aWaitOnAll, std::optional<uint64_t> aTimeout) {
 		assert(aSemaphores.size() == aTimestamps.size());
 		if (aSemaphores.size() == 0) {
-			return;
+			return vk::Result::eSuccess;
 		}
 
 		std::vector<const vk::Semaphore*> semaphores;
@@ -7166,12 +7166,13 @@ namespace avk
 		info.pValues = aTimestamps.data();
 
 		// assume all semapores use the same device
-		wait_until_signalled(aSemaphores.front()->mSemaphore.getOwner(), info, aTimeout);
+		return wait_until_signalled(aSemaphores.front()->mSemaphore.getOwner(), info, aTimeout);
 	}
 
-	void semaphore_t::wait_until_signalled(const vk::Device& d, const vk::SemaphoreWaitInfo& info, std::optional<uint64_t> aTimeout) {
-		auto result = d.waitSemaphores(info, aTimeout.value_or(UINT64_MAX));
+	vk::Result semaphore_t::wait_until_signalled(const vk::Device& aDevice, const vk::SemaphoreWaitInfo& aInfo, std::optional<uint64_t> aTimeout) {
+		auto result = aDevice.waitSemaphores(aInfo, aTimeout.value_or(UINT64_MAX));
 		assert(static_cast<VkResult>(result) >= 0);
+		return result;
 	}
 
 #pragma endregion