Libargus API Libargus Camera API

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

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:
139 ~IEGLSync() {}
140 };
141
142 } // namespace Argus
143
144 #endif // _ARGUS_EGL_SYNC_H