update copyright date
[gnash.git] / librender / Renderer.h
blob4614451d31c7f4e78d74553e5a40c266f01b0cc1
1 //
2 // Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011
3 // Free Software Foundation, Inc
4 //
5 // This program is free software; you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation; either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // This program is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with this program; if not, write to the Free Software
17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 #ifndef RENDER_HANDLER_H
20 #define RENDER_HANDLER_H
22 /// \page Renderer_intro Render handler introduction
23 ///
24 /// Information for writing new render handlers.
25 ///
26 /// The most important thing about drawing Flash shapes is to understand how
27 /// their fill styles work.
28 /// A single Flash character can contain any number shapes that use any number
29 /// of different fill styles and line styles. The shapes of a character are
30 /// defined by a number of "paths". Some important things about paths:
31 ///
32 /// - A path is a list of connected straight lines and (quadratic bezier)
33 /// curves (=edges). Interesting to note is that in the Flash world there are
34 /// *no* primitive objects like circles, rectangles or similar. These objects
35 /// are always translated to lines and curves (a circle is a set of eight
36 /// curves).
37 ///
38 /// - All paths together must by definition always build a fully closed shape.
39 /// You can't draw a rectangle with three edges, for example, contrary to
40 /// most graphics library polygon routines that connect the last anchor to
41 /// the first. However, a *single* path does *not* have to be closed. The
42 /// missing parts may be defined by other paths (you will see this makes
43 /// sense).
44 ///
45 /// - Each path has up to two fill styles and no or one line style. The line
46 /// style should be obvious. The two fill styles define the fill to the left
47 /// (fill style zero) and to the right (fill style one) of the path if you
48 /// think of it like a vector. The fill style is defined by a index to a
49 /// list of previously defined fill style definitions. Index 0 means "no
50 /// style" and is equal to a fully transparent fill style ("hole", if you
51 /// wish).
52 ///
53 /// - Paths are *never* self-intersecting.
54 ///
55 /// Simple examples to understand this concept:
56 ///
57 /// - A rectangle that contains another rectangle. Only the area between the
58 /// two rectangles is filled (so it looks like a "o"). In this case Flash
59 /// fill create two paths (one for each rectangle) and one fill style.
60 /// Assume both paths come in clockwise order, then the outer rectangle
61 /// will have fillstyle0=0 and fillstyle1=1. The inner rectangle will have
62 /// fillstyle0=1 and fillstyle1=0.
63 ///
64 /// \code
65 /// +--------------------------------+
66 /// |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
67 /// |XXX+------------------------+XXX|
68 /// |XXX| |XXX|
69 /// |XXX+------------------------+XXX|
70 /// |XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
71 /// +--------------------------------+
72 /// \endcode
73 ///
74 /// - A rectangle is divided vertically in two halves, both having different
75 /// colors:
76 ///
77 /// \code
78 /// +-------A-------+-------B--------+
79 /// |...............|################|
80 /// A...............C################B
81 /// |...............|################|
82 /// +-------A-------+-------B--------+
83 /// \endcode
84 ///
85 /// Flash will probably produce three paths (A,B,C) and two fill styles.
86 /// Paths "A" and "B" will have just one fill style (fillstyle1 will be
87 /// zero) while path "C" (which contains only one straight line!!) will
88 /// have two fill styles. To be exact the horizontal edges would not even
89 /// be necessary to render this shape (for a scanline based renderer) but
90 /// they are necessary then the character is about to be rotated.
91 ///
92 /// Now, these are simple examples but complex graphics can be compressed very
93 /// efficiently this way. Also, this method was most probably intended for a
94 /// renderer engine that can produce the final character in just one pass
95 /// (like the AGG backend does too).
98 /// \page region_update Detection of updated regions
99 ///
100 /// (this applies to the whole Gnash playback architecture)
102 /// After advancing the root movie (see gnash::Gui::advance_movie) it is checked
103 /// which region of the stage has been changed visibly (by computing the
104 /// bounds around updated characters). This has two advantages:
105 ///
106 /// 1st, it allows a renderer/gui combination to avoid re-rendering of
107 /// unchanged parts in the scene. When supported by the rendering engine
108 /// this can be a huge performance gain. The original Flash player does
109 /// that too, btw. Altough he is able to define multiple smaller regions
110 /// for one frame. This could be implemented in Gnash, too.
111 ///
112 /// 2nd, it can detect still frames (like a stopped movie). gui.cpp can
113 /// detect these and completely avoid calling any rendering function.
114 ///
115 /// Of course, the most critical part is detection of changes. There is a
116 /// method gnash::character::set_invalidated() which gets called whenever a
117 /// critical property of a instance gets updated, like when it changes
118 /// position, for example.
119 /// It's really important to *always* call set_invalidated() *before*
120 /// any call that changes the character instance in a visible way.
121 ///
122 /// Even if no renderer really uses this information it has effects when
123 /// skipping unchanged frames. If necessary, this feature can be switched
124 /// off easily in gui.cpp (maybe using a runtime option?).
126 /// Note the updated region is only passed to the gnash::Gui, which is itself
127 /// responsible of informing the renderer (see gnash::Gui::set_invalidated_region).
128 /// This is because it's pointless
129 /// to have a renderer which updates only a small part of the stage when
130 /// the GUI shows it all since the area around the region is undefined.
131 /// However, there can be a GUI which supports update regions without needing
132 /// the renderer to do so (for example, to save time during blitting).
133 /// The GUI can also completely ignore the region information.
135 /// It's also importanto to note that the bounds passed to the GUI are just
136 /// a hint and the GUI /is/ allowed to further process and alter the information
137 /// in any way.
138 ///
139 /// As for the integer/float discussion: I used SWFRect (floats) because all
140 /// the bounds calculation involves floats anyway and so it's probably
141 /// faster than converting between ints and floats all the way.
144 #include <vector>
145 #include <boost/noncopyable.hpp>
147 #include "dsodefs.h" // for DSOEXPORT
149 #include "GnashEnums.h"
150 #include "Range2d.h"
151 #include "Point2d.h"
152 #include "RGBA.h"
153 #include "log.h"
154 #include "snappingrange.h"
155 #include "SWFRect.h"
157 // Forward declarations.
158 namespace gnash {
159 class IOChannel;
160 class CachedBitmap;
161 class rgba;
162 class Transform;
163 class SWFMatrix;
164 class FillStyle;
165 class LineStyle;
166 class Shape;
167 class MorphShape;
169 // XXX: GnashImageProxy (delayed image rendering)
170 class GnashVaapiImageProxy;
172 namespace SWF {
173 class ShapeRecord;
175 namespace image {
176 class GnashImage;
180 namespace gnash {
182 /// Base class for render handlers.
184 /// You must define a subclass of Renderer, and pass an
185 /// instance to the core (RunResources) *before* any SWF parsing begins.
187 /// For more info see page \ref Renderer_intro.
188 class DSOEXPORT Renderer : boost::noncopyable
190 public:
192 Renderer()
194 _quality(QUALITY_HIGH)
197 virtual ~Renderer() {}
199 /// Return a description of this renderer.
200 virtual std::string description() const = 0;
202 /// ==================================================================
203 /// Interfaces for adjusting renderer output.
204 /// ==================================================================
206 /// Sets the x/y scale for the movie
207 virtual void set_scale(float /*xscale*/, float /*yscale*/) {}
209 /// Sets the x/y offset for the movie in pixels. This applies to all
210 /// graphics drawn except the background, which must be drawn for the
211 /// entire canvas, regardless of the translation.
212 virtual void set_translation(float /*xoff*/, float /*yoff*/) {}
214 void setQuality(Quality q) { _quality = q; }
216 /// ==================================================================
217 /// Caching utitilies for core.
218 /// ==================================================================
220 /// \brief
221 /// Given an image, returns a pointer to a bitmap_info class
222 /// that can later be passed to FillStyleX_bitmap(), to set a
223 /// bitmap fill style.
224 virtual CachedBitmap* createCachedBitmap(
225 std::auto_ptr<image::GnashImage> im) = 0;
228 /// ==================================================================
229 /// Rendering Interface.
230 /// ==================================================================
232 /// Draws a video frame.
234 /// The frame has already been decoded and is available in RGB format only.
235 ///
236 /// @param frame The RGB video buffer frame.
237 /// Ownership of the buffer is left to the caller.
239 /// @param mat The SWFMatrix with world coordinates used to retrieve the x
240 /// and y coordinate of the video object. The scaling of the SWFMatrix
241 /// only refers to the Flash instance, *not* to the video inside that
242 /// instance. When a video object is placed on the stage and the loaded
243 /// video is smaller, then the SWFMatrix is still an "identity
244 /// matrix". However, if the video object is scaled via ActionScript,
245 /// for example, then the SWFMatrix will change. This means the
246 /// renderer has to find the correct scaling for the video inside the
247 /// bounds.
249 /// @param bounds The minX/minY fields of this SWFRect are always zero.
250 /// The width and height determine the size of the Flash video instance
251 /// on the stage (in TWIPS) prior to SWFMatrix transformations.
253 virtual void drawVideoFrame(image::GnashImage* frame,
254 const Transform& xform, const SWFRect* bounds, bool smooth) = 0;
256 /// Draw a line-strip directly, using a thin, solid line.
258 /// Can be used to draw empty boxes and cursors.
260 /// @coords an array of 16-bit signed integer coordinates. Even indices
261 /// (and 0) are x coordinates, while uneven ones are y coordinates.
263 /// @vertex_count the number of x-y coordinates (vertices).
265 /// @color the color to be used to draw the line strip.
267 /// @mat the SWFMatrix to be used to transform the vertices.
268 virtual void drawLine(const std::vector<point>& coords,
269 const rgba& color, const SWFMatrix& mat) = 0;
271 /// Draw a simple, solid filled polygon with a thin (~1 pixel) outline.
273 /// This can't be used for
274 /// Flash shapes but is intended for internal drawings like bounding boxes
275 /// (editable text fields) and similar. The polygon should not contain
276 /// self-intersections. If you do not wish a outline or a fill, then simply
277 /// set the alpha value to zero.
279 /// The polygon need NOT be closed (ie: this function will automatically
280 /// add an additional vertex to close it.
282 /// When masked==false, then any potential mask currently active will be
283 /// ignored, otherwise it is respected.
285 virtual void draw_poly(const std::vector<point>& corners,
286 const rgba& fill, const rgba& outline, const SWFMatrix& mat,
287 bool masked) = 0;
289 virtual void drawShape(const SWF::ShapeRecord& shape,
290 const Transform& xform) = 0;
292 /// \brief
293 /// Draws a glyph (font character).
295 /// Glyphs are defined just like shape characters with the difference that
296 /// they do not have any fill or line styles.
297 /// Instead, the shape must be drawn using the given color (solid fill).
298 /// Please note that although the glyph paths may indicate subshapes,
299 /// the renderer is to ignore that information.
300 ///
301 /// @param def
303 /// @param mat
305 /// @param color
306 virtual void drawGlyph(const SWF::ShapeRecord& rec, const rgba& color,
307 const SWFMatrix& mat) = 0;
309 /// Draw the current rendering buffer to an image file.
311 /// Although this can be done at any time during the rendering cycle
312 /// without harmful side effects, it's advisable only to do it when
313 /// between advance() calls, when the frame is fully renderered.
315 /// @param io The IOChannel to write to.
316 /// @param type The type of image output required (PNG, JPEG, GIF).
317 /// Note that not all FileTypes are images: rendering
318 /// to an FLV will not work.
319 virtual void renderToImage(boost::shared_ptr<IOChannel> /*io*/,
320 FileType /*type*/, int /*quality*/) const {
322 log_debug(_("Rendering to image not implemented for this "
323 "renderer"));
327 /// ==================================================================
328 /// Prepare drawing area and other utilities
329 /// ==================================================================
331 /// Sets the update region (called prior to begin_display).
333 /// The renderer
334 /// might do clipping and leave the region outside these bounds unchanged,
335 /// but he is allowed to change them if that makes sense. After rendering
336 /// a frame the area outside the invalidated region can be undefined and
337 /// is not used.
339 /// It is not required for all renderers.
340 /// Parameters are world coordinates (TWIPS).
342 /// For more info see page \ref region_update.
343 virtual void set_invalidated_regions(const InvalidatedRanges& /*ranges*/)
347 /// ==================================================================
348 /// Machinery for delayed images rendering (e.g. Xv with YV12 or VAAPI)
349 /// ==================================================================
351 ///@{
352 typedef boost::shared_ptr<GnashVaapiImageProxy> RenderImage;
353 typedef std::vector<RenderImage> RenderImages;
355 // Get first render image
356 virtual RenderImages::const_iterator getFirstRenderImage() const
357 { return _render_images.begin(); }
359 // Get last render image
360 virtual RenderImages::const_iterator getLastRenderImage() const
361 { return _render_images.end(); }
363 ///@}
365 ///@{ Masks
367 /// Masks are defined by drawing calls enclosed by begin_submit_mask()
368 /// and end_submit_mask(). Between these two calls, no drawing is to
369 /// occur. The shapes rendered between the two calls define the
370 /// visible region of the mask. Graphics that are irrelevant in the
371 /// context of a mask (lines and fill styles, for example) should be
372 /// ignored. After use, disable_mask() is called to remove the mask.
374 /// Masks may be nested. That is, end_submit_mask() may be followed
375 /// by a call to begin_submit_mask(). The resulting mask shall be an
376 /// intersection of the previously created mask. disable_mask() shall
377 /// result in the disabling or destruction of the last created mask.
378 virtual void begin_submit_mask() = 0;
379 virtual void end_submit_mask() = 0;
380 virtual void disable_mask() = 0;
381 ///@}
383 /// ==================================================================
384 /// Interface for querying the renderer.
385 /// ==================================================================
387 /// Converts world coordinates to pixel coordinates
388 virtual geometry::Range2d<int> world_to_pixel(const SWFRect& worldbounds)
389 const = 0;
391 geometry::Range2d<int> world_to_pixel(const geometry::Range2d<int>& wb)
392 const
394 if ((wb.isNull() || wb.isWorld())) return wb;
395 return world_to_pixel(SWFRect(wb.getMinX(), wb.getMinY(),
396 wb.getMaxX(), wb.getMaxY()));
399 /// Converts pixel coordinates to world coordinates (TWIPS)
400 virtual point pixel_to_world(int x, int y) const = 0;
402 geometry::Range2d<int> pixel_to_world(
403 const geometry::Range2d<int>& pixelbounds) const
405 point topleft = pixel_to_world(
406 pixelbounds.getMinX(), pixelbounds.getMinY());
407 point bottomright = pixel_to_world(
408 pixelbounds.getMaxX(), pixelbounds.getMaxY());
410 return geometry::Range2d<int> (topleft.x, topleft.y,
411 bottomright.x, bottomright.y);
414 /// \brief
415 /// Checks if the given bounds are (partially) in the current drawing
416 /// clipping area.
418 /// A render handler implementing invalidated bounds should implement
419 /// this method to avoid rendering of characters that are not visible
420 /// anyway.
421 /// By default this method always returns true, which will ensure correct
422 /// rendering. If possible, it should be re-implemented by the renderer
423 /// handler for better performance.
424 /// b contains TWIPS coordinates.
425 virtual bool bounds_in_clipping_area(const geometry::Range2d<int>& /*b*/)
426 const {
427 return true;
430 #ifdef USE_TESTSUITE
432 /// ==================================================================
433 /// Interfaces for testing only. Disabled when the testsuite isn't built.
434 /// ==================================================================
437 /// This function returns the color at any position in the stage. It is used
438 /// for automatic testing only, it should not be used for anything else!
439 /// x and y are pixel coordinates (<0 won't make any sense) and the color of
440 /// the nearest pixel is returned.
441 /// The function returns false when the coordinates are outside the
442 /// main frame buffer.
443 virtual bool getPixel(rgba& /*color_return*/, int /*x*/, int /*y*/) const {
445 log_debug("getPixel() not implemented for this renderer");
446 abort();
447 return false; // avoid compiler warning
450 /// \brief
451 /// Initializes the renderer for off-screen rendering used by the
452 /// testsuite.
454 /// This is a special function used for testcases ONLY. It is used by
455 /// MovieTester to prepare the renderer for off-screen rendering
456 /// without any GUI. The renderer is responsible to do all required
457 /// steps so that rendering is possible after the call. This may mean
458 /// that the renderer allocates memory for the given stage size.
459 ///
460 /// The function returns false when the renderer is not able to do
461 /// off-screen rendering (default).
463 /// Note the function may be called again afterwards, resizing the stage.
464 /// Any number of calls to this function is possible and the renderer
465 /// is responsible to resize any buffer instead of wasting memory.
467 /// @param width stage width in pixels
469 /// @param height stage height in pixels
470 virtual bool initTestBuffer(unsigned /*width*/, unsigned /*height*/) {
471 return false;
474 /// Return color depth (bits per pixel) or 0 if unknown/unimplemented.
476 /// Default implementation returns 0 (unknown).
478 /// TODO: this should be a pure abstract function, just don't want
479 /// to scan ogl and cairo backend for an implementation *now*
480 /// but would be needed for automated testing... Quinn, can you help ?
481 virtual unsigned int getBitsPerPixel() const {
482 return 0;
485 #endif
487 class External
489 public:
490 /// Prepare the renderer for external rendering
492 /// Note that all arguments except the background colour are useless
493 /// outside the ogl renderer.
494 External(Renderer& r, const rgba& c, int w = 0, int h = 0,
495 float x0 = 0, float x1 = 0, float y0 = 0, float y1 = 0)
497 _r(r)
499 _r.begin_display(c, w, h, x0, x1, y0, y1);
502 ~External() {
503 _r.end_display();
506 private:
507 Renderer& _r;
510 class Internal
512 public:
513 /// Prepare the renderer for internal rendering
514 Internal(Renderer& r, image::GnashImage& im)
516 _r(r),
517 _ext(_r.startInternalRender(im))
521 Renderer* renderer() const {
522 return _ext;
525 ~Internal() {
526 _r.endInternalRender();
529 private:
530 Renderer& _r;
531 Renderer* _ext;
534 protected:
536 /// Kept in parallel with movie_root's setting.
537 Quality _quality;
539 // Delayed imaged to render
540 RenderImages _render_images;
542 private:
544 /// Bracket the displaying of a frame from a movie.
546 /// Set up to render a full frame from a movie and fills the
547 /// background. Sets up necessary transforms, to scale the
548 /// movie to fit within the given dimensions. Call
549 /// end_display() when you're done.
551 /// Most of the arguments are only for the ogl renderer. See documentation
552 /// in that class. Do not use these arguments for new renderers!
553 virtual void begin_display(const rgba& background_color,
554 int viewport_width, int viewport_height,
555 float x0, float x1, float y0, float y1) = 0;
557 virtual void end_display() = 0;
559 /// Setup the renderer to draw to an internal buffer.
561 /// Implementations are free to return a new renderer if they choose.
563 /// @return 0 if the renderer does not support this.
564 virtual Renderer* startInternalRender(image::GnashImage& buffer) = 0;
566 /// Finish internal rendering.
568 /// Any rendering after this function has been called must apply to the
569 /// external buffer.
570 virtual void endInternalRender() = 0;
574 } // namespace gnash
576 #endif
579 // Local Variables:
580 // mode: C++
581 // indent-tabs-mode: t
582 // End: