Line data Source code
1 :
2 : /* Copyright (c) 2006-2014, Stefan Eilemann <eile@equalizergraphics.com>
3 : * 2011, Daniel Nachbaur <danielnachbaur@gmail.com>
4 : *
5 : * This library is free software; you can redistribute it and/or modify it under
6 : * the terms of the GNU Lesser General Public License version 2.1 as published
7 : * by the Free Software Foundation.
8 : *
9 : * This library is distributed in the hope that it will be useful, but WITHOUT
10 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
12 : * details.
13 : *
14 : * You should have received a copy of the GNU Lesser General Public License
15 : * along with this library; if not, write to the Free Software Foundation, Inc.,
16 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17 : */
18 :
19 : #ifndef EQ_FRAMEDATA_H
20 : #define EQ_FRAMEDATA_H
21 :
22 : #include <eq/client/frame.h> // enum Frame::Buffer
23 : #include <eq/client/types.h>
24 :
25 : #include <eq/fabric/pixelViewport.h> // member
26 : #include <eq/fabric/pixel.h> // member
27 : #include <eq/fabric/range.h> // member
28 : #include <eq/fabric/subPixel.h> // member
29 :
30 : #include <co/object.h> // base class
31 : #include <lunchbox/monitor.h> // member
32 : #include <lunchbox/spinLock.h> // member
33 :
34 : namespace eq
35 : {
36 : namespace detail { class FrameData; }
37 :
38 : /**
39 : * A holder for multiple images.
40 : *
41 : * The FrameData is used to connect the Image data for multiple frames.
42 : * Equalizer uses the same frame data for all input and output frames of the
43 : * same name. This enables frame-specific parameters to be set on the Frame, and
44 : * generic parameters (of the output frame) to be set on the FrameData, as well
45 : * as ready synchronization of the pixel data.
46 : *
47 : * An application may allocate its own Frame and FrameData for
48 : * application-specific purposes.
49 : *
50 : * Parameters set on an Equalizer output frame data are automatically
51 : * transported to the corresponding input frames.
52 : */
53 : class FrameData : public co::Object, public lunchbox::Referenced
54 : {
55 : public:
56 : void assembleFrame( Frame* frame, Channel* channel );
57 : struct ImageHeader
58 : {
59 : uint32_t internalFormat;
60 : uint32_t externalFormat;
61 : uint32_t pixelSize;
62 : fabric::PixelViewport pvp;
63 : uint32_t compressorName;
64 : uint32_t compressorFlags;
65 : uint32_t nChunks;
66 : float quality;
67 : };
68 :
69 : /** Construct a new frame data holder. @version 1.0 */
70 : EQ_API FrameData();
71 :
72 : /** Destruct this frame data. @version 1.0 */
73 : EQ_API virtual ~FrameData();
74 :
75 : /** @name Data Access */
76 : //@{
77 : /** @return the storage type. @version 1.3.0 */
78 : EQ_API Frame::Type getType() const;
79 :
80 : /** Set the storage type. @version 1.3.1 */
81 : EQ_API void setType( const Frame::Type type );
82 :
83 : /** @return the enabled frame buffer attachments. @version 1.0 */
84 : EQ_API uint32_t getBuffers() const;
85 :
86 : /**
87 : * Set the enabled frame buffer attachments.
88 : *
89 : * The default buffers are set for Equalizer input and output frames
90 : * according to the configuration, or to 0 for application-created frame
91 : * datas.
92 : */
93 : EQ_API void setBuffers( const uint32_t buffers );
94 :
95 : /**
96 : * Get the range.
97 : *
98 : * The range is set for Equalizer frames to the range of the frame data
99 : * relative to the destination channel.
100 : *
101 : * @return the database-range.
102 : * @version 1.0
103 : */
104 : EQ_API const Range& getRange() const;
105 :
106 : /** Set the range of this frame. @version 1.0 */
107 : EQ_API void setRange( const Range& range );
108 :
109 : /**
110 : * @return the pixel decomposition wrt the destination channel.
111 : * @version 1.0
112 : */
113 : EQ_API const Pixel& getPixel() const;
114 :
115 : /**
116 : * @return the subpixel decomposition wrt the destination channel.
117 : * @version 1.0
118 : */
119 : EQ_API const SubPixel& getSubPixel() const;
120 :
121 : /**
122 : * @return the DPlex period relative to the destination channel.
123 : * @version 1.0
124 : */
125 : EQ_API uint32_t getPeriod() const;
126 :
127 : /**
128 : * @return the DPlex phase relative to the destination channel.
129 : * @version 1.0
130 : */
131 : EQ_API uint32_t getPhase() const;
132 :
133 : /** The images of this frame data holder. @version 1.0 */
134 : EQ_API const Images& getImages() const;
135 :
136 : /**
137 : * Set the covered area for readbacks.
138 : *
139 : * Preset for Equalizer output frames. The given pixel viewport is used
140 : * together with the Frame offset to compute the area for the readback()
141 : * operation.
142 : * @version 1.0
143 : */
144 : EQ_API void setPixelViewport( const PixelViewport& pvp );
145 :
146 : /** @return the covered area for readbacks. @version 1.3.0 */
147 : EQ_API const PixelViewport& getPixelViewport() const;
148 :
149 : /**
150 : * Set alpha usage for newly allocated images.
151 : *
152 : * Disabling alpha allows the selection of download or compression
153 : * plugins which drop the alpha channel for better performance.
154 : * @version 1.0
155 : */
156 : EQ_API void setAlphaUsage( const bool useAlpha );
157 :
158 : /**
159 : * Set the minimum quality after download and compression.
160 : *
161 : * Setting a lower quality decreases the image quality while increasing
162 : * the performance of scalable rendering. An application typically
163 : * selects a lower quality during interaction. Setting a quality of 1.0
164 : * provides lossless image compositing.
165 : * @version 1.0
166 : */
167 : void setQuality( const Frame::Buffer buffer, const float quality );
168 :
169 : /** @internal Set additional zoom for input frames. */
170 : EQ_API void setZoom( const Zoom& zoom );
171 :
172 : /** @internal @return the additional zoom. */
173 : EQ_API const Zoom& getZoom() const;
174 :
175 : /**
176 : * Sets a compressor which will be allocated and used during transmit of
177 : * the image buffer. The default compressor is EQ_COMPRESSOR_AUTO which
178 : * selects the most suitable compressor wrt the current image and buffer
179 : * parameters.
180 : * @sa _chooseCompressor()
181 : *
182 : * @param buffer the frame buffer attachment.
183 : * @param name the compressor name.
184 : */
185 : void useCompressor( const Frame::Buffer buffer, const uint32_t name );
186 : //@}
187 :
188 : /** @name Operations */
189 : //@{
190 : /**
191 : * Allocate and add a new image.
192 : *
193 : * The allocated image inherits the current quality, storage type from
194 : * this frame data and the internal format corresponding to the given
195 : * drawable config.
196 : *
197 : * @return the image.
198 : * @version 1.0
199 : */
200 : EQ_API Image* newImage( const Frame::Type type,
201 : const DrawableConfig& config );
202 :
203 : /** Clear the frame by recycling the attached images. @version 1.0 */
204 : EQ_API void clear();
205 :
206 : /** Flush the frame by deleting all images. @version 1.0 */
207 : void flush();
208 :
209 : /** Delete data allocated by the given object manager on all images.*/
210 : void deleteGLObjects( util::ObjectManager& om );
211 :
212 : /** Deallocate all transfer and compression plugins on all images. */
213 : EQ_API void resetPlugins();
214 :
215 : #ifndef EQ_2_0_API
216 : /**
217 : * Read back an image for this frame data.
218 : *
219 : * The newly read image is added to the data using newImage(). Existing
220 : * images are retained.
221 : *
222 : * @param frame the corresponding output frame holder.
223 : * @param glObjects the GL object manager for the current GL context.
224 : * @param config the configuration of the source frame buffer.
225 : * @version 1.0
226 : * @deprecated @sa startReadback()
227 : */
228 : void readback( const Frame& frame, util::ObjectManager& glObjects,
229 : const DrawableConfig& config );
230 : #endif
231 :
232 : /**
233 : * Start reading back a set of images for this frame data.
234 : *
235 : * The newly read images are added to the data using
236 : * newImage(). Existing images are retained.
237 : *
238 : * @param frame the corresponding output frame holder.
239 : * @param glObjects the GL object manager for the current GL context.
240 : * @param config the configuration of the source frame buffer.
241 : * @param regions the areas to read back.
242 : * @return the new images which need finishReadback.
243 : * @version 1.3.0
244 : */
245 : Images startReadback( const Frame& frame,
246 : util::ObjectManager& glObjects,
247 : const DrawableConfig& config,
248 : const PixelViewports& regions );
249 :
250 : /**
251 : * Set the frame data ready.
252 : *
253 : * The frame data is automatically set ready by readback() and after
254 : * receiving an output frame.
255 : * @version 1.0
256 : */
257 : void setReady();
258 :
259 : /** @return true if the frame data is ready. @version 1.0 */
260 : EQ_API bool isReady() const;
261 :
262 : /** Wait for the frame data to become available. @version 1.0 */
263 : EQ_API void waitReady( const uint32_t timeout = LB_TIMEOUT_INDEFINITE )
264 : const;
265 :
266 : /** @internal */
267 : void setVersion( const uint64_t version );
268 :
269 : typedef lunchbox::Monitor< uint32_t > Listener; //!< Ready listener
270 :
271 : /**
272 : * Add a ready listener.
273 : *
274 : * The listener value will will be incremented when the frame is ready,
275 : * which might happen immediately.
276 : *
277 : * @param listener the listener.
278 : * @version 1.0
279 : */
280 : void addListener( Listener& listener );
281 :
282 : /**
283 : * Remove a frame listener.
284 : *
285 : * @param listener the listener.
286 : * @version 1.0
287 : */
288 : void removeListener( Listener& listener );
289 :
290 : /**
291 : * Disable the usage of a frame buffer attachment for all images.
292 : *
293 : * @param buffer the buffer to disable.
294 : * @version 1.0
295 : */
296 : EQ_API void disableBuffer( const Frame::Buffer buffer );
297 : //@}
298 :
299 : /** @internal */
300 0 : struct Data
301 : {
302 12 : Data() : frameType( Frame::TYPE_MEMORY ), buffers( 0 ), period( 1 )
303 12 : , phase( 0 ) {}
304 :
305 : PixelViewport pvp;
306 : fabric::Frame::Type frameType;
307 : uint32_t buffers;
308 : uint32_t period;
309 : uint32_t phase;
310 : Range range; //<! database-range of src wrt to dest
311 : Pixel pixel; //<! pixel decomposition of source
312 : SubPixel subpixel; //<! subpixel decomposition of source
313 : Zoom zoom;
314 :
315 : EQ_API void serialize( co::DataOStream& os ) const;
316 : EQ_API void deserialize( co::DataIStream& is );
317 : };
318 :
319 : const Data& getData() const; //!< @internal
320 :
321 : /** @internal */
322 : bool addImage( const co::ObjectVersion& frameDataVersion,
323 : const PixelViewport& pvp, const Zoom& zoom,
324 : const uint32_t buffers, const bool useAlpha,
325 : uint8_t* data );
326 : void setReady( const co::ObjectVersion& frameData,
327 : const FrameData::Data& data ); //!< @internal
328 :
329 : protected:
330 0 : virtual ChangeType getChangeType() const { return INSTANCE; }
331 : virtual void getInstanceData( co::DataOStream& os );
332 : virtual void applyInstanceData( co::DataIStream& is );
333 :
334 : private:
335 : detail::FrameData* const _impl;
336 :
337 : /** Allocate or reuse an image. */
338 : Image* _allocImage( const Frame::Type type,
339 : const DrawableConfig& config,
340 : const bool setQuality );
341 :
342 : /** Apply all received images of the given version. */
343 : void _applyVersion( const uint128_t& version );
344 :
345 : /** Set a specific version ready. */
346 : void _setReady( const uint64_t version );
347 :
348 6 : LB_TS_VAR( _commandThread );
349 : };
350 :
351 : /** Print the frame data to the given output stream. @version 1.4 */
352 : EQ_API std::ostream& operator << ( std::ostream&, const FrameData& );
353 : }
354 :
355 : namespace lunchbox
356 : {
357 0 : template<> inline void byteswap( eq::FrameData::Data& value )
358 : {
359 0 : byteswap( value.pvp );
360 0 : byteswap( value.frameType );
361 0 : byteswap( value.buffers );
362 0 : byteswap( value.period );
363 0 : byteswap( value.phase );
364 0 : byteswap( value.range );
365 0 : byteswap( value.pixel );
366 0 : byteswap( value.subpixel );
367 0 : byteswap( value.zoom );
368 0 : }
369 : }
370 :
371 : #endif // EQ_FRAMEDATA_H
372 :
|
