Libargus API
Libargus Camera API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
EGLSync.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2017, NVIDIA CORPORATION. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * * Redistributions of source code must retain the above copyright
8  * notice, this list of conditions and the following disclaimer.
9  * * Redistributions in binary form must reproduce the above copyright
10  * notice, this list of conditions and the following disclaimer in the
11  * documentation and/or other materials provided with the distribution.
12  * * Neither the name of NVIDIA CORPORATION nor the names of its
13  * contributors may be used to endorse or promote products derived
14  * from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
19  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
20  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
23  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
24  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * <b>Libargus API: EGLSync API</b>
32  *
33  * @b Description: Defines a SyncType that uses EGLSync objects.
34  */
35 
36 #ifndef _ARGUS_EGL_SYNC_H
37 #define _ARGUS_EGL_SYNC_H
38 
39 namespace Argus
40 {
41 
42 /**
43  * @defgroup ArgusBufferEGLSync EGLSync
44  * @ingroup ArgusBufferSync
45  * Sync type that uses EGLSync objects (SYNC_TYPE_EGL_SYNC).
46  */
47 
48 /**
49  * Sync type that uses EGLSync objects (SYNC_TYPE_EGL_SYNC).
50  * @ingroup ArgusBufferSync
51  */
52 DEFINE_UUID(SyncType, SYNC_TYPE_EGL_SYNC, 5df77c90,5d1b,11e7,9598,08,00,20,0c,9a,66);
53 
54 /**
55  * @class IEGLSync
56  *
57  * Interface that provides EGLSync input and output methods for a Buffer.
58  *
59  * @ingroup ArgusBufferEGLSync
60  */
61 DEFINE_UUID(InterfaceID, IID_EGL_SYNC, 5df77c91,5d1b,11e7,9598,08,00,20,0c,9a,66);
62 class IEGLSync : public Interface
63 {
64 public:
65  static const InterfaceID& id() { return IID_EGL_SYNC; }
66 
67  /**
68  * Creates and returns a new EGLSync object that is signalled when all operations on the
69  * Buffer from the previous libargus capture request have completed.
70  *
71  * When sync support is enabled for a Stream, libargus may output Buffers to that stream
72  * even if hardware operations are still pending on the Buffer's image data. In this case,
73  * libargus will attach sync information to the Buffer when it is acquired by the client
74  * that must be used to block any client operations on the image data until all preceeding
75  * libargus operations have completed. Failure to block on this sync information may lead
76  * to undefined buffer contents.
77  *
78  * This method will create and output a new EGLSync object that will be signalled once all
79  * libargus operations on the Buffer have completed. Ownership of this EGLSync object is
80  * given to the caller, who must then wait on the sync object as needed before destroying
81  * it using eglDestroySyncKHR. Calling this method more than once is allowed, and each call
82  * will create and return a new EGLSync object.
83  *
84  * This method should only ever be called while the Buffer is in an acquired state; ie. the
85  * time between when the Buffer was acquired by IBufferOutputStream::acquireBuffer and when
86  * it was released by IBufferOutputStream::releaseBuffer. If called outside of the acquired
87  * state, STATUS_UNAVAILABLE will be returned.
88  *
89  * When successful, STATUS_OK will be returned and 'eglSync' will be written with the new
90  * EGLSync object. Note that EGL_NO_SYNC_KHR is still a valid output for the 'eglSync' even
91  * when STATUS_OK is returned; this implies that libargus does not have any pending
92  * operations to the Buffer and so the client need not take any sync precautions before
93  * accessing the image data. Thus, the returned Status code should be used for detecting
94  * failures rather than checking for an EGL_NO_SYNC_KHR output.
95  *
96  * @param[in] eglDisplay The EGLDisplay that shall own the returned EGLSync object.
97  * @param[out] eglSync Output for the newly created EGLSync object. Ownership of this object
98  * is given to the client.
99  *
100  * @returns success/status of this call.
101  */
102  virtual Status getAcquireSync(EGLDisplay eglDisplay, EGLSyncKHR* eglSync) = 0;
103 
104  /**
105  * Sets the client-provided EGLSync for a Buffer prior to its release.
106  *
107  * When sync support is enabled for a Stream, the client may release Buffers back to
108  * libargus for future capture use even if the client has hardware operations pending on
109  * the Buffer's image data. In this case, the client must provide an EGLSync object to
110  * libargus that will be signalled by the completion of the client's pending operations.
111  * This sync object will then be waited on by libargus to prevent any buffer operations
112  * from occuring before the client sync has been signalled.
113  *
114  * This method should only ever be called while the Buffer is in an acquired state; ie. the
115  * time between when the Buffer was acquired by IBufferOutputStream::acquireBuffer and when
116  * it was released by IBufferOutputStream::releaseBuffer. If called outside of this period,
117  * STATUS_UNAVAILBLE will be returned and no object updates will be made. Otherwise, when
118  * called in the acquired state, this method will set the EGLSync that will be provided to
119  * libargus at the time that the Buffer is released by IBufferOutputStream::releaseBuffer
120  * and STATUS_OK will be returned. On success, ownership of the EGLSync object will be passed
121  * to libargus; further use of the EGLSync by the client after this point may lead to
122  * undefined results or abnormal termination. If called more than once when in the acquired
123  * state, any previously set EGLSync will be replaced; only the last set EGLSync before
124  * calling releaseBuffer will be waited on by libargus.
125  *
126  * If the client does not have any pending operations on the Buffer at the time that
127  * releaseBuffer is called, it is allowed for the client to either skip calling this method
128  * or to call it using EGL_NO_DISPLAY and EGL_NO_SYNC_KHR such that libargus will not have
129  * to consider any sync requirements and may use the Buffer immediately.
130  *
131  * @param[in] eglDisplay The EGLDisplay that created the EGLSync object being provided.
132  * @param[in] eglSync The EGLSync that libargus must wait on before accessing the buffer.
133  *
134  * @returns success/status of this call.
135  */
136  virtual Status setReleaseSync(EGLDisplay eglDisplay, EGLSyncKHR eglSync) = 0;
137 
138 protected:
140 };
141 
142 } // namespace Argus
143 
144 #endif // _ARGUS_EGL_SYNC_H