1START-INFO-DIR-ENTRY 2This is gnash_ref.info, produced by makeinfo version 4.11 from gnash_ref.texi. 3 4* Gnash Reference Manual: (gnash_ref). Gnash 5END-INFO-DIR-ENTRY 6 7 8File: gnash_ref.info, Node: Top, Next: Introduction, Up: (dir) 9 10Gnash Reference Manual 11********************** 12 13* Menu: 14 15* Introduction:: 16* Building from Source:: 17* Software Internals:: 18* Gnash Extensions:: 19* RTMP Protocol:: 20* Mozilla/Firefox NSAPI Plugin:: 21* Appendix:: 22* Authors:: 23* GNU Free Documentation License:: 24 25--- The Detailed Node Listing --- 26 27Introduction 28 29* Audience:: 30* What Is Supported ?:: 31 32Building from Source 33 34* Overview:: 35* Getting The Source:: 36* Code Dependencies:: 37* Testing Dependencies:: 38* Documentation Dependencies:: 39* Configuring Gnash:: 40* Compiling the Code:: 41* Creating the Documentation:: 42* Running the Tests:: 43 44Software Internals 45 46* A Tour of Gnash:: 47* Sound handling in Gnash:: 48* Testing : Testing. 49* Adding New ActionScript Class:: 50 51Gnash Extensions 52 53* Creating A New Extension:: 54* Debugging An Extension:: 55* Included Extensions:: 56 57RTMP Protocol 58 59* AMF Format:: 60 61Mozilla/Firefox NSAPI Plugin 62 63* Plugin C API:: 64* Plugin C++ API:: 65* OpenGL and Threads:: 66* Plugin Event Handling:: 67 68Appendix 69 70* Code Style:: 71 72GNU Free Documentation License 73 74* 0. PREAMBLE: 0_ PREAMBLE. 75* 1. APPLICABILITY AND DEFINITIONS: 1_ APPLICABILITY AND DEFINITIONS. 76* 2. VERBATIM COPYING: 2_ VERBATIM COPYING. 77* 3. COPYING IN QUANTITY: 3_ COPYING IN QUANTITY. 78* 4. MODIFICATIONS: 4_ MODIFICATIONS. 79* 5. COMBINING DOCUMENTS: 5_ COMBINING DOCUMENTS. 80* 6. COLLECTIONS OF DOCUMENTS: 6_ COLLECTIONS OF DOCUMENTS. 81* 7. AGGREGATION WITH INDEPENDENT WORKS: 7_ AGGREGATION WITH INDEPENDENT WORKS. 82* 8. TRANSLATION: 8_ TRANSLATION. 83* 9. TERMINATION: 9_ TERMINATION. 84* 10. FUTURE REVISIONS OF THIS LICENSE: 10_ FUTURE REVISIONS OF THIS LICENSE. 85* Addendum:: 86 87 88File: gnash_ref.info, Node: Introduction, Next: Building from Source, Prev: Top, Up: Top 89 901 Introduction 91************** 92 93Gnash is a free SWF movie player. It is available as a stand-alone 94application or as a plugin for several popular web browsers. It 95supports playing media from a disk or streaming over a network 96connection. Some popular video sharing sites like YouTube are supported 97from a wide vaariety of devices from embedded ones to modern desktops. 98 99 Gnash has a better focus on security, allowing the user tight 100control of all network or disk based I/O. Gnash also supports extending 101ActionScript by creating your own. You can write wrappers for any 102development library, and import them into the player much like perl or 103python does. 104 105* Menu: 106 107* Audience:: 108* What Is Supported ?:: 109 110 111File: gnash_ref.info, Node: Audience, Next: What Is Supported ?, Up: Introduction 112 1131.1 Audience 114============ 115 116This manual is primarily focused on users interested in how to get 117Gnash installed from a package, and basic usage as a web browser 118plugin. For more technical details, please refer to the Gnash Reference 119manual. 120 121 122File: gnash_ref.info, Node: What Is Supported ?, Prev: Audience, Up: Introduction 123 1241.2 What Is Supported ? 125======================= 126 127Gnash is known to compile for most any POSIX and ANSI C++ conforming 128system if you have all the dependent libraries installed. Systems we 129test on, and which Gnash is know to run on are Ubuntu, Fedora, Debian, 130OpenBSD, NetBSD, FreeBSD, Win32, and Darwin (OSX) primarily. 131Occasionally other platforms are built, primarily by those distribution 132maintainers. This includes BeOS, Haiku, Syllable, OS/2, Solaris, 133Slackware, and Gentoo. 134 135 Gnash is a capable of reading up to SWF v9 files and opcodes, but 136primarily supports SWF v7, with better SWF v8 and v9 support under 137heavy developement. With the 0.8.2 release, Gnash includes initial 138parser support for SWF v8 and v9. Not all ActionScript 2 classes are 139implemented yet, but all of the most heavily used ones are. Many 140ActionScript 2 classes are partially implemented; there is support for 141all of the commonly used methods of each class. 142 143 Gnash has implemented about 80% of ActionScript v. 2.0, and has 144begun implementing ActionScript v. 3.0. Gnash supports the majority of 145Flash opcodes up to SWF version 9, and a wide sampling of ActionScript 146classes for SWF version 8. 147 148 As ActionsScript 3 is a more developed version of ActionScript 2, 149many of the same classes work for both. Support has been added to 150Gnash's ActionScript library to support the new ActionScript 3 filters, 151which get applied to every class. Implementing ActionScript clases is 152often the easiest way for new Gnash developers to make a contribution 153without a deep internal knpowledge of Gnash. 154 155 Gnash has included video support since early 2007, but this is an 156every changing field of reverse engineering. Many of the popular video 157sharing sites use SWF v8 or v9, which Gnash still has imperfect support 158for. This is improving all the time, so often builds from a development 159snapshot will work when using the older release packaged in your 160distribution doesn't. You can find daily snapshots of the latest CVS 161tree at: http://www.gnashdev.org/dev_snapshots 162(http://www.gnashdev.org/dev_snapshots/). 163 164 Gnash uses ffmpeg for codecs, so any file supported by Mplayer 165should work with Gnash. Gnash supports the loading of patent free 166codecs like Ogg Vorbis or Theora from disk based files, while work is 167being done to support these codecs when embedded in a SWF file. Ffmpeg 168contains the codecs used by the current SWF defintion, FLV, VP6 (ON2), 169H.263, H.264, and MP3. 170 171 172File: gnash_ref.info, Node: Building from Source, Next: Software Internals, Prev: Introduction, Up: Top 173 1742 Building from Source 175********************** 176 177* Menu: 178 179* Overview:: 180* Getting The Source:: 181* Code Dependencies:: 182* Testing Dependencies:: 183* Documentation Dependencies:: 184* Configuring Gnash:: 185* Compiling the Code:: 186* Creating the Documentation:: 187* Running the Tests:: 188 189 190File: gnash_ref.info, Node: Overview, Next: Getting The Source, Up: Building from Source 191 1922.1 Overview 193============ 194 195The typical process of building from source will involve getting the 196source (*note Getting The Source::), build dependencies (*note Code 197Dependencies::), configuration (*note Configuring Gnash::), compilation 198(*note Compiling the Code::), testing (*note Running the Tests::), and 199installation (*note Installation::). A simplified overview of the 200process would be: 201 202 203 ./autogen.sh 204 ./configure 205 make 206 make check 207 make install 208 209 If you are compiling with GCC you will probably need to use a machine 210with at least 128 megabytes of physical RAM; 64MB is not enough for a 211couple of the files, even with swap enabled and optimisation turned off. 212 213 At present the Gnash source is about 30 MB to extracted and 214configured and requires a total of about 125 megabytes to compile it. 215 216 Continue reading for detailed step-by-step instructions of the 217entire procedure. 218 219 220File: gnash_ref.info, Node: Getting The Source, Next: Code Dependencies, Prev: Overview, Up: Building from Source 221 2222.2 Getting The Source 223====================== 224 225* Menu: 226 227* Releases:: 228* CVS Access:: 229 230 231File: gnash_ref.info, Node: Releases, Next: CVS Access, Up: Getting The Source 232 2332.2.1 Releases 234-------------- 235 236Tarballs of official releases can be found in the download area of the 237project's GNU Savannah page at http://savannah.gnu.org/projects/gnash 238(http://savannah.gnu.org/projects/gnash) or under 239http://ftp.gnu.org/gnu/gnash (http://ftp.gnu.org/gnu/gnash) 240 241 242File: gnash_ref.info, Node: CVS Access, Prev: Releases, Up: Getting The Source 243 2442.2.2 CVS Access 245---------------- 246 247The latest Gnash development sources are available via anonymous CVS. 248Use the following commands to check them out (just hit return when you 249are prompted for the password): 250 251 252 export CVS_RSH=ssh 253 cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/gnash co gnash 254 255you will then be able to update your copy from the repository using 256 257 258 cd gnash 259 cvs update -d 260 261 If you only have access to the internet via a web proxy, you will 262find daily source snapshots of the latest CVS tree in 263http://www.gnashdev.org/dev_snapshots 264(http://www.gnashdev.org/dev_snapshots/) 265 266 267File: gnash_ref.info, Node: Code Dependencies, Next: Testing Dependencies, Prev: Getting The Source, Up: Building from Source 268 2692.3 Code Dependencies 270===================== 271 272Gnash has a number of dependencies on other packages. If you install 273the dependencies using a package manager, be certain to install the 274development versions of the packages. The normal versions are often 275missing the headers Gnash needs to compile. 276 277 Some dependencies have other dependencies, like GTk also needs 278glib2, atk, and pango to produce a fully linked executable. Different 279distributions also use differing dependencies, sometimes a package will 280depend on libxml2 on one system, but libexpat on another. 281 282*Code Dependency Table* 283 284Name Level Version DescriptionExplanationapt-get RPM/Yum 285 package packageBSD 286 package 287Boost Required 1.32 or Boost is In Gnash, `libboost-thread-dev,` 288 higher a library Boost libboost-date-time-devlibboost-thread-devel, 289 of libraries libboost-devlibboost-date-time-devel 290 portable are used ' '` 291 C++ extensively, boost-headers, 292 classes primarily boost-libs, 293 and boost-gthread or just 294 templates. and boost ' 295 boost-date-time. 296 Boost is 297 used for 298 thread 299 and mutext 300 handling. 301libxml2 Required Libxml2 This `libxml2-dev'`libxml2-devel'`libxml2' 302 is the library 303 GNOME XML is used 304 parser to parse 305 library messages 306 and is for the 307 available XML 308 at XMLNode, 309 http://xmlsoft.orgor 310 (http://xmlsoft.org).XMLSocket 311 ActionScript 312 classes. 313AGG Possibly 2.4 or AGG is Gnash `libagg-dev'`agg-devel'`agg' 314 Required higher the requires 315 AntiGrain the 316 low-level installation 317 2D of at 318 graphics least one 319 library. renderer. 320 AGG is 321 considered 322 the _best 323 supported_ 324 renderer 325 for Gnash. 326OpenGL Possibly OpenGL Gnash `libgl1-mesa-dev'`libmesa-devel'`mesa' 327 Required is a requires 328 standard the 329 specificationinstallation 330 defining a of at 331 cross-languageleast one 332 cross-platformrenderer. 333 API for If you 334 writing don't 335 applicationshave a 336 which hardware 337 produce accelerated 338 3D and 2D driver, 339 graphics. you're 340 It better 341 supports off using 342 hardware AGG for 343 acceleration.the 344 You can renderer. 345 download 346 a free 347 implementation 348 from 349 http://www.mesa3d.org 350 (http://www.mesa3d.org), 351 although 352 it 353 doesn't 354 support 355 hardware 356 acceleration. 357Cairo Possibly Cairo is Gnash `libcairo2-dev'`cairo-devel'`cairo' 358 Required a 2D requires 359 graphics the 360 library installation 361 with of at 362 support least one 363 for renderer. 364 multiple Cairo is 365 output considered 366 devices. the 367 It will _least 368 automaticallysupported_ 369 use renderer 370 graphic for Gnash. 371 card 372 acceleration 373 when 374 available, 375 and has 376 an 377 experimental 378 OpenGL 379 backend. 380GTK Possibly 2.2 or GTK is Gnash `libgtk2.0-dev'`gtk-devel'`gtk+2' 381 Required higher the GIMP requires 382 Toolkit the 383 GUI installation 384 library of at 385 used by least one 386 the GNOME GUI 387 desktop. library. 388 It uses GTK is 389 Cairo considered 390 internally.to be the 391 Gtk _best 392 enables supported_ 393 better GUI 394 integrationlibrary 395 with option 396 Firefox, for Gnash. 397 as well 398 as better 399 event 400 handling 401 and 402 higher 403 level GUI 404 constructs 405 like 406 menus and 407 dialog 408 boxes. 409GtkGlExt Possibly GtkGlExt This `libgtkglext1-dev'`gtkglext-devel'`gtkglext' 410 Required integrates library 411 OpenGL is 412 into GTK. required 413 in order 414 to use 415 the GTK 416 GUI 417 library 418 in 419 conjunction 420 with the 421 OpenGL 422 renderer. 423SDL Possibly The Gnash `libsdl1.2-dev'`SDL-devel'`SDL-1.2' 424 Required Simple requires 425 DirectMediathe 426 Layer is installation 427 a of at 428 cross-platformleast one 429 multimedia GUI 430 library library. 431 which SDL may 432 provides also be 433 abstractionused as a 434 for sound 435 audio, handler 436 graphics, regardless 437 sound and of 438 input whether 439 APIs. it is 440 SDL is employed 441 available as a GUI 442 from library. 443 http://www.libsdl.orgThe GUI 444 (http://www.libsdl.org).library 445 is 446 _poorly 447 supported_ 448 in Gnash, 449 but the 450 sound 451 handler 452 is the 453 _best 454 supported_ 455 in Gnash. 456FLTK Possibly 2.0 or The Fast Gnash No No 457 Required higher Light requires distributiondistribution 458 ToolKit the packages packages 459 is a installationare are 460 portable of at available. available.No 461 GUI least one distribution 462 library GUI packages 463 which is library. are 464 intended FLTK may available. 465 as a be used 466 replacementin 467 for the conjunction 468 SDL GUI. with the 469 Cairo and 470 AGG 471 renderers. 472KDE Possibly Kdelibs Gnash `kdelibs3-dev,`kdelibs-devel, 473 Required is a requires kdebase-dev'kdebase-devel'`kdelibs, 474 collection the kdebase' 475 of installation 476 libraries of at 477 needed to least one 478 compile GUI 479 KDE library. 480 applications.Kdelibs 481 is also 482 required 483 for the 484 Kpart 485 plugin 486 for 487 Konqueror. 488Gstreamer Optional Gstreamer If you `libgstreamer0.8-dev'`gstreamer-devel'`gstreamer-0.10' 489 is a would 490 video like 491 handler. video 492 playback, 493 you must 494 install 495 one of 496 the video 497 handlers. 498gst-ffmpeg Possibly gst-ffmpegThis `gstreamer0.8-ffmpeg-dev'`gstreamer-ffmpeg-devel'`gstreamer-ffmpeg' 499 Required allows package 500 you to is 501 use the required 502 FFMPEG if you 503 decoder would 504 with like to 505 Gstreamer. use 506 Gstreamer 507 as a 508 video 509 handler. 510FFMPEG Possibly FFMPEG If you `ffmpeg-dev'`ffmpeg-devel'`ffmpeg' 511 Required is a would 512 video like 513 handler. video 514 playback, 515 you must 516 install 517 one of 518 the video 519 handlers. 520 When 521 using the 522 gstreamer-ffmpeg 523 plugin, 524 ffmpeg 525 doesn't 526 need to be 527 installed, 528 as it's 529 part of 530 the 531 plugin. 532 For 533 systems 534 without 535 Gstreamer 536 support, 537 ffmpeg 538 can be 539 used 540 directly. 541JPEG Optional JPEG This `libjpeg62-dev'`libjpeg'`jpeg' 542 (http://www.ijg.org/)library 543 is a is used 544 lossy for 545 image rendering 546 format JPEGs. 547 which is 548 heavily 549 used for 550 images. 551PNG Optional PNG This `libpng12-dev'`libpng'`png' 552 (http://www.libpng.org/pub/png/)library 553 is a is used 554 patent-freefor 555 image rendering 556 format PNGs. 557 which is 558 comparable 559 to _GIF_. 560libcurl Optional libcurl This `libcurl4-gnutls'`libcurl'`curl' 561 is the library 562 multiprotocalis used 563 file for URL 564 transfer downloading. 565 library. 566Glib2 Optional Glib2 is This `glib2-dev'`glib2-devel'`glib2' 567 a library 568 dependency is used 569 of Gtk, for 570 and is a convenience. 571 collection 572 of 573 commonly 574 used 575 functions. 576Atk Optional Atk is a This `atk-dev' `atk-devel'`atk' 577 dependency library 578 of Gtk, is used 579 and is for 580 used for accessiblity.. 581 accessibility 582 support. 583Pango Optional Pango is This `pango-dev'`pango-devel'`pango' 584 a library 585 dependency is used 586 of Gtk, for font 587 and is handling. 588 used for 589 font 590 handling. 591automake Possibly 1.6.0 Automake This `automake' `automake'`automake' 592 Required is a tool package 593 for is 594 generating required 595 _Makefile.in_to run 596 files. _autogen.sh_, 597 which is 598 a 599 requirement 600 if you 601 are using 602 the 603 development 604 source 605 from CVS. 606autoconf Possibly 2.59 Autoconf This `autoconf' `autoconf'`autoconf' 607 Required is a package 608 package is 609 for required 610 generating to run 611 configure _autogen.sh_, 612 scripts. which is 613 a 614 requirement 615 if you 616 are using 617 the 618 development 619 source 620 from CVS. 621gettext Possibly 0.14.6 Gettext This `gettext' `gettext'`gettext' 622 Required is part package 623 of the is 624 GNU required 625 Translationto run 626 Project. _autogen.sh_, 627 which is 628 a 629 requirement 630 if you 631 are using 632 the 633 development 634 source 635 from CVS. 636libtool Possibly 1.5.22 This is This `libltdl3-dev'`libtool'`libtool' 637 Required a generic package 638 library is 639 support required 640 script. to run 641 _autogen.sh_, 642 which is 643 a 644 requirement 645 if you 646 are using 647 the 648 development 649 source 650 from CVS. 651 652 653File: gnash_ref.info, Node: Testing Dependencies, Next: Documentation Dependencies, Prev: Code Dependencies, Up: Building from Source 654 6552.4 Testing Dependencies 656======================== 657 658Gnash tries to run as many tests as possible, but will simply skip 659tests if the tools to run them are unavailable. 660 661*Testing Dependency Table* 662 663Name Level Version DescriptionExplanationapt-get RPM/Yum 664 package packageBSD 665 package 666Ming Optional 0.4.0_beta4 Ming is Ming is No No 667 or higher an the distributiondistribution 668 ActionScriptprimary packages packages 669 compiler. compiler are are 670 for available. available.No 671 ActionScript distribution 672 testcases. packages 673 are 674 available. 675Mtasc Optional 1.12 or Mtasc is Mtasc is `mtasc' No 676 higher an used in distribution 677 ActionScriptsome packages 678 compiler. tests. are 679 available.No 680 distribution 681 packages 682 are 683 available. 684swfc Optional part of Swfc a Swfc is No No 685 swftools swf used in distributiondistribution 686 0.8.1 decompiler.some packages packages 687 testcases. are are 688 available. available.No 689 distribution 690 packages 691 are 692 available. 693swfmill Optional 0.2.12 Swfmill Swfmill No No 694 is an is used distributiondistribution 695 XML-based in some packages packages 696 SWF testcases. are are 697 (Shockwave available. available.No 698 Flash) distribution 699 processing packages 700 tool. are 701 available. 702Python Optional 2.4 or Python Python is `python' `python'`python' 703 higher is a used by 704 scripting part of 705 language. the 706 testing 707 framework. 708DejaGnu Optional 1.4 or DejaGnu DejaGnu `dejagnu' `dejagnu'`dejagnu' 709 higher is a is used 710 testing to run 711 framework. multiple 712 tests in 713 an 714 automated 715 fashion. 716 717 718File: gnash_ref.info, Node: Documentation Dependencies, Next: Configuring Gnash, Prev: Testing Dependencies, Up: Building from Source 719 7202.5 Documentation Dependencies 721============================== 722 723The following packages are used to build Gnash's documentation. 724 725*Documentation Dependency Table* 726 727Name Level Version DescriptionExplanationapt-get RPM/Yum 728 package packageBSD 729 package 730Docbook Required Docbook Gnash `docbook-utils'`docbook-dtd41-sgml' 731 (http://http://docbook.sourceforge.net/)documentationand and 732 is is an is `docbook-dsssl'`docbook-style-dsssl'docbook 733 industry-standardwritten 734 XML in 735 format Docbook. 736 for 737 technical 738 documentation. 739 You can 740 download 741 it from 742 http://sourceforge.net/project/showfiles.php?group_id=21935#files 743 (http://sourceforge.net/project/showfiles.php?group_id=21935#files). 744DocBook2X Optional This DocBook2X `docbook2x'`docbook2x'`docbook2x' 745 software is 746 package required 747 converts to 748 Docbook produce 749 documents HTML and 750 to the Texinfo 751 traditionalformats. 752 man page 753 format, 754 GNU 755 Texinfo 756 format, 757 and HTML 758 (via 759 Texinfo) 760 format. 761 It is 762 available 763 at 764 http://docbook2x.sourceforge.net/ 765 (http://docbook2x.sourceforge.net/). 766DocBook-utilsOptional This DocBook-utils`docbook-utils'`docbook-utils'`docbook-utils' 767 software is 768 package required 769 converts to 770 Docbook produce 771 documents HTML and 772 to the Texinfo 773 traditionalformats. 774 man page 775 format, 776 GNU 777 Texinfo 778 format, 779 and HTML 780 (via 781 Texinfo) 782 format. 783Texinfo Possibly Texinfo Texinfo `texinfo' `texinfo'`texinfo' 784 Required can be is 785 used to required 786 convert if you 787 DocBook2X wish to 788 output product 789 into GNU GNU info 790 info pages. 791 pages. 792 You can 793 download 794 it from 795 http://ftp.gnu.org/gnu/texinfo/ 796 (http://ftp.gnu.org/gnu/texinfo/). 797FOP Optional 0.20.5 FormattingFOP is `fop' `fop'`fop' 798 Objects required 799 Processor for PDF 800 is a output. 801 print 802 formatter 803 driven by 804 XSL 805 formatting 806 objects. 807 It is a 808 Java 809 application 810 which can 811 output 812 PDF, PCL, 813 PS, SVG, 814 XML, 815 Print, 816 AWT, MIF, 817 and Text. 818 It is 819 available 820 at 821 http://xmlgraphics.apache.org/fop/ 822 (http://xmlgraphics.apache.org/fop/). 823Java Possibly FOP Sun's Download Download 824(j2re) Required requires Java the the 825 Sun's runtime package package 826 Java (j2re) is from Sun from Sun 827 runtime required (http://java.sun.com).(http://java.sun.com). 828 (GCJ does to use 829 not work FOP. 830 with 831 FOP). 832 You can 833 download 834 it from 835 http://java.sun.com 836 (http://java.sun.com). 837JAI Possibly Sun's JAI is Download Download 838 Required Java required the the 839 Advanced if you package package 840 Imaging wish to from Sun from Sun 841 API can include (http://java.sun.com/products/java-media/jai/iio.html).(http://java.sun.com/products/java-media/jai/iio.html). 842 be graphics 843 downloaded in a PDF 844 from file being 845 http://java.sun.com/products/java-media/jai/iio.htmlgenerated 846 (http://java.sun.com/products/java-media/jai/iio.html).with FOP. 847 848 If you install j2re, set the _JAVA_HOME_ environment variable to the 849top directory of the j2re installation. If you encounter problems with 850the Java installation, you may also need to add this path to the 851_CLASSPATH_ environment variable. 852 853 854File: gnash_ref.info, Node: Configuring Gnash, Prev: Documentation Dependencies, Up: Building from Source 855 8562.6 Configuring Gnash 857===================== 858 859Gnash, like most GNU projects, allows a user to select various options 860before compiling its source code. These options include selecting from 861the available features, specifying custom paths for installation, and 862cross compiling support uses GNU Autoconf 863(http://www.gnu.org/software/autoconf/) for configuration. 864 865 If you opted to download the [Cross reference to non-existant ID 866"sourcerepo"] of Gnash, the _configure_ script will not be included. 867It can be created by running _autogen.sh_ from the source root 868directory: 869 870 871 ./autogen.sh 872 873Note that there are some dependencies (*note Code Dependencies::) for 874autogen. 875 876 All the standard `configure' options are available. In addition, 877Gnash has two types of options: those that [Cross reference to 878non-existant ID "features"], and those that specify custom paths for 879development packages (*note Specifying Custom Paths::) which are not 880found during the default search. A complete list of _all_ 881configuration options, including standard ones, can be seen by typing: 882 883 884 ./configure --help |less 885 886Read further for a more detailed explanation of Gnash-specific options. 887 888 The syntax for running _configure_ is as follows: 889 890 891 configure <options> 892 893The example below shows the `configure' options which create the 894smallest working standalone version of Gnash. In this example, 895`configure' is being run from the source root directory: 896 897 898 ./configure --disable-debugger --disable-cygnal \ 899 --disable-plugin --enable-media=ffmpeg --enable-gui=sdl 900 901 By default, you shouldn't need to supply any options to configure. 902The configure script will attempt to determine what to build based on 903the development libraries you have installed. The default configuration 904for Gnash is both GTK and KDE GUIs, the AGG renderer, and Gstreamer for 905mltimedia support, with no extensions built. 906 907 Being higher portable, Gnash has many configuration options 908available, and not all are supposed to work together. A common mistake 909when configuring Gnash is to supply too many options, overdriving 910Gnash's ability to do the right thing. 911 912* Menu: 913 914* Features:: 915* Specifying Custom Paths:: 916 917 918File: gnash_ref.info, Node: Features, Next: Specifying Custom Paths, Up: Configuring Gnash 919 9202.6.1 Features 921-------------- 922 923Some switches can be used during configuration to enable or disable 924features of Gnash. Some of the most important configuration options are: 925 926 * `--enable-gui' lets you specify your GUI of choice. The default 927 option is GTK. 928 929 * `--enable-renderer' allows a renderer to be chosen. The default 930 renderer is AGG. 931 932 * `--enable-media' permits a media handler to be selected. The 933 default is Gstreamer. 934 935 A complete list of available features follows. 936 937*Configuration Options - Features* 938 939Option Function 940`--enable-debugger' Enable support for the Flash 941 debugger. The debugger is mainly of 942 interest to Flash developers, and 943 is still under development. 944`--enable-lirc' Enable support for the LIRC remote 945 control protocol. 946`--enable-cygnal' Build the Cygnal streaming media 947 server. 948`--disable-menus' Disable building all the menus for 949 the GUI. THis is used by mobile 950 devices without as much screen 951 space. 952`--enable-docbook' Enable the generation of HTML, 953 INFO, and MAN versions of the 954 documentation from the Docbook XML. 955 You will then be able to use `make 956 html', `make info', and `make man' 957 commands. By default, man,info and 958 html pages are generated. 959`--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp'Select the Graphic User Interface 960 to use (choose one).? 961 [undisplayable block object] 962`--enable-i810-lod-bias' Enable fix for Intel 810 LOD bias 963 problem. Older versions of libMesa 964 on the Intel i810 or i815 graphics 965 processor need this flag or Gnash 966 will core dump. This has been fixed 967 in newer versions (summer 2005) of 968 libMesa. 969`--enable-media=ffmpeg|gst|none' Select the specified media decoder 970 and sound engine. FFMPEG uses the 971 SDL sound engine; GST uses its own. 972 `GST' is the default decoder. ? 973 [undisplayable block object] You 974 should only select one media 975 decoder. 976`--disable-nsapi'`--enable-nsapi' Force disable/enable building the 977 NPAPI plugin. By default the 978 Mozilla plugin is built if the GTK 979 gui is selected. Specify the 980 `--with-npapi-plugindir=' option to 981 specify where the plugin should be 982 installed. 983`--disable-kparts'`--enable-kparts' Force disable/enable building the 984 KPARTS plugin. By default the KDE 985 plugin is built if the kde gui is 986 selected. Specify the 987 `--with-kde-plugindir=' and 988 `--with-kde-servicesdir=' options 989 (or more generally the 990 `--with-kde-pluginprefix=' one) to 991 specify where the plugin should be 992 installed. The default installation 993 dir is extracted from kde-config. 994`--disable-plugins' Disable build of both kparts and 995 npapi plugins 996`--enable-renderer=opengl|cairo|agg' Enable support for the a graphics 997 backend. Currently only `opengl' and 998 `agg' work sufficiently. OpenGL is 999 used when you have hardware 1000 accelerated graphics. AGG i used 1001 when you do not have hardware 1002 accelerated graphics. Typically 1003 most desktop machines have OpenGL 1004 support, and most embedded systems 1005 do not. OpenGl is the default when 1006 building Gnash, although the 1007 quality of AGG's rendering is 1008 currently superior to OpenGL. 1009`--enable-sdk-install' Enable installing the libraries and 1010 headers as an SDK. 1011`--disable-shared' Enable installing the shared 1012 libraries and headers. Note that 1013 the extensions mechanism may not 1014 work if shared libraries are 1015 disabled. 1016`--enable-strict' Turn verbose GCC compiler warnings. 1017 By default only `-Wall' is used 1018 with GCC. 1019`--enable-fps-debug' Enable FPS debugging code. When 1020 this feature is compiled in you can 1021 use the -f switch of Gnash to have 1022 FPS printed at regular intervals. 1023`--enable-write' Makes the Mozilla plugin write the 1024 currently playing SWF movie to 1025 `/tmp'. 1026`--disable-mit-shm' Disable support for the MIT-SHM X 1027 extensions. Currently support is 1028 only available using GTK gui and 1029 AGG renderer. Keeping it enabled 1030 is not a problem as it will not be 1031 used if not available in the 1032 current X session. 1033 1034 1035File: gnash_ref.info, Node: Specifying Custom Paths, Prev: Features, Up: Configuring Gnash 1036 10372.6.2 Specifying Custom Paths 1038----------------------------- 1039 1040By default, none of these options should be required unless you want 1041Gnash to use a specific version of a development package, or if the 1042configure test fails to find a component. Please [Cross reference to 1043non-existant ID "bugreport"] if a configure test fails. 1044 1045 The following custom path options are available: 1046 1047*Custom Path Options* 1048 1049Option Function 1050`--x-includes=DIR' X include files are in DIR. 1051`--x-libraries=DIR' X library files are in DIR. 1052`--with-libxml=PFX' Prefix to where libxml is 1053 installed. 1054`--with-libxml-libraries=DIR' Directory where libxml library is 1055 installed. 1056`--with-libxml-includes=DIR' Directory where libxml header 1057 files are installed. 1058`--with-docbook=DIR' Directory where the DocBook 1059 style-sheets are installed. 1060`--with-sdl-prefix=PFX' Prefix where SDL is installed. 1061`--with-zlib-incl' Directory where zlib header is 1062 installed. 1063`--with-zlib-lib' Directory where zlib library is 1064 installed. 1065`--with-jpeg-incl' Directory where jpeg header is 1066 installed. 1067`--with-jpeg-lib' Directory where jpeg library is 1068 installed. 1069`--with-png-incl' Directory where png header is 1070 installed. 1071`--with-png-lib' Directory where png library is 1072 installed. 1073`--with-qt-dir' Directory where QT is installed. 1074 This is only used by the Klash 1075 plugin. 1076`--with-qt-includes' Directory where the QT header 1077 files are installed. This is only 1078 used by the Klash plugin. 1079`--with-qt-libraries' Directory where the QT libraries 1080 are installed. This is only used by 1081 the Klash plugin. 1082`--with-npapi-plugindir' This is the directory to install 1083 the NPAPI (Mozilla) plugin in. By 1084 default it goes to 1085 ~/.mozilla/plugins. 1086`--with-kde-pluginprefix' This option sets the default 1087 install dir for all KPARTS (kde) 1088 files. The plugin will be 1089 installed in PREFIX/lib/kde3, use 1090 `-with-kde-plugindir' to override. 1091 The service file in 1092 PREFIX/share/services, use 1093 `--with-kde-servicesdir' to 1094 override. The config file in 1095 PREFIX/share/config, use 1096 `--with-kde-configdir' to override. 1097 The appdata file in 1098 PREFIX/share/apps/klash, use 1099 `--with-kde-appsdatadir' to 1100 override. 1101`--with-kde-plugindir' This is the directory to install 1102 the KPARTS (kde) plugin in. By 1103 default it is what's set by 1104 -with-kde-pluginprefix or what's 1105 returned by kde-config -install 1106 module -expandvars, or 1107 $(prefix)/share/services if 1108 kde-config is not found. 1109`--with-kde-servicesdir' This is the directory to install 1110 the KPARTS (kde) service in. By 1111 default it is what's set by 1112 -with-kde-pluginprefix or what's 1113 returned by kde-config -install 1114 services -expandvars, or 1115 $(libdir)/kde3 if kde-config is not 1116 found. 1117`--with-kde-configdir' This is the directory to install 1118 the KPARTS (kde) config files in. 1119 By default it is what's set by 1120 -with-kde-pluginprefix or what's 1121 returned by kde-config -install 1122 config -expandvars, or 1123 $(prefix)/share/config if 1124 kde-config is not found. 1125`--with-kde-appsdatadir' This is the directory to install 1126 the KPARTS (kde) application data 1127 files in. By default it is what's 1128 set by -with-kde-pluginprefix or 1129 what's returned by kde-config 1130 -install data -expandvars, or 1131 $(prefix)/share/apps if kde-config 1132 is not found. 1133`--with-ming' Ming is used to build test cases, 1134 but not by the Gnash player itself. 1135`--with-ogg_incl' Directory where the libogg headers 1136 are installed. 1137`--with-ogg_lib' Directory where the libogg library 1138 is installed. 1139`--with-gstreamer-incl' Directory where the Gstreamer 1140 headers are installed. Gstreamer 1141 version 0.10 or greater must be 1142 used. 1143`--with-gstreamer-lib' Directory where the Gstreamer 1144 library is installed. Gstreamer 1145 version 0.10 or greater must be 1146 used. 1147`--with-opengl-includes' Directory where OpenGL (libMesa) 1148 headers are installed. 1149`--with-opengl-lib' Directory where the OpenGL 1150 (libMesa) library is installed. 1151`--with-glext-incl' Directory where GtkGlExt headers 1152 are installed. 1153`--with-glext-lib' Directory where the GtkGlExt 1154 library is installed. 1155`--with-gtk2-incl' Directory where the Gtk2 headers 1156 are installed. 1157`--with-gtk2-lib' Directory where the Gtk2 library 1158 is installed. 1159`--with-cairo_incl' Directory where the Cairo headers 1160 are installed. 1161`--with-cairo-lib' Directory where the Cairo library 1162 is installed. 1163`--with-glib-incl' Directory where the Glib headers 1164 are installed. 1165`--with-glib-lib' Directory where the Glib library 1166 is installed. 1167`--with-pango-incl' Directory where the Pango headers 1168 are installed. 1169`--with-pango-lib' Directory where the Pango library 1170 is installed. 1171`--with-atk-incl' Directory where the ATK headers 1172 are installed. 1173`--with-atk-lib' Directory where the ATK library is 1174 installed. 1175`--with-pthread-incl' Directory where the Pthread 1176 headers are installed. 1177`--with-pthread-lib' Directory where the Pthread 1178 library is installed. 1179`--with-agg-incl' Directory where the AGG 1180 (Antigrain) headers are installed. 1181`--with-agg-lib' Directory where the AGG 1182 (Antigrain) library is installed. 1183`--with-ffmpeg-incl' Directory where the FFMPEG headers 1184 are installed. 1185`--with-ffmpeg-lib' Directory where the FFMPEG library 1186 is installed. 1187`--with-boost-incl' Directory where the Boost headers 1188 are installed. 1189`--with-boost-lib' Directory where the Boost library 1190 is installed. 1191`--with-curl-incl' Directory where the libCurl 1192 headers are installed. 1193`--with-curl-lib' Directory where the libCurl 1194 library is installed. 1195 1196 Once you have [Cross reference to non-existant ID 1197"pre-configuration"] Gnash, you are ready to build the code. Gnash is 1198built using _GNU make_. 1199 1200* Menu: 1201 1202* Overview:: 1203* Getting The Source:: 1204* Code Dependencies:: 1205* Testing Dependencies:: 1206* Documentation Dependencies:: 1207* Configuring Gnash:: 1208* Compiling the Code:: 1209* Creating the Documentation:: 1210* Running the Tests:: 1211 1212 1213File: gnash_ref.info, Node: Compiling the Code, Next: Creating the Documentation, Up: Building from Source 1214 12152.7 Compiling the Code 1216====================== 1217 1218The most basic way to compile code is simply: 1219 1220 1221 make 1222 1223If the compilation ends with an error, check the output of _configure_ 1224and ensure that you are not missing any required prerequisites. The 1225output of `make' can be verbose; you may wish to pipe the output to a 1226file. 1227 1228 The variables used by _make_ can be redefined when the program is 1229invoked, if you desire it. The most interesting flags are _CFLAGS_ 1230and _CXXFLAGS_, which are often used to enable debugging or turn of 1231optimization. The default value for both of these variables is _-O2 1232-g_. A list of influential environment variables can be seen in the 1233configuration help: 1234 1235 ./configure --help 1236 1237 In the following example, debugging is enabled and optimization is 1238disabled: 1239 1240 make CFLAGS=-g CXXFLAGS=-g 1241 1242 1243File: gnash_ref.info, Node: Creating the Documentation, Next: Running the Tests, Prev: Compiling the Code, Up: Building from Source 1244 12452.8 Creating the Documentation 1246============================== 1247 1248By default, documentation is not built when you install (*note 1249Installation::) Gnash. This is because there are a number of [Cross 1250reference to non-existant ID "docdepend"]. Documentation is built when 1251it is specified with a specific target in the generated `Makefile' in 1252the `doc/C' sub-directory. If you type `make install' in this 1253directory, all documents will be built. 1254 1255 You must specify a target output format when you wish to create 1256documentation. The available output formats are: `html', `pdf', `info', 1257`man', and `alldocs'. It is also possible to output `GNOME help' if 1258the [Cross reference to non-existant ID "features"] `--enable-ghelp' 1259was used. The `alldocs' target will build all output formats except 1260_GNOME help_. For example, to create HTML output, type: 1261 1262 1263 make html 1264 1265 Gnash also uses Doxygen 1266(http://www.stack.nl/~dimitri/doxygen/index.html) to produce _HTML_ 1267documentation of Gnash internals. You must have Doxygen installed to 1268produce this documentation, which is built from the `doc' directory 1269with the command (documents will be placed in the subdirectory 1270`apidoc/html'): 1271 1272 1273 make apidoc 1274 1275 1276File: gnash_ref.info, Node: Running the Tests, Prev: Creating the Documentation, Up: Building from Source 1277 12782.9 Running the Tests 1279===================== 1280 1281Before beginning the potentially lengthy install, it is wise to test 1282the installation. If a test fails, please report it by following the 1283[Cross reference to non-existant ID "bugreport"]. 1284 1285* Menu: 1286 1287* Using DejaGnu:: 1288* Running The Tests Manually:: 1289* Installation:: 1290* Cross Configuring:: 1291 1292 1293File: gnash_ref.info, Node: Using DejaGnu, Next: Running The Tests Manually, Up: Running the Tests 1294 12952.9.1 Using DejaGnu 1296------------------- 1297 1298The easiest way to run Gnash's test suite is to install _DejaGnu 1299(http://www.gnu.org/software/dejagnu)_. After installing DejaGnu, run: 1300 1301 1302 make check 1303 1304* Menu: 1305 1306* Increasing Verbosity:: 1307* Running Some Tests:: 1308 1309 1310File: gnash_ref.info, Node: Increasing Verbosity, Next: Running Some Tests, Up: Using DejaGnu 1311 13122.9.1.1 Increasing Verbosity 1313............................ 1314 1315If you encounter a problem with a test, increasing the verbosity may 1316make the issue easier to spot. Additional details are visible when 1317_RUNTESTFLAGS_ are used to add the _verbose_ and _all_ options. The 1318`verbose' option prints more information about the testing process, 1319while the `all' option includes details on passing tests. 1320 1321 1322 make check RUNTESTFLAGS="-v -a" 1323 1324 1325File: gnash_ref.info, Node: Running Some Tests, Prev: Increasing Verbosity, Up: Using DejaGnu 1326 13272.9.1.2 Running Some Tests 1328.......................... 1329 1330It is possible to run just a single test, or a subdirectory of tests, 1331by specifying the directory or compiled test file. 1332 1333 Some tests rely on _testsuite/Dejagnu.swf_, which in turn relies on 1334_Ming_. This file is created when you run `make check' for the entire 1335testsuite, and can also be created on demand: 1336 1337 1338 make -C testsuite Dejagnu.swf 1339 1340 In this example, the `clip_as_button2' test is compiled and run: 1341 1342 1343 make -C testsuite/samples clip_as_button2-TestRunner 1344 cd testsuite/samples && ./clip_as_button2-TestRunner 1345 1346This creates and runs all the tests in the directory `movies.all': 1347 1348 1349 make -C testsuite/movies.all check 1350 1351 1352File: gnash_ref.info, Node: Running The Tests Manually, Next: Installation, Prev: Using DejaGnu, Up: Running the Tests 1353 13542.9.2 Running The Tests Manually 1355-------------------------------- 1356 1357You may also run test cases by hand, which can be useful if you want to 1358see all the debugging output from the test case. Often the messages 1359which come from deep within Gnash are most useful for development. 1360 1361 The first step is to compile the test case, which can be done with 1362`make XML-v#.swf' where the '#' is replaced with the _target_ SWF 1363version or versions. For example: 1364 1365 1366 make XML-v{5,6,7,8}.swf 1367 1368* Menu: 1369 1370* Movie tests:: 1371* ActionScript Unit Tests:: 1372 1373 1374File: gnash_ref.info, Node: Movie tests, Next: ActionScript Unit Tests, Up: Running The Tests Manually 1375 13762.9.2.1 Movie tests 1377................... 1378 1379This creates a Flash movie version of the test case, which can be run 1380with a standalone Flash player. For instance, the target for SWF 1381version 6 could be run with Gnash: 1382 1383 1384 gnash -v XML-v6.swf 1385 1386 1387File: gnash_ref.info, Node: ActionScript Unit Tests, Prev: Movie tests, Up: Running The Tests Manually 1388 13892.9.2.2 ActionScript Unit Tests 1390............................... 1391 1392Unit tests for ActionScript classes in `testsuite/actionscript.all' are 1393run without a graphical display: 1394 1395 1396 gprocessor -v XML-v6.swf 1397 1398 1399File: gnash_ref.info, Node: Installation, Next: Cross Configuring, Prev: Running The Tests Manually, Up: Running the Tests 1400 14012.9.3 Installation 1402------------------ 1403 1404Now that Gnash has been compiled and tested, use the following command 1405to install it: 1406 1407 1408 make install 1409 1410The above command installs the standalone player. If the correct files 1411were found by `configure' and if the `--disable-plugin' option was not 1412specified, the Gnash browser plugin is also installed. 1413 1414 Gnash installs a number of libraries (*note Libraries::), namely: 1415_libbase_, _libgeometry_, _libbackend_, _libserver_, and _libmozsdk_. 1416Executables (*note Executables::) consist of the (optional) plugin, 1417`gprocessor', `cygnal', and `gnash'. Documentation (*note 1418Documentation::) may also be installed. The installation location is 1419controlled with the _-prefix_ configure option (*note Specifying Custom 1420Paths::), except for plugins, which are explicitly set with 1421_-plugin-dir_. 1422 1423 Note that if you are using a single file-system _NFS_ mounted to 1424multiple platforms, the configuration option (*note Specifying Custom 1425Paths::) _-exec-prefix_ may be used to specify where platform-dependent 1426executables and libraries are installed. 1427 1428* Menu: 1429 1430* Libraries:: 1431* Executables:: 1432* Documentation:: 1433 1434 1435File: gnash_ref.info, Node: Libraries, Next: Executables, Up: Installation 1436 14372.9.3.1 Libraries 1438................. 1439 1440Installed libraries are located in `/usr/local/lib' by default. If the 1441_-prefix_ option was used in [Cross reference to non-existant ID 1442"pre-configuration"], the libraries will be installed in the directory 1443`lib' inside the path you specified. If the libraries are stored in a 1444non-standard location, you must identify the path in one of two ways. 1445 1446 The traditional way to do this on UNIX platforms is to set the 1447_LD_LIBRARY_PATH_ variable to the path plus `/lib'. For example, if you 1448installed in `/home/gnash', the _LD_LIBRARY_PATH_ path would be 1449`/home/gnash/lib'. Multiple paths are delimited with a colon (':'). 1450 1451 GNU/Linux allows the custom path to be added to `/etc/ld.so.conf'. 1452After adding the path, run _ldconfig_ as root to update the runtime 1453cache. 1454 1455 1456File: gnash_ref.info, Node: Executables, Next: Documentation, Prev: Libraries, Up: Installation 1457 14582.9.3.2 Executables 1459................... 1460 1461The Mozilla plugin is built from headers (the Mozilla SDK) provided 1462with Gnash and does not need extra development packages to be 1463installed. By default, the plugin is installed to 1464`~/.mozilla/plugins/'. To enable the plugin for other users, copy the 1465file `libgnashplugin.so' to `.mozilla/plugins/' in their home directory. 1466You may also specify the plugin installation directory by using the 1467`--with-plugindir' option at configuration time (*note Specifying 1468Custom Paths::). 1469 1470 These defaults are likely to change in future versions of Gnash. 1471 1472 The remaining executables are installed in the `bin' subdirectory of 1473the directory specified by during configuration. If no path was 1474specified, the default is `/usr/local/bin'. 1475 1476 1477File: gnash_ref.info, Node: Documentation, Prev: Executables, Up: Installation 1478 14792.9.3.3 Documentation 1480..................... 1481 1482Documentation is not built by default; please refer to the section on 1483documentation (*note Creating the Documentation::) for more information 1484on building documentation. 1485 1486 `man' and `info' are installed in `/usr/local/share/man' and 1487`/usr/local/share/info' respectively, unless the `--mandir' or 1488`--infodir' configuration options (*note Specifying Custom Paths::) are 1489used. 1490 1491 _GNOME help_ documentation uses the directory 1492`/usr/local/share/gnash/doc/gnash/C/' by default. A configuration file 1493in the Gnash source tree, `doc/C/gnash.omf' is used to specify under 1494which menu item Gnash appears in the _GNOME help_ system. 1495 1496 1497File: gnash_ref.info, Node: Cross Configuring, Prev: Installation, Up: Running the Tests 1498 14992.9.4 Cross Configuring 1500----------------------- 1501 1502To cross configure and compile Gnash, begin by building a target system 1503on your workstation. This includes cross compilers for the target 1504architecture, and some system headers. You will also need to cross 1505compile all the [Cross reference to non-existant ID "docdepend"] 1506normally needed to build Gnash. This can on occasion be a daunting 1507process, as not libraries will cross configure and cross compile. There 1508is more information about cross compiling all the dependant packages on 1509the http://www.gnashdev.org (http://www.gnashdev.org) web site. 1510 1511 If you need to build your own tool chain, that is beyond the scope 1512of this manual. There are various resources on the web for howto's on 1513building GCC based cross toolchains. Two popular sites are 1514http://frank.harvard.edu/~coldwell/toolchain/ 1515(http://frank.harvard.edu/~coldwell/toolchain/) and 1516http://www.kegel.com/crosstool/ (http://www.kegel.com/crosstool/). This 1517can also be a very time consuming and frustrating process, even for 1518experienced developers. 1519 1520 Because the process of building your own cross tool chain can be 1521harder than one may wish, there are several other cross development 1522environments that simulate a native environment to make it easier to 1523develop. These also let you develop for both native and cross builds. 1524Several popular ones are Access Linux Platform 1525(http://www.access-company.com/products/linux/alp.html), Scratchbox 1526(http://www.scratchbox.org/), Open Embedded 1527(http://www.openembedded.org/), Maemo (http://maemo.org/). 1528 1529 To build for an ARM based system on an x86 based systems, configure 1530like this using the traditional style cross toolchain, configure like 1531this: 1532 1533 1534 ../../gnash/configure --build=i686-pc-linux-gnu 1535 --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi 1536 --disable-kparts --enable-gui=fb --enable-renderer=agg 1537 --disable-shared --disable-menus 1538 1539 The important configuration options are the ones which specify the 1540architecture for the build: 1541 1542-target 1543 The target architecture, where the final executables are expected 1544 to run. 1545 1546-host 1547 The host architecture, where the executables are expected to run. 1548 Usually this is the same as the _-target_, except when building a 1549 compiler as a Canadian Cross. In this case, you might build a 1550 cross compiler on a UNIX system which runs on a win32 machine, 1551 producing code for a third architecture, such as ARM. In this 1552 example, _-target_ would be 'arm-unknown-linux-gnu', while _-host_ 1553 would be 'win32'. 1554 1555-build 1556 This is the system the build is running on. 1557 1558 The following example of _configure_ builds for an ARM system on an 1559x86 system. It was run after an ARM system was built in `/usr/arm' and 1560other required libraries were cross compiled. 1561 1562 1563 ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \ 1564 --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin 1565 1566 1567File: gnash_ref.info, Node: Software Internals, Next: Gnash Extensions, Prev: Building from Source, Up: Top 1568 15693 Software Internals 1570******************** 1571 1572* Menu: 1573 1574* A Tour of Gnash:: 1575* Sound handling in Gnash:: 1576* Testing : Testing. 1577* Adding New ActionScript Class:: 1578 1579 1580File: gnash_ref.info, Node: A Tour of Gnash, Next: Sound handling in Gnash, Up: Software Internals 1581 15823.1 A Tour of Gnash 1583=================== 1584 1585The top level of Gnash has several libraries, _libgnashbase_, 1586_libgnashgeo_, _libgnashserver_, _libgnashasobjs_ and 1587_libgnashbackend_. There are several utility programs included for 1588debug parsing and processing of Flash movie files, and other useful 1589utilitis for examining local Shared Objects and sniffingh 1590LocalConnections. 1591 1592* Menu: 1593 1594* The Libraries:: 1595* The Applications:: 1596* The Plugin:: 1597* The Debug Logging System:: 1598 1599 1600File: gnash_ref.info, Node: The Libraries, Next: The Applications, Up: A Tour of Gnash 1601 16023.1.1 The Libraries 1603------------------- 1604 1605* Menu: 1606 1607* libgnashbase:: 1608* libgnashgeo:: 1609* libgnashgui:: 1610* libgnashserver:: 1611* libgnashasobjs:: 1612* libgnashamf:: 1613* libgnashbackend:: 1614* libgnashplugin:: 1615* libklashpart:: 1616 1617 1618File: gnash_ref.info, Node: libgnashbase, Next: libgnashgeo, Up: The Libraries 1619 16203.1.1.1 libgnashbase 1621.................... 1622 1623Libgnashbase contains support classes used by the rest of the code.This 1624library has no dependencies on any of the other Gnash libraries. 1625 1626 Gnash makes heavy use of smart pointers, so memory allocations are 1627freed up automatically by the interpreter. Both STL and Boost smart 1628pointers are used. 1629 1630 1631File: gnash_ref.info, Node: libgnashgeo, Next: libgnashgui, Prev: libgnashbase, Up: The Libraries 1632 16333.1.1.2 libgnashgeo 1634................... 1635 1636Libgnashgeo contains code for device independent graphics routines. 1637 1638 1639File: gnash_ref.info, Node: libgnashgui, Next: libgnashserver, Prev: libgnashgeo, Up: The Libraries 1640 16413.1.1.3 libgnashgui 1642................... 1643 1644Libgnashgui contains code for a portable GUI class that supports using 1645GTK2, a framebuffer, SDL, or KDE, FLTK, or Aqua. 1646 1647 1648File: gnash_ref.info, Node: libgnashserver, Next: libgnashasobjs, Prev: libgnashgui, Up: The Libraries 1649 16503.1.1.4 libgnashserver 1651...................... 1652 1653Libgnashserver is the guts of the interpreter itself. This is where the 1654main code for the interpreter lives. Includes in libserver are the two 1655support libraries for the parser and the core of the virtual machine. 1656 1657 1658File: gnash_ref.info, Node: libgnashasobjs, Next: libgnashamf, Prev: libgnashserver, Up: The Libraries 1659 16603.1.1.5 libgnashasobjs 1661...................... 1662 1663Libgnashasobjs contains all the ActionScript classes used by the 1664interpreter. 1665 1666 1667File: gnash_ref.info, Node: libgnashamf, Next: libgnashbackend, Prev: libgnashasobjs, Up: The Libraries 1668 16693.1.1.6 libgnashamf 1670................... 1671 1672AMF is the data format used internally by SWF files. This is Gnash's 1673support library to handle AMF data. This is used by the ActionScript 1674classes SharedObject and LocalConnection. This is also used by the 1675NetStream class when using thre RTMP streaming network protocol. 1676 1677 1678File: gnash_ref.info, Node: libgnashbackend, Next: libgnashplugin, Prev: libgnashamf, Up: The Libraries 1679 16803.1.1.7 libgnashbackend 1681....................... 1682 1683Libgnashbackend is a library containing the rendering code that glues 1684this display to the Gnash. Supported rendering backends are OpenGL, 1685Cairo, and AGG. 1686 1687 1688File: gnash_ref.info, Node: libgnashplugin, Next: libklashpart, Prev: libgnashbackend, Up: The Libraries 1689 16903.1.1.8 libgnashplugin 1691...................... 1692 1693Libgnashplugin is the Mozilla/Firefox plugin. 1694 1695 1696File: gnash_ref.info, Node: libklashpart, Prev: libgnashplugin, Up: The Libraries 1697 16983.1.1.9 libklashpart 1699.................... 1700 1701Libklashpart is the Konqueror plugin. 1702 1703 1704File: gnash_ref.info, Node: The Applications, Next: The Plugin, Prev: The Libraries, Up: A Tour of Gnash 1705 17063.1.2 The Applications 1707---------------------- 1708 1709There are currently a few standalone programs in Gnash, which serve to 1710either assist with Gnash development or play flash movies. 1711 1712* Menu: 1713 1714* The Standalone Player:: 1715* Gprocesser:: 1716* SOLdumper:: 1717* Dumpshm:: 1718 1719 1720File: gnash_ref.info, Node: The Standalone Player, Next: Gprocesser, Up: The Applications 1721 17223.1.2.1 The Standalone Player 1723............................. 1724 1725This is the standalone OpenGL back-end used to play movies. There are 1726several command-line options and keyboard control keys used by Gnash. 1727 1728 1729File: gnash_ref.info, Node: Gprocesser, Next: SOLdumper, Prev: The Standalone Player, Up: The Applications 1730 17313.1.2.2 Gprocesser 1732.................. 1733 1734Gprocesser is used to print out the actions (using the -va option) or 1735the parsing (using the -vp option) of a flash movie. It is also used to 1736produce the _.gsc_ files that Gnash uses to cache data, thereby 1737speeding up the loading of files. 1738 1739 1740File: gnash_ref.info, Node: SOLdumper, Next: Dumpshm, Prev: Gprocesser, Up: The Applications 1741 17423.1.2.3 SOLdumper 1743................. 1744 1745SOLDumper is a utility program used to find and dump the content of 1746_Local Shared Objects_, also called "Flash Cookies" by some. 1747 1748 1749File: gnash_ref.info, Node: Dumpshm, Prev: SOLdumper, Up: The Applications 1750 17513.1.2.4 Dumpshm 1752............... 1753 1754Dumpshm is a program used to find and dump the contents of the 1755_LocalConnection_ shared memory segment. 1756 1757 1758File: gnash_ref.info, Node: The Plugin, Next: The Debug Logging System, Prev: The Applications, Up: A Tour of Gnash 1759 17603.1.3 The Plugin 1761---------------- 1762 1763The plugin is designed to work within Mozilla or Firefox, although 1764there is Konqueror support as well. The plugin uses the Mozilla NSAPI 1765plugin API to be cross platform, and is portable, as well as being well 1766integrated into Mozilla based browsers. 1767 1768* Menu: 1769 1770* Current Status:: 1771* GUI Support:: 1772* Mozplugger:: 1773* Klash:: 1774 1775 1776File: gnash_ref.info, Node: Current Status, Next: GUI Support, Up: The Plugin 1777 17783.1.3.1 Current Status 1779...................... 1780 1781As of March 30, 2006, the plugin works! This works in a fashion similar 1782to MozPlugger in that the standalone player is used instead of using a 1783thread. This gets around the issue of having to maintain a separate 1784player to support the plugin. It also gets around the other issues that 1785Gnash itself is not thread safe at this time. 1786 1787 As of Jan, 2007, streaming video, ala "YouTube" works, along with 1788other video sharing sites. 1789 1790 1791File: gnash_ref.info, Node: GUI Support, Next: Mozplugger, Prev: Current Status, Up: The Plugin 1792 17933.1.3.2 GUI Support 1794................... 1795 1796Any plugin that wants to display in a browser window needs to be tied 1797into the windowing system of the platform being used. On GNU/Linux 1798systems, Firefox is a GTK2+ application. There is also KDE support 1799through the use of the Klash plugin. 1800 1801 Gnash can use either several different GUI toolkits to create the 1802window, and to handle events for the standalone player. 1803 1804 The SDL version is more limited, but runs on all platforms, 1805including win32. It has no support for event handling, which means 1806mouse clicks, keyboard presses, and window resizing doesn't work. I 1807personally find the default event handler slow and unresponsive. Gnash 1808has support to use fast events, (currently not enabled) which is an SDL 1809hack using a background thread to pump events into the SDL event queue 1810at a much higher rate. 1811 1812 There are a variety of development libraries that build a GUI widget 1813system on top of SDL and OpenGL. The use of these to add menus and 1814dialog boxes to the SDL version is being considered. 1815 1816 The GTK support is currently the most functional, and the best 1817integrated into Firefox. The performance of this version is better than 1818the SDL version because of the more efficient event handling within 1819GTK. For the best end user experience, use the GTK enabled version. 1820 1821 GTK also allows Gnash to have menus and dialog boxes. Currently this 1822is only being utilized in a limited fashion for now. There is a right 1823mouse button menu that allows the user to control the movie being 1824player the same way the existing keyboard commands do. 1825 1826 1827File: gnash_ref.info, Node: Mozplugger, Next: Klash, Prev: GUI Support, Up: The Plugin 1828 18293.1.3.3 Mozplugger 1830.................. 1831 1832Mozplugger (http://mozplugger.mozdev.org/) is a _Mozilla/Firefox_ 1833plugin that uses external programs to play video, audio, and other 1834multimedia content in the browser. With some support added to the 1835external application, it's possible to force the external program to 1836use the internal window in the browser where this plugin is supposed to 1837display. This enables one to then run the standalone player and display 1838its output in the browser. 1839 1840 While this is not an optimal solution, it does enable one to use 1841Gnash as the flash player when browsing. The main issue appears to be 1842that the Flash movie being played doesn't get any mouse or keyboard 1843input. That may be a mozplugger configuration issue, however. 1844 1845 Use of MozPlugger is obsolete now that the Gnash plugin works. 1846Still, this may be useful still on some platforms. 1847 1848 Add this to your _$(HOME)/.mozilla/mozpluggerrc_ file to enable this: 1849 1850 1851 application/x-shockwave-flash:swf:Shockwave Gnash 1852 nokill embed noisy ignore_errors hidden fill swallow(Gnash) loop: gnash -v "$file" -x $window 1853 : gnash -v "$file" -x $window 1854 1855 Once this is added, you must delete the 1856_$(HOME)/.mozilla/firefox/pluginreg.dat_ file to force Firefox to 1857register the plugins again. This is an ASCII text file, so if the patch 1858has been added correctly, you'll see an entry for _swf_ files after it 1859is recreated. You will need to restart Firefox to recreate this file. 1860 1861 This file is not recreated immediately when restarting Firefox, but 1862waits till the first time a plugin is used. You can force creation of 1863this file by typing _about:plugins_ into the URL entry of the browser 1864window. The output will also contain information about the mozplugger. 1865You should see an entry for Gnash now. 1866 1867 1868File: gnash_ref.info, Node: Klash, Prev: Mozplugger, Up: The Plugin 1869 18703.1.3.4 Klash 1871............. 1872 1873Klash is MozPlugger type support for KDE's Konqueror web browser. Klash 1874makes Gnash a _kpart_, so it's integrated into KDE better than when 1875using MozPlugger. Klash uses the standalone player, utilizing Gnash's 1876"-x" window plugin command line option. 1877 1878 By default, Klash is not built. To enable building Klash, use the 1879_-enable-klash_ option when configuring. Other than installing, there 1880is nothing else that needs to be done to install Klash. 1881 1882 1883File: gnash_ref.info, Node: The Debug Logging System, Prev: The Plugin, Up: A Tour of Gnash 1884 18853.1.4 The Debug Logging System 1886------------------------------ 1887 1888Gnash supports a debug logging system which supports both C and C++ 1889natively. This means you can use both _printf()_ style debug messages 1890and C++ _iostreams_ style, where you can print C++ objects directly as 1891you would when using _cout_. 1892 1893 In the beginning, Gnash only supported the C API for debug logging, 1894so it is the most heavily used in Gnash. This API was used in the 1895_log_msg()_ and _log_error()_ functions, and used a callback to set 1896them up. 1897 1898 If a filename is not specified at object construction time, a 1899default name of _gnash-dbg.log_ is used. If Gnash is started from the 1900command line, the debug log will be created in the current directory. 1901When executing Gnash from a launcher under _GNOME_ or _KDE_ the debug 1902file goes in your home directory, since that's considered the current 1903directory. 1904 1905 There is common functionality between using the C or C++ API. 1906Optional output is based on flags that can be set or unset. Multiple 1907levels of verbosity are supported, so you can get more output by 1908supplying multiple _-v_ options on the command line. You can also 1909disable the creation of the debug log. 1910 1911 Currently the use of the C++ API for logging is discouraged, do to 1912performance issues.and the generic log_msg() has been replaced by more 1913spcific function calls to allow more control of what gets displayed and 1914logged. 1915 1916* Menu: 1917 1918* Logging System C API:: 1919* Logging System C++ API:: 1920 1921 1922File: gnash_ref.info, Node: Logging System C API, Next: Logging System C++ API, Up: The Debug Logging System 1923 19243.1.4.1 Logging System C API 1925............................ 1926 1927These functions are clones of the originals as they were used for 1928Gnash. These function the same as always except output can be logged to 1929disk now as well. These currently print no timestamp with the output, 1930which is the older functionality. As these functions are implemented on 1931top of the C++ API now, they can be used without corrupting the output 1932buffers. 1933 1934log_error(const char* fmt, ...) 1935 Display an error message if verbose output is enabled. By default 1936 the error messages are always written to the disk file, but 1937 optionally displayed in the terminal. 1938 1939void log_unimpl 1940 Displays a warning to the user about missing Gnash features. We 1941 expect all calls to this function to disappear over time, as we 1942 implement those features of Flash. 1943 1944void log_trace 1945 Used only for explicit user traces 1946 1947void log_debug 1948 Logs debug information. 1949 1950void log_action 1951 Log action execution information. Wrap all calls to this function 1952 (and other related statements) into an IF_VERBOSE_ACTION macro, so 1953 to allow completely removing all the overhead at compile time and 1954 reduce it at runtime. 1955 1956void log_parse 1957 Log SWF parsing Wrap all calls to this function (and other 1958 related statements) into an IF_VERBOSE_PARSE macro, so to allow 1959 completely removing all the overhead at compile time and reduce it 1960 at runtime. 1961 1962void log_security 1963 Display a message with security related information. 1964 1965void log_swferror 1966 This indicates an error in how the binary SWF file was 1967 constructed, i.e.probably a bug in the tools used to build the SWF 1968 file. Wrap all calls to this function (and other related 1969 statements) into an IF_VERBOSE_MALFORMED_SWF macro, so to allow 1970 completely removing all the overhead at compile time and reduce it 1971 at runtime. 1972 1973log_warning(const char* fmt, ...) 1974 Display a warning message if verbose output is enabled. By default 1975 the error messages are always written to the disk file, but 1976 optionally displayed in the terminal. 1977 1978 1979File: gnash_ref.info, Node: Logging System C++ API, Prev: Logging System C API, Up: The Debug Logging System 1980 19813.1.4.2 Logging System C++ API 1982.............................. 1983 1984This is the new C++ streams based API that can be used to print C++ 1985objects natively. All output lines are timestamped. 1986 1987 There are two macros used for program tracing. these can be used in 1988both C or C++ code with one little difference. Since C doesn't have 1989destructors, you must call _GNASH_REPORT_RETURN_ at the end of a 1990function to display the function returning message. 1991 1992GNASH_REPORT_FUNCTION; 1993 When this is included in a C++ method, a message is printed when 1994 entering and exiting this method by hooking into the constructor 1995 and destructor. These are always written to the disk file, but 1996 optionally written to the screen only at the highest levels of 1997 verbosity. 1998 1999GNASH_REPORT_RETURN; 2000 This is used by C functions to print the returning from function 2001 debug message. For C++, this macro is executed automatically by 2002 the destructor. 2003 2004 This is the main API for the logging system. By default everything 2005is setup to write to the default _gnash-dbg.log_ file whenever a 2006verbose option is supplied. Optionally it is possible to open a log 2007file with a specified name, allowing multiple output files. 2008 2009closeLog(void) 2010 Close a debug log. The disk file remains. 2011 2012removeLog(void) 2013 Delete the debug log file from disk. 2014 2015setVerbosity(void) 2016 Increment the verbosity level. 2017 2018setVerbosity(int) 2019 Set the verbosity level. 2020 2021setStamp(bool flag) 2022 If _flag_ is _true_, then print a timestamp prefixed to every 2023 output line. If _flag_ is _false_, then don't print a timestamp. 2024 2025setWriteDisk(bool flag) 2026 If _flag_ is _true_, then create the disk file. If _flag_ is 2027 _false_, then don't create the disk file. 2028 2029 2030File: gnash_ref.info, Node: Sound handling in Gnash, Next: Testing, Prev: A Tour of Gnash, Up: Software Internals 2031 20323.2 Sound handling in Gnash 2033=========================== 2034 2035When a SWF-file contains audio Gnash uses its sound handlers to play it. 2036At the moment there are two sound handlers, but it is likely that more 2037will be made. 2038 2039 There are two different settings related to sound support: _[Cross 2040reference to non-existant ID "pluginsound"]_ and _[Cross reference to 2041non-existant ID "standalonesound"]_. This was done in order to allow 2042the plugin to be independently configured, for instance to block sound 2043from advertisements. 2044 2045* Menu: 2046 2047* Sound types:: 2048* Sound parsing:: 2049* Sound playback:: 2050* The SDL sound backend:: 2051* The Gstreamer backend:: 2052* Future audio backends:: 2053* Detailed description of the Gstreamer backend:: 2054 2055 2056File: gnash_ref.info, Node: Sound types, Next: Sound parsing, Up: Sound handling in Gnash 2057 20583.2.1 Sound types 2059----------------- 2060 2061Sounds can be divided into two groups: event-sounds and soundstreams. 2062Event-sounds are contained in a single SWF frame, but the playtime can 2063span multiple frames. Soundstreams can be (and normally are) divided 2064between the SWF frames the soundstreams spans. This means that if a 2065gotoframe-action jumps to a frame which contains data for a soundstream, 2066playback of the stream can be picked up from there. 2067 2068 2069File: gnash_ref.info, Node: Sound parsing, Next: Sound playback, Prev: Sound types, Up: Sound handling in Gnash 2070 20713.2.2 Sound parsing 2072------------------- 2073 2074When Gnash parses a SWF-file, it creates a sound handler if possible 2075and hands over the sounds to it. Since the event-sounds are contained 2076in one frame, the entire event-sound is retrieved at once, while a 2077soundstream maybe not be completely retrieved before the entire 2078SWF-file has been parsed. But since the entire soundstream doesn't need 2079to be present when playback starts, it is not necessary to wait. 2080 2081 2082File: gnash_ref.info, Node: Sound playback, Next: The SDL sound backend, Prev: Sound parsing, Up: Sound handling in Gnash 2083 20843.2.3 Sound playback 2085-------------------- 2086 2087When a sound is about to be played Gnash calls the sound handler, which 2088then starts to play the sound and return. All the playing is done by 2089threads (in both SDL and Gstreamer), so once started the audio and 2090graphics are not sync'ed with each other, which means that we have to 2091trust both the graphic backend and the audio backend to play at correct 2092speed. 2093 2094 2095File: gnash_ref.info, Node: The SDL sound backend, Next: The Gstreamer backend, Prev: Sound playback, Up: Sound handling in Gnash 2096 20973.2.4 The SDL sound backend 2098--------------------------- 2099 2100The current SDL sound backend has replaced the original sound handler, 2101based on SDL_mixer, which by design had some limitations, making it 2102difficult to implement needed features such as support for soundstreams. 2103The SDL sound backend supports both event-sounds and soundstreams, 2104using Gnash's internal ADPCM, and optionally MP3 support, using either 2105FFMPEG or LIBMAD. When it receives sound data it is stored without 2106being decoded, unless it is ADPCM, which is decoded in the parser. When 2107playing, backend relies on a function callback for retrieving output 2108sound, which is decoded and re-sampled if needed, and all sound output 2109is mixed together. The current SDL sound backend was made since Gnash 2110needed a working sound backend as soon as possible, and since the 2111gstreamer backend at the time suffered from bugs and/or lack of 2112features in gstreamer. The result was the most complete and best sound 2113handler so far. The advantages of the SDL sound handler is speed, and 2114ease of use, while its only real disadvantage is that it has to be 2115compiled with MP3 support, which some Linux distributions will probably 2116not like... 2117 2118 2119File: gnash_ref.info, Node: The Gstreamer backend, Next: Future audio backends, Prev: The SDL sound backend, Up: Sound handling in Gnash 2120 21213.2.5 The Gstreamer backend 2122--------------------------- 2123 2124The Gstreamer backend, though not complete, supports both soundstreams 2125and event-sounds. When receiving sound data it stores it compressed, 2126unless if it's ADPCM event-sounds, which it decodes by the parser. 2127When the playback starts, the backend sets up a Gstreamer bin 2128containing a decoder (and other things needed) and places it in a 2129Gstreamer pipeline, which plays the audio. All the sound data is not 2130passed at once, but in small chunks, and via callbacks the pipeline 2131gets fed. The advantages of the Gstreamer backend is that it supports 2132both kinds of sound, it avoids all the legal MP3-stuff, and it should 2133be relatively easy to add VORBIS support. The drawbacks are that it has 2134longer "reply delay" when starting the playback of a sound, and it 2135suffers under some bugs in Gstreamer that are yet to be fixed. 2136 2137 2138File: gnash_ref.info, Node: Future audio backends, Next: Detailed description of the Gstreamer backend, Prev: The Gstreamer backend, Up: Sound handling in Gnash 2139 21403.2.6 Future audio backends 2141--------------------------- 2142 2143It would probably be desirable to make more backends in the future, 2144either because other and better backend systems are brought to our 2145attention, or perhaps because an internal sound handling is better 2146suited for embedded platform with limited software installed. 2147 2148 2149File: gnash_ref.info, Node: Detailed description of the Gstreamer backend, Prev: Future audio backends, Up: Sound handling in Gnash 2150 21513.2.7 Detailed description of the Gstreamer backend 2152--------------------------------------------------- 2153 2154Gstreamer uses pipelines, bins and elements. Pipelines are the main 2155bin, where all other bins or elements are places. Visually the audio 2156pipeline in Gnash looks like this: 2157 2158 2159 ___ 2160 |Bin|_ 2161 |___| \ 2162 ___ \ _____ ____________ 2163 |Bin|___|Adder|_____|Audio output| 2164 |___| |_____| |____________| 2165 ___ / 2166 |Bin|_/ 2167 |___| 2168 2169 There is one bin for each sound which is being played. If a sound is 2170played more the once at the same time, multiple bins will be made. The 2171bins contains: 2172 2173 2174 2175 |source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume| 2176 2177 In the source element we place parts of the undecoded sound data, and 2178when playing the pipeline will pull the data from the element. Via 2179callbacks it is refilled if needed. In the capsfilter the data is 2180labeled with the format of the data. The decoder (surprise!) decodes 2181the data. The audioconverter converts the now raw sound data into a 2182format accepted by the adder, all input to the adder must in the same 2183format. The audio re-sampler re-samples the raw sound data into a sample 2184accepted by the adder, all input to the adder must in the same sample 2185rate. The volume element makes it possible to control the volume of 2186each sound. 2187 2188 When a sound is done being played it emits a End-Of-Stream-signal 2189(EOS), which is caught by an event-handler-callback, which then makes 2190sure that the bin in question is removed from the pipeline. When a 2191sound is told by Gnash to stop playback before it has ended playback, 2192we do something (not yet finally implemented), which makes the bin emit 2193an EOS, and the event-handler-callback will remove the sound from the 2194pipeline. Unfortunately Gstreamer currently has a bug which causes the 2195entire pipeline to stop playing when unlinking an element from the 2196pipeline; so far no fix is known. 2197 2198 Gstreamer also contains a bug concerning linking multiple elements to 2199the adder in rapid succession, which causes to adder to "die" and stop 2200the playback. 2201 2202 2203File: gnash_ref.info, Node: Testing, Next: Adding New ActionScript Class, Prev: Sound handling in Gnash, Up: Software Internals 2204 22053.3 Testing 2206=========== 2207 2208Instructions on running tests (*note Running the Tests::) can be found 2209in the section on building Gnash. 2210 2211* Menu: 2212 2213* Testing Tools:: 2214* Test Cases:: 2215* Writing ActionScript Tests:: 2216* Writing Ming-based self-contained SWF tests:: 2217* Writing self-contained SWF tests with other compilers:: 2218* Writing Test Runners:: 2219 2220 2221File: gnash_ref.info, Node: Testing Tools, Next: Test Cases, Up: Testing 2222 22233.3.1 Testing Tools 2224------------------- 2225 2226Currently Gnash uses three other tools to help with testing. Two of 2227these are free compilers for the Flash format. This lets us write 2228simple test cases for Gnash to test specific features, and to see how 2229the features operate. 2230 2231 The primary compiler used at this time is Ming (http://ming.sf.net). 2232Since release 0.3, _Ming_ includes a command-line compiler, _makeswf_. 2233This allows test case development to be done entirely with free tools. 2234 2235 The other tools are optional. DejaGnu 2236(http://www.gnu.org/software/dejagnu) is used to run multiple test 2237cases in an automated manner. _DejaGnu_ is used by many other GNU 2238(http://www.gnu.org) projects like GCC (http://gcc.gnu.org) and Samba 2239(http://www.samba.org). 2240 2241 2242File: gnash_ref.info, Node: Test Cases, Next: Writing ActionScript Tests, Prev: Testing Tools, Up: Testing 2243 22443.3.2 Test Cases 2245---------------- 2246 2247ActionScript test cases are located under testsuite/actionscript.all/; 2248these are organized in one file for the ActionScript class. Other 2249Ming-generated tests are under testsuite/ming-misc.all/; these are 2250typically used to test specific tag types. Full movies are located in 2251testsuite/movies.all/ and sample movies are found in testsuite/samples/. 2252Other directories in testsuite/ are (or shall be) used for other kind 2253of tests. 2254 2255 2256File: gnash_ref.info, Node: Writing ActionScript Tests, Next: Writing Ming-based self-contained SWF tests, Prev: Test Cases, Up: Testing 2257 22583.3.3 Writing ActionScript Tests 2259-------------------------------- 2260 2261Writing ActionScript tests is very simple. The _makeswf_ compiler makes 2262use of the C preprocessor, thus allowing the inclusion of definitions 2263for macros and external files. We use these feature to provide common 2264utilities for test units. 2265 2266 Each test unit sets an _rcsid_ variable, includes the _check.as_ 2267file and performs some checks using the provided macros. Here is an 2268example: 2269 2270 2271 2272 // This variable will be used by check.as 2273 // to show testcase info as part of the test runs. 2274 rcsid="Name and version of this testcase, usually the RCS id"; 2275 2276 #include "check.as" 2277 2278 // Test object creation 2279 check(new Object() instanceOf Object); 2280 2281 // Test parseInt 2282 check(isNaN(parseInt('none'))); 2283 2284 // Test assignment 2285 var a = 1; 2286 check_equals(a, 1); 2287 2288 // .. your tests here ... 2289 2290 The check(expr) macro will _trace_ PASSED or FAILED together with 2291the expression being evaluated and the line number of the check. This 2292is the format expected by DejaGnu. 2293 2294 The _check_equals(obtained, expected)_ macro uses equality operator 2295_==_ to check for equality. When possible, use of the _check_equals()_ 2296macro is preferred over _check()_ because it shows what the actual 2297result was in case of a failure. 2298 2299 Additionally, the check.as file provides a transparent way to send 2300results to a TextField rather then using trace. This is very useful 2301when you use a flash player without tracing support. 2302 2303 Test units are built by running _make TestName-v#.swf_. This will 2304use TestName.as as source and the value of # as target version. 2305Allowed target version are from 5 to 8 (inclusive). 2306 2307 Note that if you get a syntax error from the compiler, the line 2308number will refer to the pre-processed file. This file is called 2309_TestName.as.pp_ or _TestName-v#.swf.frame#.pp_ (depending on Ming 2310version) and it's not thrown away by _makeswf_ to make debugging easier. 2311 2312 Sometimes an expression is only supported by a specific SWF version, 2313or it's evaluated differently by different SWF versions. For this 2314purpose the framework provides an OUTPUT_VERSION macro that you can use 2315to switch code based on output version. For example: 2316 2317 2318 2319 #if OUTPUT_VERSION >= 7 2320 check(_root.getSWFVersion == OUTPUT_VERSION); 2321 #endif 2322 2323 2324File: gnash_ref.info, Node: Writing Ming-based self-contained SWF tests, Next: Writing self-contained SWF tests with other compilers, Prev: Writing ActionScript Tests, Up: Testing 2325 23263.3.4 Writing Ming-based self-contained SWF tests 2327------------------------------------------------- 2328 2329Ming-based test cases are located in testsuite/misc-ming.all and 2330contain a test generator and a test runner. The test generator 2331(usually a C program) is used to produce the SWF file, while the test 2332runner (a C++ program) will run it using a MovieTester class. Note 2333that only the test generator needs Ming, not the test runner, so if 2334Ming isn't installed on the user's host, the test cases can still be 2335run as long as SWF has been distributed. 2336 2337 Producing tests using Ming has the advantage that you can easily see 2338and modify the full source code for the SWF movie, and you can use some 2339facilities (*note Using Ming-based test generators facilities::) 2340provided by the Gnash testing framework to easily run tests. 2341 2342 For generic Ming API documentation, see http://www.libming.org 2343(http://www.libming.org/). 2344 2345* Menu: 2346 2347* Using Ming-based test generators facilities:: 2348 2349 2350File: gnash_ref.info, Node: Using Ming-based test generators facilities, Up: Writing Ming-based self-contained SWF tests 2351 23523.3.4.1 Using Ming-based test generators facilities 2353................................................... 2354 2355Ming-based test generator facilities, which might be moved into a 2356loadable SWF in the future, can be currently used by your test 2357generator by including the ming_utils.h file and calling the 2358appropriate functions. 2359 2360 The most useful facility provided for Ming-based SWF test generators 2361is a Dejagnu-like TestState ActionScript class. In order to use this 2362facility you must call 'add_dejagnu_functions()' right after Movie 2363creation. The function takes an SWFMovie object and some parameters 2364specifying depth and location of the "visual" trace textfield; it 2365instantiates a global 'TestState' ActionScript object to keep track of 2366test's state. 2367 2368 You will _not_ need to directly invoke the TestState object created 2369by the 'add_dejagnu_functions()' routine, rather you will be using C 2370macros hiding its complexity: 2371 2372 2373 2374 check(SWFMovie mo, const char* expr) 2375 2376 Evaluate an ActionScript expression. 2377 2378 xcheck(SWFMovie mo, const char* expr) 2379 2380 Evaluate an ActionScript expression. 2381 A failure is expected 2382 (for cases where the call exposes a known bug). 2383 2384 check_equals(SWFMovie mo, const char* obtained, const char* expected) 2385 2386 Evaluate an ActionScript expression against an expected output. 2387 2388 xcheck_equals(SWFMovie mo, const char* obtained, const char* expected) 2389 2390 Evaluate an ActionScript expression against an expected output. 2391 A failure is expected (for cases where the call exposes a known bug). 2392 2393 print_tests_summary(SWFMovie mo) 2394 2395 This will print a summary of tests run, and should be 2396 called as the last step in your SWF generator. 2397 2398 Test cases generated using Ming and the provided facilities (*note 2399Using Ming-based test generators facilities::) will be self-contained, 2400which means they can be used as tests by simply running them with 2401whatever Player you might have. Any 'check' or 'check_equals' result 2402will be both traced and printed in a textfield. You can use 'gprocessor 2403-v' to have Gnash use them as tests. 2404 2405 See section Writing Test Runners (*note Writing Test Runners::) for 2406information about writing SWF test runners. 2407 2408 2409File: gnash_ref.info, Node: Writing self-contained SWF tests with other compilers, Next: Writing Test Runners, Prev: Writing Ming-based self-contained SWF tests, Up: Testing 2410 24113.3.5 Writing self-contained SWF tests with other compilers 2412----------------------------------------------------------- 2413 2414If you want/need to use a different compiler for your test cases 2415(there's plenty of open source tools for generating SWF out there), you 2416can still make use of a loadable SWF utility provided as part of the 2417Gnash testsuite to let your test consistent with the rest of the suite. 2418 2419 The loadable module is called Dejagnu.swf and is built during make 2420check under testsuite/misc-ming.all. In order to use it you will need 2421to load it into your SWF. We currently load it with an IMPORT tag for 2422our ActionScript based test cases, but you can probably also use 2423loadMovie or whatever works in the target SWF you're generating. Just 2424make sure that the module is initialized before using it. You can check 2425this by inspecting the dejagnu_module_initialized variable, which will 2426be set to 'true' when all initialization actions contained in the 2427Dejagnu.swf file are executed. 2428 2429 Once the module is loaded you will be able to invoke the following 2430functions, all registered against the _root sprite (effects of _lockroot 2431untested): 2432 2433 2434 2435 check(expression, [message]); 2436 2437 Evaluate the expression. 2438 Trace result (PASSED: expression / FAILED: expression). 2439 If fails, *visually* trace the failure. 2440 If second argument is given, it will be used instead of 2441 'expression' for printing results. 2442 2443 check_equals(obtained, expected) 2444 2445 Evaluate an expression against an expected output. 2446 Trace result (PASSED: obtained == expected / FAILED: expected X, obtained Y) 2447 If fails, *visually* trace the failure. 2448 2449 xcheck(expression, [message]); 2450 2451 Evaluate the expression. 2452 Trace result (XPASSED: expression / XFAILED: expression). 2453 If fails, *visually* trace the failure. 2454 If second argument is given, it will be used instead of 2455 'expression' for printing results. 2456 2457 xcheck_equals(obtained, expected) 2458 2459 Evaluate an expression against an expected output. 2460 Trace result (XPASSED: obtained == expected / XFAILED: expected X, obtained Y) 2461 If fails, *visually* trace the failure. 2462 2463 note(string) 2464 2465 Print string, both as debugging and *visual* trace. 2466 2467 totals() 2468 2469 Print a summary of tests run, both as debugging and *visual* traces. 2470 2471 Visual traces are lines of text pushed to a textarea defined by the 2472Dejagnu.swf module. The textarea is initially placed at 0, 50 and is 2473600x800 in size. You can resize/move the clip after loading it. Also, 2474you can completely make the clip invisible if that bothers you. The 2475important thing is the *debuggin* trace (call to the trace function). 2476The latter will be used by the testing framework. 2477 2478 See section Writing Test Runners (*note Writing Test Runners::) for 2479information about writing a test runners for your self-contained tests. 2480 2481 2482File: gnash_ref.info, Node: Writing Test Runners, Prev: Writing self-contained SWF tests with other compilers, Up: Testing 2483 24843.3.6 Writing Test Runners 2485-------------------------- 2486 2487Test runners are executables that run one or more tests, writing 2488results in Dejagnu form to standard output. 2489 2490 The Dejagnu form uses a standard set of labels when printing test 2491results. These are: 2492 2493Label Meaning 2494PASSED The test succeeded. 2495FAILED The test failed. 2496XPASSED The test succeeded, but was 2497 expected to fail. 2498XFAILED The test failed, and was expected 2499 to fail. 2500UNRESOLVED The results of the test could not 2501 be automatically parsed. 2502UNTESTED This test case is not complete. 2503UNSUPPORTED The test case relies on a 2504 conditional feature which is not 2505 present in your environment. 2506 2507 The following labels may also appear: 2508 2509Label Meaning 2510ERROR There was a serious error in 2511 running the test. 2512WARNING There may have been a problem with 2513 running the test. 2514NOTE There was some additional 2515 information given about the test. 2516 2517* Menu: 2518 2519* Using the generic test runner for self-contained SWF tests:: 2520* Writing Movie testers:: 2521 2522 2523File: gnash_ref.info, Node: Using the generic test runner for self-contained SWF tests, Next: Writing Movie testers, Up: Writing Test Runners 2524 25253.3.6.1 Using the generic test runner for self-contained SWF tests 2526.................................................................. 2527 2528The simplest test runner is one that simply invokes Gnash in verbose 2529mode against a self-contained SWF test movie. Self-contained SWF test 2530movies are the ones that print the PASSED/FAILED etc. lines using 2531ActionScript (traces). By invoking Gnash in verbose mode this movie 2532will behave as a compliant "Test Runner". 2533 2534 A generator for simple test runners can be found in 2535testsuite/generic-testrunner.sh. The script can be invoked by passing 2536it $(top_builddir) as the first argument and the name of the SWF file 2537(without the path) as the second argument. This will create a specific 2538runner for your test in the current build directory. A simple 2539Makefile.am rule for doing this follows: 2540 2541 2542 MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf 2543 sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf > $@ 2544 chmod +x $@ 2545 2546 By default, the generated test runner will play the movie up to the 2547last frame. If you want the movie to be played more then once (maybe 2548because you're exactly testing loop features) you can use the -r switch 2549to the generic-testrunner.sh call. The following will create a runner 2550playing the movie twice: 2551 2552 2553 MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf 2554 sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir) MyTest.swf > $@ 2555 chmod +x $@ 2556 2557 In case your test movie stops before the last frame, or you want to 2558control the exact number of times to call the frame advancement 2559routine, you can use the -f switch to control that. 2560 2561 2562 MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf 2563 sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir) MyTest.swf > $@ 2564 chmod +x $@ 2565 2566When both -f and -r are given, the first exit condition reached will 2567take effect. 2568 2569 2570File: gnash_ref.info, Node: Writing Movie testers, Prev: Using the generic test runner for self-contained SWF tests, Up: Writing Test Runners 2571 25723.3.6.2 Writing Movie testers 2573............................. 2574 2575There are some parts of Gnash that can NOT be tested by only using 2576ActionScript tests. Examples include: frame advancements, actual 2577actions execution, gui events and so on. 2578 2579 In this case you might want to use the MovieTester class to 2580implement a C++ test runner. Be aware that you can *mix* tests in the 2581MovieTester-based class with *self-contained* tests in the SWF file as 2582long as you activate verbosity for the debug logfile. This is done, for 2583example, for the DefineEditTextVariableNameTest.swf file. The 2584corresponding test runner (DefineEditTextVariableNameTest-Runner) is a 2585C++ runner based on MovieTester class. If you run the runner you see 2586two kinds of test results: the ones coming from the ActionScript 2587engine, and the ones coming from the test runner. You can distinguish 2588between the two because the former contains an additional timestamp and 2589the latter does not. Also, you'll see two final summaries for the two 2590test sets. The 'make check' rule, which uses the testsuite/simple.exp 2591output parser as its work-horse, will count test results from both test 2592sets. 2593 2594 Movie testers are executables which load an SWF, generate events 2595(both user or system) on it, and check its state using a standard 2596interface. 2597 2598 To help this process a MovieTester class is defined in the 2599testsuite/MovieTester.{h,cpp} files; see Doxygen documentation for more 2600information. 2601 2602 Note that you do NOT need access to the SWF source code in order to 2603implement a Movie tester for it. Some knowledge about the expected 2604behavior suffices. 2605 2606 2607File: gnash_ref.info, Node: Adding New ActionScript Class, Prev: Testing, Up: Software Internals 2608 26093.4 Adding New ActionScript Class 2610================================= 2611 2612In this document, the term 'ActionScript class' refers to the C++ class 2613which is instantiated by Gnash when some ActionScript code instantiates 2614a corresponding class. The C++ class stores instance data and 2615implements the methods which are called on the object in the 2616ActionScript code. 2617 2618 Adding a new ActionScript class is relatively simple, but the 2619process is complicated by the fact that the interface has evolved over 2620time and the current code base represents several different formats. 2621This document describes the current interface. The Boolean class 2622should be considered the authoritative example of a modern ActionScript 2623class. 2624 2625 ActionScript classes contain a header file and a C++ implementation. 2626The name is usually the name of the class as it is called in the 2627ActionScript specifications; for instance _Boolean.cpp_ for the Boolean 2628class. 2629 2630* Menu: 2631 2632* Prototype:: 2633* Declaration:: 2634* Instantiation:: 2635* Methods:: 2636* Dynamic Properties:: 2637* The as_value Object Type:: 2638* Object ActionScript Class:: 2639 2640 2641File: gnash_ref.info, Node: Prototype, Next: Declaration, Up: Adding New ActionScript Class 2642 26433.4.1 Prototype 2644--------------- 2645 2646In ActionScript, a prototype is a base object which contains all the 2647methods that an instantiated object will contain. In short, it 2648contains every part of the class except for the portions dealing with 2649the storage of instance data. 2650 2651 In Gnash, the prototype of an ActionScript object is implemented as 2652an _as_object_. At startup, the methods and properties of the 2653ActionScript class are attached to the _as_object_. The following 2654example demonstrates how methods can be attached: 2655 2656 2657 static void 2658 attachBooleanInterface(as_object& o) { 2659 o.init_member("toString", new builtin_function(boolean_tostring)); 2660 o.init_member("valueOf", new builtin_function(boolean_valueof)); 2661 } 2662 2663 Static properties can also be added to the ActionScript prototype 2664(dynamic properties (*note Dynamic Properties::) are addressed later). 2665They are attached in a similar way: 2666 2667 2668 o.init_member("myProperty", as_value("HelloWorld")); 2669 2670 Properties which have been added in this manner can be directly 2671accessed in ActionScript code without a function call, as this piece of 2672ActionScript code compiled by Ming's _makeswf_ compiler demonstrates: 2673 2674 2675 // Get the value of the myProperty property 2676 if (node.myProperty == "HelloWorld") { 2677 trace("MATCHED"); 2678 } 2679 2680 2681File: gnash_ref.info, Node: Declaration, Next: Instantiation, Prev: Prototype, Up: Adding New ActionScript Class 2682 26833.4.2 Declaration 2684----------------- 2685 2686A new class should derive from _as_object_, which is the base class of 2687every ActionScript object in Gnash. 2688 2689 2690File: gnash_ref.info, Node: Instantiation, Next: Methods, Prev: Declaration, Up: Adding New ActionScript Class 2691 26923.4.3 Instantiation 2693------------------- 2694 2695When a new object is needed, instance data is added to the methods and 2696properties inherited from the prototype. 2697 2698 The init method should be called in the constructor in _Global.cpp_, 2699where all other ActionScript classes are similarly referenced. This 2700method constructs a prototype, which is implemented as an _as_object_. 2701In addition, the method registers the constructor to be used for future 2702object creation, and attaches methods and properties to the prototype. 2703 2704 2705File: gnash_ref.info, Node: Methods, Next: Dynamic Properties, Prev: Instantiation, Up: Adding New ActionScript Class 2706 27073.4.4 Methods 2708------------- 2709 2710Every method you implement and attach (*note Prototype::) will receive 2711an _fn_call_ data structure as an argument when it is called. 2712 2713* Menu: 2714 2715* Accessing Arguments:: 2716* Returning a Value to ActionScript:: 2717* Additional fn_call Members:: 2718 2719 2720File: gnash_ref.info, Node: Accessing Arguments, Next: Returning a Value to ActionScript, Up: Methods 2721 27223.4.4.1 Accessing Arguments 2723........................... 2724 2725The arguments stored in _fn_call_ should be accessed using _arg()_. For 2726instance, the first element can be popped with _fn.arg(0)_. 2727 2728 The element popped off the stack is an _as_value_ object (*note The 2729as_value Object Type::). 2730 2731 2732File: gnash_ref.info, Node: Returning a Value to ActionScript, Next: Additional fn_call Members, Prev: Accessing Arguments, Up: Methods 2733 27343.4.4.2 Returning a Value to ActionScript 2735......................................... 2736 2737The return value should be an _as_value_ object (*note The as_value 2738Object Type::). For example: 2739 2740 2741 return as_value('Goodbye, cruel world.'); 2742 2743 2744File: gnash_ref.info, Node: Additional fn_call Members, Prev: Returning a Value to ActionScript, Up: Methods 2745 27463.4.4.3 Additional fn_call Members 2747.................................. 2748 2749There are two other useful members of the _fn_call_ structure, namely 2750_this_ptr_ and _nargs_. The former points to the class which is 2751invoking this method, while the latter is a count of the number of 2752arguments in the stack (*note Accessing Arguments::). 2753 2754 You may also see instances of the _env_ pointer being used. This 2755is being deprecated. Instances which could be replaced with _arg()_ 2756(*note Accessing Arguments::) are already deprecated; other uses will 2757be deprecated in the near future. 2758 2759 Beyond the _arg() (*note Accessing Arguments::)_ method, there is 2760one method of note. _dump_args()_ can be used in debugging to output 2761the entire argument stack. 2762 2763 2764File: gnash_ref.info, Node: Dynamic Properties, Next: The as_value Object Type, Prev: Methods, Up: Adding New ActionScript Class 2765 27663.4.5 Dynamic Properties 2767------------------------ 2768 2769This section describes accessors to dynamic properties. Read-only 2770properties are described in the prototype (*note Prototype::) section. 2771 2772 Accessors should be written as a single get/set method. Previously 2773this was done by overriding _get_member()_ and _set_member()_, but this 2774practice is deprecated. 2775 2776 The accessor is written so that it sets the property if it is called 2777with an argument, and puts the property in the _fn_call_ (*note 2778Methods::) result pointer (*note Returning a Value to ActionScript::). 2779For instance: 2780 2781 2782 void 2783 MyClass::myProperty_getset(const fn_call& fn) { 2784 boost::intrusive_ptr<MyClass> ptr = ensureType<MyClass>(fn.this_ptr); 2785 2786 // setter 2787 if ( fn.nargs > 0 ) { 2788 bool h = fn.arg(0).to_bool(); 2789 ptr->MyMethod(h); 2790 return; 2791 } 2792 2793 // getter 2794 bool h = ptr->MyMethod(); 2795 fn.result->set_bool(h); 2796 } 2797 2798 It has not yet been decided whether properties should be set in the 2799exported interface (*note Prototype::) or attached to instances of the 2800class. A property is attached in the following manner: 2801 2802 2803 boost::intrusive_ptr<builtin_function> gettersetter; 2804 gettersetter = new builtin_function(&MyClass::myProperty_getset, NULL); 2805 o.init_property("myProperty", *gettersetter, *gettersetter); 2806 2807 2808File: gnash_ref.info, Node: The as_value Object Type, Next: Object ActionScript Class, Prev: Dynamic Properties, Up: Adding New ActionScript Class 2809 28103.4.6 The as_value Object Type 2811------------------------------ 2812 2813The _as_value_ class is used throughout the interpreter to create 2814generic objects to hold data. 2815 2816* Menu: 2817 2818* Data Types:: 2819* Determining the Type:: 2820* Fetching the Value:: 2821* Setting the Value and Type:: 2822* Further Reading:: 2823 2824 2825File: gnash_ref.info, Node: Data Types, Next: Determining the Type, Up: The as_value Object Type 2826 28273.4.6.1 Data Types 2828.................. 2829 2830The following data types are supported: _NULLTYPE_, _BOOLEAN_, _STRING_, 2831_NUMBER_, _OBJECT_, _AS_FUNCTION_, and _MOVIECLIP_ (sprite). The type 2832_C_FUNCTION_ is being deprecated. 2833 2834 2835File: gnash_ref.info, Node: Determining the Type, Next: Fetching the Value, Prev: Data Types, Up: The as_value Object Type 2836 28373.4.6.2 Determining the Type 2838............................ 2839 2840Several methods allow you to determine if a value stored in _as_value_ 2841is of a specific type. These follow the form of _is_TYPE_, for example 2842_is_as_function()_ and _is_number()_. In general, the type names match 2843the data types (*note Data Types::) listed above, with the exception of 2844the type _MOVIECLIP_ which has a method _is_sprite()_. 2845 2846 2847File: gnash_ref.info, Node: Fetching the Value, Next: Setting the Value and Type, Prev: Determining the Type, Up: The as_value Object Type 2848 28493.4.6.3 Fetching the Value 2850.......................... 2851 2852Another set of methods will return a representation of the value as a 2853particular type. They follow the _to_TYPE_ naming convention. Examples 2854are _to_number()_ and _to_bool()_. The type names are as listed (*note 2855Data Types::) earlier, except for _MOVIECLIP_, which uses _to_sprite()_. 2856 2857 2858File: gnash_ref.info, Node: Setting the Value and Type, Next: Further Reading, Prev: Fetching the Value, Up: The as_value Object Type 2859 28603.4.6.4 Setting the Value and Type 2861.................................. 2862 2863Finally, there is the _set_TYPE_ series of methods. They change the 2864type to the type specified in the method name, and set the value to the 2865one given as an argument. It is also possible to accomplish the same 2866thing with the _=_ operator. Again, type names match those named 2867earlier (*note Data Types::), except in the case of _MOVIECLASS_. Its 2868method is called _set_sprite()_. 2869 2870 2871File: gnash_ref.info, Node: Further Reading, Prev: Setting the Value and Type, Up: The as_value Object Type 2872 28733.4.6.5 Further Reading 2874....................... 2875 2876Please refer to _as_value.h_ or the Doxygen documentation (see 2877'Processing The Documentation' in the Gnash manual for instructions on 2878generating documents with Doxygen) for more information about which 2879methods are available for the _as_value_ object. 2880 2881 2882File: gnash_ref.info, Node: Object ActionScript Class, Prev: The as_value Object Type, Up: Adding New ActionScript Class 2883 28843.4.7 Object ActionScript Class 2885------------------------------- 2886 2887This class implements an Object object. 2888 2889* Menu: 2890 2891* The Methods of the Class:: 2892* The Properties of the Object Class:: 2893* Object Class Conformance:: 2894 2895 2896File: gnash_ref.info, Node: The Methods of the Class, Next: The Properties of the Object Class, Up: Object ActionScript Class 2897 28983.4.7.1 The Methods of the Class 2899................................ 2900 2901addProperty() 2902 2903registerClass() 2904 2905toString() 2906 2907unwatch() 2908 2909valueOf() 2910 2911watch() 2912 2913Sharedclear() 2914 2915Sharedflush() 2916 2917SharedgetLocal() 2918 2919SharedgetSize() 2920 2921 2922File: gnash_ref.info, Node: The Properties of the Object Class, Next: Object Class Conformance, Prev: The Methods of the Class, Up: Object ActionScript Class 2923 29243.4.7.2 The Properties of the Object Class 2925.......................................... 2926 2927constructor 2928 2929__proto__ 2930 2931__resolve 2932 2933Shareddata 2934 2935SharedonStatus 2936 2937 2938File: gnash_ref.info, Node: Object Class Conformance, Prev: The Properties of the Object Class, Up: Object ActionScript Class 2939 29403.4.7.3 Object Class Conformance 2941................................ 2942 2943Class Name Conformance 2944addProperty() This method has an unknown status. 2945registerClass() This method has an unknown status. 2946toString() This method has an unknown status. 2947unwatch() This method has an unknown status. 2948valueOf() This method has an unknown status. 2949watch() This method has an unknown status. 2950Sharedclear() This method has an unknown status. 2951Sharedflush() This method has an unknown status. 2952SharedgetLocal() This method has an unknown status. 2953SharedgetSize() This method has an unknown status. 2954constructor This property has an unknown 2955 status. 2956__proto__ This property has an unknown 2957 status. 2958__resolve This property has an unknown 2959 status. 2960Shareddata This property has an unknown 2961 status. 2962SharedonStatus This property has an unknown 2963 status. 2964 2965 2966File: gnash_ref.info, Node: Gnash Extensions, Next: RTMP Protocol, Prev: Software Internals, Up: Top 2967 29684 Gnash Extensions 2969****************** 2970 2971Gnash supports extending the Flash specification by creating custom 2972ActionScript classes that are compiled code, as opposed to the existing 2973method of defining custom classes as ActionScript. Executing compiled 2974code has many performance benefits over having to interpret the byte 2975stream of the ActionScript opcodes. 2976 2977 I can already hear people complaining now about the concept of 2978extending Flash, so this in no way affects Gnash's ability to play 2979Flash movies when functioning as a browser plugin. Gnash's goal is 2980still to function in a way that is compatible with the current 2981proprietary Flash player. 2982 2983 But at the same time, we see Flash as the ideal scripting language 2984for a digital multi-media streaming environment. There are many 2985resources for Flash movie creators for widgets, higher level APIs, all 2986sorts of desirable things. But for those of use committed to using free 2987software tools for Flash, our options are very limited. 2988 2989 Rather than launching a multi-year project to duplicate all classes 2990in the commercial Flash IDE, it's much more efficient to use existing 2991development libraries much like Python or Perl do. The extension 2992mechanism in Gnash allows wrappers to be created for any C or C++ 2993development library. Unlike the proprietary Flash IDE, which compiles 2994all the extension libraries into byte codes from ActionScript, the 2995support is moved to the player side. Movies with all of the goodies of 2996the proprietary IDE in them play in Gnash just fine, as it's all just 2997byte codes by then. 2998 2999 This trick works because until Flash player version 9, all the 3000ActionScript class names and methods are passed as ASCII strings into 3001the Flash movie. So the Gnash Virtual Machine just loads the extension 3002file if that class name is invoked in the movie. All extension files 3003specify the class name and methods it implements in an identical style 3004as adding any new ActionScript class. The advantage is the class itself 3005is compiled code, and runs much faster than the equivalent byte codes 3006which all have to be interpreted.. 3007 3008* Menu: 3009 3010* Creating A New Extension:: 3011* Debugging An Extension:: 3012* Included Extensions:: 3013 3014 3015File: gnash_ref.info, Node: Creating A New Extension, Next: Debugging An Extension, Up: Gnash Extensions 3016 30174.1 Creating A New Extension 3018============================ 3019 3020Each new extension should live in it's own directory. The extensions 3021included in Gnash are all in the gnash/extensions directory. Creating 3022an extension requires a Makefile.am, 3023 3024 If you are adding this extension to the Gnash source tree itself, 3025then you need to make two changes to add the new extension. 3026 3027 The first change is to add the directory to the list in 3028extensions/Makefile.am. This can be done either by adding the new 3029directory to the SUBDIRS setting, or by wrapping it in a conditional 3030test. 3031 3032 The other change is to add it to the AC_OUTPUT list in 3033_configure.ac_ so the new directory will be configured along with the 3034rest of Gnash. 3035 3036 Each extension should have an ActionScript source file included that 3037tests the new class, and this file should be referenced in the new 3038Makefile.am in the _check_PROGRAMS_ variable so that "make check" works. 3039 3040 When creating an extension that is a wrapper for an existing 3041development library API, it's often better to make this a thin layer, 3042than to get carried away with creating beautiful abstractions. 3043Higher-level classes that offer a lot of new functionality are fine, 3044but is different than wrapping a library so it can be used from within 3045Gnash. 3046 3047* Menu: 3048 3049* Crafting an Extension:: 3050 3051 3052File: gnash_ref.info, Node: Crafting an Extension, Up: Creating A New Extension 3053 30544.1.1 Crafting an Extension 3055--------------------------- 3056 3057All extensions have the same requirements, namely setting up a few 3058defined function callbacks, which the Gnash VM then uses to do the 3059right thing. The initial two function callbacks are for handling the 3060interface of the newly created object so that Gnash can find and use it. 3061 3062 The first function is commonly called _attachInterface_, and this 3063sets the other function callbacks for all the methods this class 3064supports. The method callbacks are attached to the parent class by 3065using _init_member()_ to set a C function pointer to the string value 3066used in the Flash movie. 3067 3068 3069 // Attach DummyClass 'func1' and 'func2' methods to the given object 3070 static void 3071 attachInterface(as_object& obj) { 3072 obj.init_member("func1", &ext_func1); 3073 obj.init_member("func2", &ext_func2); 3074 } 3075 3076 The second function is commonly called _getInterface()_, and this 3077returns a pointer to a static prototype of the class. Gnash uses 3078garbage collection for ActionScript objects so you need to register the 3079static with the VM to give it a chance to be marked as reachable. 3080 3081 3082 static as_object* 3083 getInterface() 3084 { 3085 static boost::intrusive_ptr<as_object> o; 3086 if (o == NULL) { 3087 o = new as_object(); 3088 VM::get().addStatic(o); 3089 attachInterface(*o); 3090 } 3091 return o.get(); 3092 } 3093 3094 This is the callback that gets executed when constructing a new 3095object for the VM. In this example we'll assume the new ActionScript 3096class is called _DummyExt_, and has two methods, _func1_ and _func2_. 3097 3098 3099 static as_value 3100 dummyext_ctor(const fn_call& fn) 3101 { 3102 DummyExt *obj = new DummyExt(); // will setup prototypes 3103 3104 return as_value(obj); 3105 } 3106 3107 The trick for the above simple constructor to work is that class 3108appartenence is setup in the C++ DummyExt constructor itself, which 3109should derive from as_object and construct the base passing it the 3110interface (prototype) of it's class. 3111 3112 3113 class DummyExt : public as_object 3114 { 3115 public: 3116 DummyExt() 3117 : 3118 as_object(getInterface()) // returns the static prototype 3119 {} 3120 3121 }; 3122 3123 Initialize the extension. This is looked for by the extension 3124handling code in each extension, and is executed when the extension is 3125loaded. This is the main entry point into the extension. This function 3126can be found because the prefix of _dummyext_, which also matches the 3127file name of the extension. Gnash uses the name of the extension file 3128itself when looking for the init function. 3129 3130 3131 extern "C" { 3132 void 3133 dummyext_class_init(as_object &obj) 3134 { 3135 static builtin_function* cl=NULL; 3136 if (!cl) 3137 { 3138 // Create a builtin function using the given constructor 3139 // to instanciate objects and exporting the given interface 3140 cl = new builtin_function(&dummyext_ctor, getInterface()); 3141 VM::get().addStatic(cl); // will forbid to collect the class 3142 } 3143 3144 obj.init_member("DummyExt", cl); 3145 } 3146 } // end of extern C 3147 3148 The callbacks are all C functions. Like all the other code that 3149implements ActionScript, parameters to the function are passed in using 3150the _fn_call_ data structure. The return code, if any, is also returned 3151using this data structure. _this_ptr_ is the object that the method is 3152a member of. 3153 3154 3155 // Creates a new button with the label as the text. 3156 as_value func1(const fn_call& fn) { 3157 // Following line will ensure 'func1' is called for a DummyExt instance, 3158 // or would throw an exception which should behave as if we returned the 3159 // undefined value. 3160 boost::intrusive_ptr<DummyExt> ptr = ensureType<DummyExt>(fn.this_ptr); 3161 3162 if (fn.nargs > 0) { 3163 std::string label = fn.arg(0).to_string(); 3164 bool ret = ptr->dummy_text_label(label); 3165 return as_value(ret); 3166 } 3167 } 3168 3169 3170File: gnash_ref.info, Node: Debugging An Extension, Next: Included Extensions, Prev: Creating A New Extension, Up: Gnash Extensions 3171 31724.2 Debugging An Extension 3173========================== 3174 3175As extensions are loaded dynamically at runtime, debugging one can be 3176difficult. You can use GDB, but you have the problem of not being able 3177to set a breakpoint in Gnash until _after_ the extension has been 3178loaded into Gnash's VM. The easy solution is to use the Gnash debugger. 3179 3180 You can insert these few lines in any file that you wish to manually 3181start the debugger. Once at the console, you can attach GDB to the 3182process. Then you can set breakpoints, etc... and you are at the point 3183of execution where the console was started. To then continue playing 3184the movie, type the _c_ (for continue) command to the Gnash console. 3185 3186 3187 // Get the debugger instance 3188 static Debugger& debugger = Debugger::getDefaultInstance(); 3189 3190 // Enable the debugger 3191 debugger.enabled(true); 3192 // Stop and drop into a console 3193 debugger.console(); 3194 3195 You can also resort to the time honored technique of creating a loop 3196before the point you want to set a breakpoint for. Gnash will stop 3197playing the movie at this point, and then you can externally attach GDB 3198to the running process, or type _^C_ to drop into the GDB command 3199console. 3200 3201 3202 bool stall = true; 3203 while (stall) { 3204 sleep 1; 3205 } 3206 3207 Once you have set the breakpoints you want, reset the value of the 3208_stall_ variable to break out of the loop, and the Flash movie will 3209then continue playing. 3210 3211 3212 (gdb) set variable stall = false; 3213 continue 3214 3215 3216File: gnash_ref.info, Node: Included Extensions, Prev: Debugging An Extension, Up: Gnash Extensions 3217 32184.3 Included Extensions 3219======================= 3220 3221Gnash has some extensions included in the distribution. This is mostly 3222because they were written by the Gnash team. Extensions can be external 3223to gnash, Gnash needs no compiled in knowledge to load an extension 3224file. 3225 3226* Menu: 3227 3228* Gtk Extension:: 3229* File I/O Extension:: 3230* MySQL Extension:: 3231 3232 3233File: gnash_ref.info, Node: Gtk Extension, Next: File I/O Extension, Up: Included Extensions 3234 32354.3.1 Gtk Extension 3236------------------- 3237 3238The GTK ActionScript class follows the same API as Gtk2, even down to 3239the same arguments to the same function names. This means you're 3240actually programming GTK,you're just using ActionScript instead of 3241python, perl, or C. This extension makes it possible to write Flash 3242movies that use the Gtk2 widgets for user interface components. 3243 3244window_new 3245 Create a new window. 3246 3247signal_connect 3248 Add an event handler to a widget. 3249 3250container_set_border_width 3251 Set the width of the window border. 3252 3253button_new_with_label 3254 Create a new button and give it the specified label. 3255 3256signal_connect_swapped 3257 Swap signals. Commonly used for _delete_ event handling. 3258 3259container_add 3260 Add one widget to another as a child. 3261 3262widget_show 3263 Display the widget on the screen. 3264 3265main 3266 Start the main GTK event loop. This function does not return. 3267 3268 3269File: gnash_ref.info, Node: File I/O Extension, Next: MySQL Extension, Prev: Gtk Extension, Up: Included Extensions 3270 32714.3.2 File I/O Extension 3272------------------------ 3273 3274Flash movies are traditionally forbidden from accessing the filesystem, 3275but this may be necessary for some embedded applications. Especially in 3276the case of a user console, currently there is no way to get input into 3277a Flash movie but through a TextField. 3278 3279fopen 3280 Open the file. 3281 3282fread 3283 Read a series of bytes from the opened file. 3284 3285fgetc 3286 Read a single byte from the opened file. 3287 3288fgets 3289 Read a single line until a Carriage Return from the opened file. 3290 3291gets 3292 Read a single line from the standard in. 3293 3294getchar 3295 Read a single character from the standard in. 3296 3297fwrite 3298 3299fputc 3300 Write a single character to the opened file. 3301 3302fputs 3303 Write a single line to the opened file. 3304 3305puts 3306 Write a single line to standard out.. 3307 3308putchar 3309 Write a single character to standard out.. 3310 3311fflush 3312 Flush the current opened file to disk. 3313 3314fseek 3315 Seek to a location within the opened file. 3316 3317ftell 3318 Report the current position within the opened file. 3319 3320fclose 3321 Close the opened file. 3322 3323 3324File: gnash_ref.info, Node: MySQL Extension, Prev: File I/O Extension, Up: Included Extensions 3325 33264.3.3 MySQL Extension 3327--------------------- 3328 3329The MySQL ActionScript class follows the same API as MySQL, even down 3330to the same arguments to the same function names. This enables a Flash 3331movie to have direct access to a MySQL database. Traditionally Flash 3332movies have had no database support, they either had to use arrays, or 3333use XML to communicate to an application specific external database 3334daemon. 3335 3336connect 3337 Connect to a MySQL database. 3338 3339qetData 3340 Get data from the database. 3341 3342disconnect 3343 Disconnect from a MySQL database. 3344 3345query 3346 Execute an SQL query to the database. 3347 3348fetch_row 3349 Fetch a row from the query results. 3350 3351num_fields 3352 3353free_result 3354 Free the results of a query. 3355 3356store_results 3357 Store the results of a query. 3358 3359 3360File: gnash_ref.info, Node: RTMP Protocol, Next: Mozilla/Firefox NSAPI Plugin, Prev: Gnash Extensions, Up: Top 3361 33625 RTMP Protocol 3363*************** 3364 3365This document is based mostly on my own reverse engineering of the RTMP 3366protocol and AMF format. _tcpdump_ and _ethereal_ are your friend. Some 3367additional info that got me started was from the Red5 3368(http://www.osflash.org/red5) project. _Red5_ is the only other open 3369source Flash server. So some details are still vague, but as the 3370implementation appears to work, we'll figure out what they are later. 3371 3372 The Real Time Messaging Protocol was created by MacroMedia (now 3373Adobe) for delivering Flash objects and video over a network 3374connection. Currently the only servers which support this format are 3375the MacroMedia Media sever, and the Open Source Red5 project. 3376 3377 This is a simple protocol, optimized for poor bandwidth connections. 3378It can support up to 64 concurrent streams over the same network 3379connection. Part of each AMF packet header contains the index number of 3380the stream. A single RTMP message can contain multiple AMF packets. 3381 3382 An RTMP connection uses Tcp/ip port 1935. It is also possible to 3383tunnel RTMP over an HTTP connection using port 80. Each AMF packet is 3384128 bytes long except for streaming audio, which has 64 byte packets. 3385 3386 The basics of the RTMP protocol are as follows. All communications 3387are initiated by the client. 3388 3389Image of the RTMP protocol. 3390 3391 The client starts the RTMP connection by sending a single byte with 3392a value of 0x3. This byte is followed by a data block of 1536 bytes. 3393The format if this data block is unknown, but it appears to not be 3394actually used by the protocol except as a handshake. 3395 3396 The server receives this packet, stores the 1536 byte data block, 3397and then send a single byte with the value of 0x3, followed by two 1536 3398data blocks. The second data block is the full contents of the original 3399data block as sent by the client. 3400 3401 The client receives the 1536 byte data block, and if they match, the 3402connection is established. After the handshake process is done, there 3403are three other messages that the client sends to the sever to start 3404the data flowing. 3405 3406 The first AMF packet sent to the server contains the _connect_ 3407packet. This doesn't appear to do much but notify the server the client 3408is happy with the handshake, and ready to start reading packets. 3409 3410 The second packet is the _NetConnection_ object from the client. 3411This ActionScript class is used by the Flash movie to create the 3412network connection to the server. 3413 3414 The third packet is the _NetStream_ object from the client. This is 3415the ActionScript class used to specify the file to be streamed by the 3416server. 3417 3418 The RTMP packet for our example looks like this: 3419 3420 3421 030000190000c91400000000020007connect00?f0000000000000030003app0200# 3422 software/gnash/tests/1153948634.flv0008flashVer02000cLNX 6,0,82,0 0006 3423 swfUrl02001dfile:///file|%2Ftmp%2Fout.swfc30005tcUrl\002\0004 3424 rtmp://localhost/software/gnash/tests/1153948634.flv\000\000\t 3425 \002\000\005userx 3426 3427We'll take this apart in a bit, but you can see how all three AMF 3428packets are in the same message. The message is received in several 128 3429byte blocks, with the last one being less than that. The total size of 3430the RTMP message is in the header, so the reader can tell if the entire 3431message was read or not. 3432 3433 The RTMP header is first, followed by the connect message as an 3434ASCII string as the message body. The following AMF packet is the 3435_NetConnection_ one, which specifies that this is coming from a Flash 3436application. This also contains the file path the server can use to 3437find the file to stream. This is then followed by the version number, 3438which I assume is the version of the Flash player, so the server knows 3439what it is talking to. 3440 3441 The third packet is the one from _NetStream_, which specifies the 3442URL used for the movie, followed by the user name for a semblance of 3443security. 3444 3445 For the next level of detail, we'll explain the format of AMF. AMF 3446is used by the RTMP protocol to transfer data. Each Flash object is 3447encapsulated in an AMF packet, including streaming audio or video. 3448 3449 The first byte of the RTMP header determines two things about the 3450rest of the message. The first 2 bits of this byte signify the total 3451size of the RTMP header. The RTMP header is of a variable size, so this 3452is important. 3453 345400 3455 This specifies the header contains 12 bytes, including this one. 3456 345701 3458 This specifies the header contains 8 bytes, including this one. 3459 346002 3461 This specifies the header contains 4 bytes, including this one. 3462 346303 3464 This specifies the header contains 1 byte, so this is the complete 3465 header. 3466 3467 The other 6 bits in this byte represent the AMF index. As a single 3468RTMP connection can support multiple data streams, this signifies which 3469stream this packet is for. Once an AMF object is fully received by the 3470client, the AMF index may be reused. 3471 3472 For messages with headers of at least 4 bytes, the next 3 bytes are 3473used by audio and video data packets, but at this time the meaning of 3474this field is unknown. 3475 3476 For messages with a 8 byte or larger header, the next 3 bytes 3477determine the size of the RTMP message being transmitted. Messages with 3478a 1 byte or 4 byte header use a standard size, 128 bytes for video, and 347964 bytes for audio. 3480 3481 For messages with an 8 byte or larger header, the next byte is the 3482type of the AMF object. 3483 34840x3 3485 This specifies the content type of the RTMP packet is the number 3486 of bytes read. This is used to start the RTMP connection. 3487 34880x4 3489 This specifies the content type of the RTMP message is a _ping_ 3490 packet. 3491 34920x5 3493 This specifies the content type of the RTMP message is server 3494 response of some type. 3495 34960x6 3497 This specifies the content type of the RTMP packet is client 3498 request of some type. 3499 35000x8 3501 This specifies the content type of the RTMP packet is an audio 3502 message. 3503 35040x9 3505 This specifies the content type of the RTMP message is a video 3506 packet. 3507 35080x12 3509 This specifies the content type of the RTMP message is notify. 3510 35110x13 3512 This specifies the content type of the RTMP message is shared 3513 object. 3514 35150x14 3516 This specifies the content type of the RTMP message is remote 3517 procedure call. This invokes the method of a Flash class remotely. 3518 3519 There are two sets of data types to consider. One set is used by the 3520to specify the content type of the AMF object, the other is an 3521ActionScript data type tag used to denote which type of object is being 3522transferred. 3523 3524 The values of the initial type byte are: 3525 35260x0 3527 This specifies the data in the AMF packet is a numeric value. All 3528 numeric values in Flash are 64 bit, _big-endian_. 3529 35300x1 3531 This specifies the data in the AMF packet is a boolean value. 3532 35330x2 3534 This specifies the data in the AMF packet is an _ASCII_ string. 3535 35360x3 3537 This specifies the data in the AMF packet is a Flash object. The 3538 Flash object data type field further along in the message 3539 specifies which type of ActionScript object it is. 3540 35410x4 3542 This specifies the data in the AMF packet is a Flash movie, ie. 3543 another Flash movie. 3544 35450x5 3546 This specifies the data in the AMF packet is a NULL value. NULL is 3547 often used as the return code from calling Flash functions. 3548 35490x6 3550 This specifies the data in the AMF packet is a undefined. This is 3551 also used as the return code from calling Flash functions. 3552 35530x7 3554 This specifies the data in the AMF packet is a reference. 3555 35560x8 3557 This specifies the data in the AMF packet is a ECMA array. 3558 35590x9 3560 This specifies the data in the AMF packet is the end of an object 3561 definition. As an object is transmitted with multiple AMF packets, 3562 this lets the server know when the end of the object is reached. 3563 35640xa 3565 This specifies the data in the AMF packet is a Strict array. 3566 35670xb 3568 This specifies the data in the AMF packet is a date. 3569 35700xc 3571 This specifies the data in the AMF packet is a multi-byte string. 3572 Multi-byte strings are used for international language support to 3573 represent non _ASCII_ fonts. 3574 35750xd 3576 This specifies the data in the AMF packet is a an unsupported 3577 feature. 3578 35790xe 3580 This specifies the data in the AMF packet is a record set. 3581 35820xf 3583 This specifies the data in the AMF packet is a AML object. XML 3584 objects are then parsed by the _XML_ ActionScript class. 3585 35860x10 3587 This specifies the data in the AMF packet is a typed object. 3588 3589 For messages with a 12 byte header, the last 4 bytes are the routing 3590of the message. If the destination is the server, this value is the 3591NetStream object source. If the destination is the client, this is the 3592NetStream object for this RTMP message. A value of 0x00000000 appears 3593to be reserved for the NetConnection object. 3594 3595 Multiple AMF streams can be contained in a single RTMP messages, so 3596it's important to check the index of each AMF packet. 3597 3598 An example RTMP header might look like this. (spaces added between 3599fields for clarity) All the numbers are in hex. 3600 3601 3602 03 000019 0000c9 14 000000000 3603 360403 3605 The first two bits of this byte are the size of the header, which 3606 in this example is 00, for a 12 byte header. The next 6 bits is 3607 the AMF stream index number, which in this example is 0x3. 3608 3609000019 3610 These 3 bytes currently have an unknown purpose. 3611 3612000c9 3613 Since this example has a 12 byte header, this is the size of the 3614 RTMP message, in this case 201 bytes. 3615 361614 3617 This is the content type of the RTMP message, which in this case 3618 is to invoke a remote function call. (which we later see is the 3619 connect function). 3620 362100000000 3622 The source is the NetConnection object used to start this 3623 connection. 3624 3625* Menu: 3626 3627* AMF Format:: 3628 3629 3630File: gnash_ref.info, Node: AMF Format, Up: RTMP Protocol 3631 36325.1 AMF Format 3633============== 3634 3635The AMF format is used in the LocalConnection, SharedObject, 3636NetConnection, and NetStream ActionScript classes. This is a means of 3637binary data interchange between Flash movies, or between a SWF player 3638and a SWF server. 3639 3640 Like the RTMP messages, an AMF packet header can be of a variable 3641size. The size is either the same as the initial header of the RTMP 3642message, or a 1 byte header, which is commonly used for streaming audio 3643or video data. 3644 3645 The body of an AMF packet may look something like this example. The 3646spaces have been added for clarity. 3647 3648 3649 02 0007 636f6e6e656374 3650 365102 3652 This is a single byte header. The value of the first 2 bits is 3653 0x3, and the AMF index is also 0x3. 3654 36550007 3656 This is the length in bytes of the string. 3657 365863 6f 6e 6e 65 63 74 3659 This is the string. Note that there is no null terminator since 3660 the length is specified. 3661 3662 3663File: gnash_ref.info, Node: Mozilla/Firefox NSAPI Plugin, Next: Appendix, Prev: RTMP Protocol, Up: Top 3664 36656 Mozilla/Firefox NSAPI Plugin 3666****************************** 3667 3668The Mozilla SDK has two API layers for plugins. The older layer is 3669documented in the Geeko Plugin API Reference 3670(http://www.gnu.org/software/gnash/manual/plugin.pdf), and the newer 3671layer doesn't appear to be documented. The new API is simpler, and is 3672portable across multiple versions of Mozilla or Firefox. The new API is 3673just a layer on top of the older one, so this manual still applies. 3674 3675 Most of the programming of a plugin is filling in real emphasis for 3676the standard API functions and methods. Firefox uses these to create 3677the plugin, and to send it data. 3678 3679 When initializing or destroying a plugin, no matter how many 3680instances are being used, the C API is used. These functions are 3681typically called once for each plugin that is loaded. 3682 3683* Menu: 3684 3685* Plugin C API:: 3686* Plugin C++ API:: 3687* OpenGL and Threads:: 3688* Plugin Event Handling:: 3689 3690 3691File: gnash_ref.info, Node: Plugin C API, Next: Plugin C++ API, Up: Mozilla/Firefox NSAPI Plugin 3692 36936.1 Plugin C API 3694================ 3695 3696The lower layer is a C based API which is used by Firefox to initialize 3697and destroy a plugin. This is so a plugin can be portable across 3698multiple systems, since C++ emphasis is not portable between most C++ 3699compilers. This is where most of the behind the scenes work is done in 3700a plugin. For Gnash, the sources this lower layer are in 3701_plugin/mozilla-sdk_. They were added to the Gnash source tree so it 3702wouldn't be necessary to have the Mozilla development packages 3703installed to compile the Gnash plugin. 3704 3705 This is also the older API used for plugins, so is usually the one 3706used if you dig around for plugin examples on the web. These are the 3707main functions which have to be implemented in a plugin for it to be 3708recognized by the browser, and to be initialized and destroyed. 3709 3710NS_PluginInitialize 3711 This C function gets called once when the plugin is loaded, 3712 regardless of how many instantiations there are actually playing 3713 movies. So this is where all the one time only initialization 3714 stuff goes that is shared by all the threads. 3715 3716NS_NewPluginInstance 3717 This instantiates a new object for the browser. Returning a 3718 pointer to the C++ plugin object is what ties the C++ and C 3719 emphasis parts of the API together. 3720 3721NS_DestroyPluginInstance 3722 This destroys our instantiated object when the browser is done. 3723 3724NS_PluginShutdown 3725 This is called when a plugin is shut down, so this is where all 3726 the one time only shutdown stuff goes. 3727 3728NPP_GetMIMEDescription 3729 This is called to get the MIME types the plugin supports. 3730 3731NS_PluginGetValue 3732 This is used by Firefox to query information from the plugin, like 3733 the supported MIME type, the version number, and a description. 3734 3735 3736File: gnash_ref.info, Node: Plugin C++ API, Next: OpenGL and Threads, Prev: Plugin C API, Up: Mozilla/Firefox NSAPI Plugin 3737 37386.2 Plugin C++ API 3739================== 3740 3741The higher level layer is the one we are most concerned with. This is 3742an instantiation of the _nsPluginInstanceBase_ class, as defined by the 3743Mozilla SDK, for our plugin. With this API, a plugin is mostly defining 3744the standard entry points for Firefox, and the emphasis that implements 3745the glue between the Firefox and our plugin. 3746 3747 These are called for each instantiation of plugin. If there are 3748three Flash movies on a web page, then three instances are created. 3749Unfortunately for plugin programmers, these functions may randomly be 3750called more than once, so it's good to use initialization flags for 3751things that should only be done one per thread. For instance, 3752_nsPluginInstance::init()_ and _nsPluginInstance::SetWindow()_ are 3753called more than once, so the plugin must protect against actions that 3754could be destructive. 3755 3756nsPluginInstance::nsPluginInstance 3757 Create a new plugin object. 3758 3759nsPluginInstance::init 3760 This methods initializes the plugin object, and is called for 3761 every movie which gets played. This is where the thread-specific 3762 information goes. 3763 3764nsPluginInstance::SetWindow 3765 This sets up the window the plugin is supposed to render into. 3766 This calls passes in various information used by the plugin to 3767 setup the window. This may get called multiple times by each 3768 instantiated object, so it can't do much but window specific setup 3769 here. This is where the main emphasis is that sets up the window 3770 for the plugin. 3771 3772nsPluginInstance::NewStream 3773 Opens a new incoming data stream, which is the flash movie we want 3774 to play. A URL can be pretty ugly, like in this example: 3775 http://www.sickwave.com/swf/navbar/navbar_sw.swf?atfilms=http%3a//www.atm.com/af/home/&shickwave=http%3a//www.sickwave.com&gblst=http%3a//gbst.sickwave.com/gb/gbHome.jsp&known=0 3776 ../flash/gui.swf?ip_addr=foobar.com&ip_port=3660&show_cursor=true&path_prefix=../flash/&trapallkeys=true" 3777 So this is where we parse the URL to get all the options passed in 3778 when invoking the plugin. 3779 3780nsPluginInstance::Write 3781 Read the data stream from Mozilla/Firefox. For now we read the 3782 bytes and write them to a disk file. 3783 3784nsPluginInstance::WriteReady 3785 Return how many bytes we can read into the buffer. 3786 3787nsPluginInstance::DestroyStream 3788 Destroy the data stream we've been reading. For Gnash, when the 3789 stream is destroyed means we've grabbed the entire movie. So we 3790 signal the thread to start reading and playing the movie. 3791 3792nsPluginInstance::shut 3793 This is where the movie playing specific shutdown emphasis goes. 3794 3795nsPluginInstance::~nsPluginInstance 3796 This destroys our plugin object. 3797 3798NS_PluginInitialize::initGL 3799 This is a Gnash internal function that sets up OpenGL. 3800 3801NS_PluginInitialize::destroyContext 3802 This is a Gnash internal function that destroys a GLX context. 3803 3804nsPluginInstance::getVersion 3805 This returns the version of Mozilla this plugin supports. 3806 3807nsPluginInstance::GetValue 3808 This returns information to the browser about the plugin's name 3809 and description. 3810 3811nsPluginInstance::URLNotify 3812 3813 3814File: gnash_ref.info, Node: OpenGL and Threads, Next: Plugin Event Handling, Prev: Plugin C++ API, Up: Mozilla/Firefox NSAPI Plugin 3815 38166.3 OpenGL and Threads 3817====================== 3818 3819Neither OpenGL nor X11 has any built-in support for threads. Most 3820actions aren't even atomic, so care has to be made to not corrupt any 3821internal data. While it is difficult to render OpenGL from multiple 3822threads, it can be done with the proper locking. The downside is the 3823locking adds a performance hit, since all the threads will have to have 3824the access synchronized by using mutexes. 3825 3826 The X11 context is maintained one per instantiation of the plugin. 3827It is necessary to lock access to the X11 context when using threads by 3828using _XLockDisplay()_ and _XUnlockDisplay()_. A connection to the X11 3829server is opened for every instantiation of the plugin using 3830_XOpenDisplay()_. 3831 3832 The _GLX Context_ is maintained one per instantiation of the plugin 3833for a web page. If there are more than one Flash movie, there is more 3834than one GLX Context. A GLX context can be created by using 3835_glXCreateContext()_, and then later destroyed by using 3836_glXDestroyContext()_. When swapping threads, the context is changed 3837using _glXMakeCurrent()_. 3838 3839 All the emphasis that directly accesses a GLX context or the X11 3840display must be wrapped with a mutex. 3841 3842 3843File: gnash_ref.info, Node: Plugin Event Handling, Prev: OpenGL and Threads, Up: Mozilla/Firefox NSAPI Plugin 3844 38456.4 Plugin Event Handling 3846========================= 3847 3848Firefox on most UNIX systems is a GTK+ application, so it is possible 3849to have the plugin hook into the X11 event handling via GLX or GTK. 3850Since Firefox uses GTK, so does Gnash. This also allows the addition of 3851a right-click mouse menu for controlling the player. The GTK build of 3852Gnash offers the best browsing experience as it's more functional than 3853the SDL version. 3854 3855 It is also possible to disable the _GTK_ support so only the older 3856_SDL_ support is used. In this case Gnash can't support event handling 3857within the browser. This means that when using the SDL of the plugin, 3858mouse clicks and keys pressed get ignored. Windows also can't be 3859resized, and sometimes they overrun their boundaries as well. To 3860disable the GTK support and force SDL to be used anyway, configure with 3861_-disable-glext_ 3862 3863 3864File: gnash_ref.info, Node: Appendix, Next: Authors, Prev: Mozilla/Firefox NSAPI Plugin, Up: Top 3865 38667 Appendix 3867********** 3868 3869* Menu: 3870 3871* Code Style:: 3872 3873 3874File: gnash_ref.info, Node: Code Style, Up: Appendix 3875 38767.1 Code Style 3877============== 3878 3879I know any discussion of coding styles leads to strong opinions, so 3880I'll state simply I follow the GNU Coding Standards 3881(http://www.gnu.org/prep/standards/standards.html). Where there is some 3882flexibility as to the location of braces, I prefer mine on the end of a 3883line when using an _if_, _while_, or _do_ statement. I find this more 3884compact style easier to read and parse by eye. I'm also a big fan of 3885always using braces around _if_ statements, even if they're one liners. 3886 3887 Here's my tweaked style settings for _Emacs_, the one true editor to 3888rule them all. 3889 3890 3891 (defconst my-style 3892 '((c-tab-always-indent . t) 3893 (c-auto-newline . t) 3894 (c-hanging-braces-alist . ( 3895 (brace-list-intro) 3896 (namespace-open) 3897 (inline-open) 3898 (block-open) 3899 (brace-list-open) 3900 (brace-list-close) 3901 (brace-entry-open) 3902 (brace-else-brace) 3903 (brace-elseif-brace) 3904 (class-open after) 3905 (class-close) 3906 (defun-open after) 3907 (defun-close) 3908 (extern-lang-open) 3909 (inexpr-class-open) 3910 (statement-open) 3911 (substatement-open) 3912 (inexpr-class-close))) 3913 (c-hanging-colons-alist . ((member-init-intro before) 3914 (inher-intro) 3915 (case-label after) 3916 (label after) 3917 (access-label after))) 3918 (c-offsets-alist . ( 3919 (innamespace . 0) 3920 (case-label . 2) 3921 )) 3922 (c-cleanup-list . ( 3923 (scope-operator) 3924 (empty-defun-braces) 3925 (brace-else-brace) 3926 (brace-elseif-brace) 3927 (defun-close-semi) 3928 (list-close-comma) 3929 ) 3930 ) 3931 ;; no automatic newlines after ';' if following line non-blank or inside 3932 ;; one-line inline methods 3933 (add-to-list 'c-hanging-semi&comma-criteria 3934 'c-semi&comma-no-newlines-before-nonblanks) 3935 (add-to-list 'c-hanging-semi&comma-criteria 3936 'c-semi&comma-no-newlines-for-oneline-inliners) 3937 ; (knr-argdecl-intro . -) 3938 (c-echo-syntactic-information-p . t) 3939 ) 3940 "My GNU Programming Style") 3941 3942 Another coding consideration: comments are good! Over commenting 3943isn't good. Here is an over commented example: 3944 3945 3946 counter++; // increment counter 3947 3948Gnash also uses Doxygen (http://www.doxygen.org) style comments. These 3949are processed by Doxygen when building a cross reference of all the 3950classes, and is a good way to help push internals documentation from 3951the depths of the code into documentation where it can be seen by 3952others. 3953 3954 _Doxygen_ style comments for _C++_ code involves simply using three 3955slashes _///_ instead of the standard two slashes _//_ used for C++ 3956comments. Here's a short comment block for the _XML::cloneNode()_ 3957method: 3958 3959 3960 /// \brief copy a node 3961 /// 3962 /// Method; constructs and returns a new XML node of the same type, 3963 /// name, value, and attributes as the specified XML object. If deep 3964 /// is set to true, all child nodes are recursively cloned, resulting 3965 /// in an exact copy of the original object's document tree. 3966 XMLNode & 3967 XML::cloneNode(XMLNode &newnode, bool deep) { 3968 ... 3969 } 3970 3971 The _\brief_ keyword means that the text becomes associated when 3972listing all the classes on the generated web pages. The text after the 3973blank link becomes the detailed description which appears on the 3974generated web page for that class and method. 3975 3976 3977File: gnash_ref.info, Node: Authors, Next: GNU Free Documentation License, Prev: Appendix, Up: Top 3978 39798 Authors 3980********* 3981 3982Gnash is maintained by Rob Savoye. Other active developers are: Sandro 3983Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad Musick, Benjamin 3984Wolsey, and Zou Lunkai. Please send all comments and suggestions to 3985<gnash-dev@gnu.org>. Past and sometimes current developers are Tomas 3986Groth and Markus Gothe. 3987 3988 Gnash was initially derived from GameSWF. GameSWF is maintained by 3989Thatcher Ulrich <tu@tulrich.com>. The following people contributed to 3990GameSWF: Mike Shaver, Thierry Berger-Perrin, Ignacio Castan~o, Willem 3991Kokke, Vitaly Alexeev, Alexander Streit, and Rob Savoye. 3992 3993 3994File: gnash_ref.info, Node: GNU Free Documentation License, Prev: Authors, Up: Top 3995 3996Appendix A GNU Free Documentation License 3997***************************************** 3998 3999* Menu: 4000 4001* 0. PREAMBLE: 0_ PREAMBLE. 4002* 1. APPLICABILITY AND DEFINITIONS: 1_ APPLICABILITY AND DEFINITIONS. 4003* 2. VERBATIM COPYING: 2_ VERBATIM COPYING. 4004* 3. COPYING IN QUANTITY: 3_ COPYING IN QUANTITY. 4005* 4. MODIFICATIONS: 4_ MODIFICATIONS. 4006* 5. COMBINING DOCUMENTS: 5_ COMBINING DOCUMENTS. 4007* 6. COLLECTIONS OF DOCUMENTS: 6_ COLLECTIONS OF DOCUMENTS. 4008* 7. AGGREGATION WITH INDEPENDENT WORKS: 7_ AGGREGATION WITH INDEPENDENT WORKS. 4009* 8. TRANSLATION: 8_ TRANSLATION. 4010* 9. TERMINATION: 9_ TERMINATION. 4011* 10. FUTURE REVISIONS OF THIS LICENSE: 10_ FUTURE REVISIONS OF THIS LICENSE. 4012* Addendum:: 4013 4014 4015File: gnash_ref.info, Node: 0_ PREAMBLE, Next: 1_ APPLICABILITY AND DEFINITIONS, Up: GNU Free Documentation License 4016 4017A.1 0. PREAMBLE 4018=============== 4019 4020The purpose of this License is to make a manual, textbook, or other 4021written document "free" in the sense of freedom: to assure everyone the 4022effective freedom to copy and redistribute it, with or without 4023modifying it, either commercially or non-commercially. Secondarily, 4024this License preserves for the author and publisher a way to get credit 4025for their work, while not being considered responsible for 4026modifications made by others. 4027 4028 This License is a kind of "copyleft", which means that derivative 4029works of the document must themselves be free in the same sense. It 4030complements the GNU General Public License, which is a copyleft license 4031designed for free software. 4032 4033 We have designed this License in order to use it for manuals for 4034free software, because free software needs free documentation: a free 4035program should come with manuals providing the same freedoms that the 4036software does. But this License is not limited to software manuals; it 4037can be used for any textual work, regardless of subject matter or 4038whether it is published as a printed book. We recommend this License 4039principally for works whose purpose is instruction or reference. 4040 4041 4042File: gnash_ref.info, Node: 1_ APPLICABILITY AND DEFINITIONS, Next: 2_ VERBATIM COPYING, Prev: 0_ PREAMBLE, Up: GNU Free Documentation License 4043 4044A.2 1. APPLICABILITY AND DEFINITIONS 4045==================================== 4046 4047This License applies to any manual or other work that contains a notice 4048placed by the copyright holder saying it can be distributed under the 4049terms of this License. The "Document", below, refers to any such manual 4050or work. Any member of the public is a licensee, and is addressed as 4051"you". 4052 4053 A "Modified Version" of the Document means any work containing the 4054Document or a portion of it, either copied verbatim, or with 4055modifications and/or translated into another language. 4056 4057 A "Secondary Section" is a named appendix or a front-matter section 4058of the Document (*note fdl-document::) that deals exclusively with the 4059relationship of the publishers or authors of the Document to the 4060Document's overall subject (or to related matters) and contains nothing 4061that could fall directly within that overall subject. (For example, if 4062the Document is in part a textbook of mathematics, a Secondary Section 4063may not explain any mathematics.) The relationship could be a matter 4064of historical connection with the subject or with related matters, or of 4065legal, commercial, philosophical, ethical or political position 4066regarding them. 4067 4068 The "Invariant Sections" are certain Secondary Sections (*note 4069fdl-secondary::) whose titles are designated, as being those of 4070Invariant Sections, in the notice that says that the Document (*note 4071fdl-document::) is released under this License. 4072 4073 The "Cover Texts" are certain short passages of text that are 4074listed, as Front-Cover Texts or Back-Cover Texts, in the notice that 4075says that the Document (*note fdl-document::) is released under this 4076License. 4077 4078 A "Transparent" copy of the Document (*note fdl-document::) means a 4079machine-readable copy, represented in a format whose specification is 4080available to the general public, whose contents can be viewed and edited 4081directly and straightforwardly with generic text editors or (for images 4082composed of pixels) generic paint programs or (for drawings) some 4083widely available drawing editor, and that is suitable for input to text 4084formatters or for automatic translation to a variety of formats 4085suitable for input to text formatters. A copy made in an otherwise 4086Transparent file format whose markup has been designed to thwart or 4087discourage subsequent modification by readers is not Transparent. A 4088copy that is not "Transparent" is called "Opaque". 4089 4090 Examples of suitable formats for Transparent copies include plain 4091ASCII without markup, Texinfo input format, LaTeX input format, SGML or 4092XML using a publicly available DTD, and standard-conforming simple HTML 4093designed for human modification. Opaque formats include PostScript, PDF, 4094proprietary formats that can be read and edited only by proprietary 4095word processors, SGML or XML for which the DTD and/or processing tools 4096are not generally available, and the machine-generated HTML produced by 4097some word processors for output purposes only. 4098 4099 The "Title Page" means, for a printed book, the title page itself, 4100plus such following pages as are needed to hold, legibly, the material 4101this License requires to appear in the title page. For works in formats 4102which do not have any title page as such, "Title Page" means the text 4103near the most prominent appearance of the work's title, preceding the 4104beginning of the body of the text. 4105 4106 4107File: gnash_ref.info, Node: 2_ VERBATIM COPYING, Next: 3_ COPYING IN QUANTITY, Prev: 1_ APPLICABILITY AND DEFINITIONS, Up: GNU Free Documentation License 4108 4109A.3 2. VERBATIM COPYING 4110======================= 4111 4112You may copy and distribute the Document (*note fdl-document::) in any 4113medium, either commercially or noncommercially, provided that this 4114License, the copyright notices, and the license notice saying this 4115License applies to the Document are reproduced in all copies, and that 4116you add no other conditions whatsoever to those of this License. You 4117may not use technical measures to obstruct or control the reading or 4118further copying of the copies you make or distribute. However, you may 4119accept compensation in exchange for copies. If you distribute a large 4120enough number of copies you must also follow the conditions in section 41213 (*note 3_ COPYING IN QUANTITY::). 4122 4123 You may also lend copies, under the same conditions stated above, 4124and you may publicly display copies. 4125 4126 4127File: gnash_ref.info, Node: 3_ COPYING IN QUANTITY, Next: 4_ MODIFICATIONS, Prev: 2_ VERBATIM COPYING, Up: GNU Free Documentation License 4128 4129A.4 3. COPYING IN QUANTITY 4130========================== 4131 4132If you publish printed copies of the Document (*note fdl-document::) 4133numbering more than 100, and the Document's license notice requires 4134Cover Texts (*note fdl-cover-texts::), you must enclose the copies in 4135covers that carry, clearly and legibly, all these Cover Texts: 4136Front-Cover Texts on the front cover, and Back-Cover Texts on the back 4137cover. Both covers must also clearly and legibly identify you as the 4138publisher of these copies. The front cover must present the full title 4139with all words of the title equally prominent and visible. You may add 4140other material on the covers in addition. Copying with changes limited 4141to the covers, as long as they preserve the title of the Document 4142(*note fdl-document::) and satisfy these conditions, can be treated as 4143verbatim copying in other respects. 4144 4145 If the required texts for either cover are too voluminous to fit 4146legibly, you should put the first ones listed (as many as fit 4147reasonably) on the actual cover, and continue the rest onto adjacent 4148pages. 4149 4150 If you publish or distribute Opaque (*note fdl-transparent::) copies 4151of the Document (*note fdl-document::) numbering more than 100, you 4152must either include a machine-readable Transparent (*note 4153fdl-transparent::) copy along with each Opaque copy, or state in or 4154with each Opaque copy a publicly-accessible computer-network location 4155containing a complete Transparent copy of the Document, free of added 4156material, which the general network-using public has access to download 4157anonymously at no charge using public-standard network protocols. If 4158you use the latter option, you must take reasonably prudent steps, when 4159you begin distribution of Opaque copies in quantity, to ensure that 4160this Transparent copy will remain thus accessible at the stated 4161location until at least one year after the last time you distribute an 4162Opaque copy (directly or through your agents or retailers) of that 4163edition to the public. 4164 4165 It is requested, but not required, that you contact the authors of 4166the Document (*note fdl-document::) well before redistributing any 4167large number of copies, to give them a chance to provide you with an 4168updated version of the Document. 4169 4170 4171File: gnash_ref.info, Node: 4_ MODIFICATIONS, Next: 5_ COMBINING DOCUMENTS, Prev: 3_ COPYING IN QUANTITY, Up: GNU Free Documentation License 4172 4173A.5 4. MODIFICATIONS 4174==================== 4175 4176You may copy and distribute a Modified Version (*note fdl-modified::) 4177of the Document (*note fdl-document::) under the conditions of sections 41782 (*note 2_ VERBATIM COPYING::) and 3 (*note 3_ COPYING IN QUANTITY::) 4179above, provided that you release the Modified Version under precisely 4180this License, with the Modified Version filling the role of the 4181Document, thus licensing distribution and modification of the Modified 4182Version to whoever possesses a copy of it. In addition, you must do 4183these things in the Modified Version: 4184 4185 * *A. * Use in the Title Page (*note fdl-title-page::) (and on the 4186 covers, if any) a title distinct from that of the Document (*note 4187 fdl-document::), and from those of previous versions (which 4188 should, if there were any, be listed in the History section of the 4189 Document). You may use the same title as a previous version if the 4190 original publisher of that version gives permission. 4191 4192 * *B. * List on the Title Page (*note fdl-title-page::), as authors, 4193 one or more persons or entities responsible for authorship of the 4194 modifications in the Modified Version (*note fdl-modified::), 4195 together with at least five of the principal authors of the 4196 Document (*note fdl-document::) (all of its principal authors, if 4197 it has less than five). 4198 4199 * *C. * State on the Title Page (*note fdl-title-page::) the name of 4200 the publisher of the Modified Version (*note fdl-modified::), as 4201 the publisher. 4202 4203 * *D. * Preserve all the copyright notices of the Document (*note 4204 fdl-document::). 4205 4206 * *E. * Add an appropriate copyright notice for your modifications 4207 adjacent to the other copyright notices. 4208 4209 * *F. * Include, immediately after the copyright notices, a license 4210 notice giving the public permission to use the Modified Version 4211 (*note fdl-modified::) under the terms of this License, in the 4212 form shown in the Addendum below. 4213 4214 * *G. * Preserve in that license notice the full lists of Invariant 4215 Sections (*note fdl-invariant::) and required Cover Texts (*note 4216 fdl-cover-texts::) given in the Document's (*note fdl-document::) 4217 license notice. 4218 4219 * *H. * Include an unaltered copy of this License. 4220 4221 * *I. * Preserve the section entitled "History", and its title, and 4222 add to it an item stating at least the title, year, new authors, 4223 and publisher of the Modified Version (*note fdl-modified::)as 4224 given on the Title Page (*note fdl-title-page::). If there is no 4225 section entitled "History" in the Document (*note fdl-document::), 4226 create one stating the title, year, authors, and publisher of the 4227 Document as given on its Title Page, then add an item describing 4228 the Modified Version as stated in the previous sentence. 4229 4230 * *J. * Preserve the network location, if any, given in the Document 4231 (*note fdl-document::) for public access to a Transparent (*note 4232 fdl-transparent::) copy of the Document, and likewise the network 4233 locations given in the Document for previous versions it was based 4234 on. These may be placed in the "History" section. You may omit a 4235 network location for a work that was published at least four years 4236 before the Document itself, or if the original publisher of the 4237 version it refers to gives permission. 4238 4239 * *K. * In any section entitled "Acknowledgements" or "Dedications", 4240 preserve the section's title, and preserve in the section all the 4241 substance and tone of each of the contributor acknowledgements 4242 and/or dedications given therein. 4243 4244 * *L. * Preserve all the Invariant Sections (*note fdl-invariant::) 4245 of the Document (*note fdl-document::), unaltered in their text 4246 and in their titles. Section numbers or the equivalent are not 4247 considered part of the section titles. 4248 4249 * *M. * Delete any section entitled "Endorsements". Such a section 4250 may not be included in the Modified Version (*note fdl-modified::). 4251 4252 * *N. * Do not retitle any existing section as "Endorsements" or to 4253 conflict in title with any Invariant Section (*note 4254 fdl-invariant::). 4255 4256 If the Modified Version (*note fdl-modified::) includes new 4257front-matter sections or appendices that qualify as Secondary Sections 4258(*note fdl-secondary::) and contain no material copied from the 4259Document, you may at your option designate some or all of these 4260sections as invariant. To do this, add their titles to the list of 4261Invariant Sections (*note fdl-invariant::) in the Modified Version's 4262license notice. These titles must be distinct from any other section 4263titles. 4264 4265 You may add a section entitled "Endorsements", provided it contains 4266nothing but endorsements of your Modified Version (*note 4267fdl-modified::) by various parties-for example, statements of peer 4268review or that the text has been approved by an organization as the 4269authoritative definition of a standard. 4270 4271 You may add a passage of up to five words as a Front-Cover Text 4272(*note fdl-cover-texts::), and a passage of up to 25 words as a 4273Back-Cover Text (*note fdl-cover-texts::), to the end of the list of 4274Cover Texts (*note fdl-cover-texts::) in the Modified Version (*note 4275fdl-modified::). Only one passage of Front-Cover Text and one of 4276Back-Cover Text may be added by (or through arrangements made by) any 4277one entity. If the Document (*note fdl-document::) already includes a 4278cover text for the same cover, previously added by you or by 4279arrangement made by the same entity you are acting on behalf of, you 4280may not add another; but you may replace the old one, on explicit 4281permission from the previous publisher that added the old one. 4282 4283 The author(s) and publisher(s) of the Document (*note 4284fdl-document::) do not by this License give permission to use their 4285names for publicity for or to assert or imply endorsement of any 4286Modified Version (*note fdl-modified::). 4287 4288 4289File: gnash_ref.info, Node: 5_ COMBINING DOCUMENTS, Next: 6_ COLLECTIONS OF DOCUMENTS, Prev: 4_ MODIFICATIONS, Up: GNU Free Documentation License 4290 4291A.6 5. COMBINING DOCUMENTS 4292========================== 4293 4294You may combine the Document (*note fdl-document::) with other 4295documents released under this License, under the terms defined in 4296section 4 (*note 4_ MODIFICATIONS::) above for modified versions, 4297provided that you include in the combination all of the Invariant 4298Sections (*note fdl-invariant::) of all of the original documents, 4299unmodified, and list them all as Invariant Sections of your combined 4300work in its license notice. 4301 4302 The combined work need only contain one copy of this License, and 4303multiple identical Invariant Sections (*note fdl-invariant::) may be 4304replaced with a single copy. If there are multiple Invariant Sections 4305with the same name but different contents, make the title of each such 4306section unique by adding at the end of it, in parentheses, the name of 4307the original author or publisher of that section if known, or else a 4308unique number. Make the same adjustment to the section titles in the 4309list of Invariant Sections in the license notice of the combined work. 4310 4311 In the combination, you must combine any sections entitled "History" 4312in the various original documents, forming one section entitled 4313"History"; likewise combine any sections entitled "Acknowledgements", 4314and any sections entitled "Dedications". You must delete all sections 4315entitled "Endorsements." 4316 4317 4318File: gnash_ref.info, Node: 6_ COLLECTIONS OF DOCUMENTS, Next: 7_ AGGREGATION WITH INDEPENDENT WORKS, Prev: 5_ COMBINING DOCUMENTS, Up: GNU Free Documentation License 4319 4320A.7 6. COLLECTIONS OF DOCUMENTS 4321=============================== 4322 4323You may make a collection consisting of the Document (*note 4324fdl-document::) and other documents released under this License, and 4325replace the individual copies of this License in the various documents 4326with a single copy that is included in the collection, provided that 4327you follow the rules of this License for verbatim copying of each of the 4328documents in all other respects. 4329 4330 You may extract a single document from such a collection, and 4331distribute it individually under this License, provided you insert a 4332copy of this License into the extracted document, and follow this 4333License in all other respects regarding verbatim copying of that 4334document. 4335 4336 4337File: gnash_ref.info, Node: 7_ AGGREGATION WITH INDEPENDENT WORKS, Next: 8_ TRANSLATION, Prev: 6_ COLLECTIONS OF DOCUMENTS, Up: GNU Free Documentation License 4338 4339A.8 7. AGGREGATION WITH INDEPENDENT WORKS 4340========================================= 4341 4342A compilation of the Document (*note fdl-document::) or its derivatives 4343with other separate and independent documents or works, in or on a 4344volume of a storage or distribution medium, does not as a whole count 4345as a Modified Version (*note fdl-modified::) of the Document, provided 4346no compilation copyright is claimed for the compilation. Such a 4347compilation is called an "aggregate", and this License does not apply 4348to the other self-contained works thus compiled with the Document , on 4349account of their being thus compiled, if they are not themselves 4350derivative works of the Document. If the Cover Text (*note 4351fdl-cover-texts::) requirement of section 3 (*note 3_ COPYING IN 4352QUANTITY::) is applicable to these copies of the Document, then if the 4353Document is less than one quarter of the entire aggregate, the 4354Document's Cover Texts may be placed on covers that surround only the 4355Document within the aggregate. Otherwise they must appear on covers 4356around the whole aggregate. 4357 4358 4359File: gnash_ref.info, Node: 8_ TRANSLATION, Next: 9_ TERMINATION, Prev: 7_ AGGREGATION WITH INDEPENDENT WORKS, Up: GNU Free Documentation License 4360 4361A.9 8. TRANSLATION 4362================== 4363 4364Translation is considered a kind of modification, so you may distribute 4365translations of the Document (*note fdl-document::) under the terms of 4366section 4 (*note 4_ MODIFICATIONS::). Replacing Invariant Sections 4367(*note fdl-invariant::) with translations requires special permission 4368from their copyright holders, but you may include translations of some 4369or all Invariant Sections in addition to the original versions of these 4370Invariant Sections. You may include a translation of this License 4371provided that you also include the original English version of this 4372License. In case of a disagreement between the translation and the 4373original English version of this License, the original English version 4374will prevail. 4375 4376 4377File: gnash_ref.info, Node: 9_ TERMINATION, Next: 10_ FUTURE REVISIONS OF THIS LICENSE, Prev: 8_ TRANSLATION, Up: GNU Free Documentation License 4378 4379A.10 9. TERMINATION 4380=================== 4381 4382You may not copy, modify, sublicense, or distribute the Document (*note 4383fdl-document::) except as expressly provided for under this License. 4384Any other attempt to copy, modify, sublicense or distribute the 4385Document is void, and will automatically terminate your rights under 4386this License. However, parties who have received copies, or rights, 4387from you under this License will not have their licenses terminated so 4388long as such parties remain in full compliance. 4389 4390 4391File: gnash_ref.info, Node: 10_ FUTURE REVISIONS OF THIS LICENSE, Next: Addendum, Prev: 9_ TERMINATION, Up: GNU Free Documentation License 4392 4393A.11 10. FUTURE REVISIONS OF THIS LICENSE 4394========================================= 4395 4396The Free Software Foundation (http://www.gnu.org/fsf/fsf.html) may 4397publish new, revised versions of the GNU Free Documentation License 4398from time to time. Such new versions will be similar in spirit to the 4399present version, but may differ in detail to address new problems or 4400concerns. See http://www.gnu.org/copyleft/ 4401(http://www.gnu.org/copyleft). 4402 4403 Each version of the License is given a distinguishing version 4404number. If the Document (*note fdl-document::) specifies that a 4405particular numbered version of this License "or any later version" 4406applies to it, you have the option of following the terms and 4407conditions either of that specified version or of any later version 4408that has been published (not as a draft) by the Free Software 4409Foundation. If the Document does not specify a version number of this 4410License, you may choose any version ever published (not as a draft) by 4411the Free Software Foundation. 4412 4413 4414File: gnash_ref.info, Node: Addendum, Prev: 10_ FUTURE REVISIONS OF THIS LICENSE, Up: GNU Free Documentation License 4415 4416A.12 Addendum 4417============= 4418 4419To use this License in a document you have written, include a copy of 4420the License in the document and put the following copyright and license 4421notices just after the title page: 4422 4423 Copyright 2008, Free Software Foundation. 4424 4425 Permission is granted to copy, distribute and/or modify this 4426 document under the terms of the GNU Free Documentation License, 4427 Version 1.1 or any later version published by the Free Software 4428 Foundation; with noInvariant Sections (*note fdl-invariant::), 4429 with no Front-Cover Texts (*note fdl-cover-texts::), and with no 4430 Back-Cover Texts (*note fdl-cover-texts::). A copy of the license 4431 is included in the section entitled "GNU Free Documentation 4432 License". 4433 4434 If your document contains nontrivial examples of program code, we 4435recommend releasing these examples in parallel under your choice of 4436free software license, such as the GNU General Public License 4437(http://www.gnu.org/copyleft/gpl.html), to permit their use in free 4438software. 4439 4440 4441 4442Tag Table: 4443Node: Top168 4444Node: Introduction1821 4445Node: Audience2622 4446Node: What Is Supported ?2950 4447Node: Building from Source5482 4448Node: Overview5862 4449Node: Getting The Source6907 4450Node: Releases7113 4451Node: CVS Access7481 4452Node: Code Dependencies8193 4453Ref: Code Dependency Table8890 4454Node: Testing Dependencies34405 4455Ref: Testing Dependency Table34713 4456Node: Documentation Dependencies38637 4457Ref: Documentation Dependency Table38906 4458Node: Configuring Gnash47974 4459Node: Features50296 4460Ref: Configuration Options - Features50896 4461Node: Specifying Custom Paths57226 4462Ref: Custom Path Options57701 4463Node: Compiling the Code67371 4464Node: Creating the Documentation68312 4465Node: Running the Tests69648 4466Node: Using DejaGnu70093 4467Node: Increasing Verbosity70456 4468Node: Running Some Tests70992 4469Node: Running The Tests Manually71812 4470Node: Movie tests72474 4471Node: ActionScript Unit Tests72828 4472Node: Installation73145 4473Node: Libraries74421 4474Node: Executables75308 4475Node: Documentation76178 4476Node: Cross Configuring76933 4477Node: Software Internals80008 4478Node: A Tour of Gnash80279 4479Node: The Libraries80846 4480Node: libgnashbase81149 4481Node: libgnashgeo81573 4482Node: libgnashgui81788 4483Node: libgnashserver82057 4484Node: libgnashasobjs82428 4485Node: libgnashamf82664 4486Node: libgnashbackend83087 4487Node: libgnashplugin83402 4488Node: libklashpart83608 4489Node: The Applications83778 4490Node: The Standalone Player84145 4491Node: Gprocesser84443 4492Node: SOLdumper84837 4493Node: Dumpshm85104 4494Node: The Plugin85323 4495Node: Current Status85801 4496Node: GUI Support86359 4497Node: Mozplugger88040 4498Node: Klash89931 4499Node: The Debug Logging System90481 4500Node: Logging System C API92042 4501Node: Logging System C++ API94246 4502Node: Sound handling in Gnash96087 4503Node: Sound types96918 4504Node: Sound parsing97455 4505Node: Sound playback98023 4506Node: The SDL sound backend98553 4507Node: The Gstreamer backend99872 4508Node: Future audio backends100888 4509Node: Detailed description of the Gstreamer backend101378 4510Node: Testing103629 4511Node: Testing Tools104100 4512Node: Test Cases104932 4513Node: Writing ActionScript Tests105511 4514Node: Writing Ming-based self-contained SWF tests108014 4515Node: Using Ming-based test generators facilities109171 4516Node: Writing self-contained SWF tests with other compilers111531 4517Node: Writing Test Runners114624 4518Node: Using the generic test runner for self-contained SWF tests116373 4519Node: Writing Movie testers118462 4520Node: Adding New ActionScript Class120202 4521Node: Prototype121382 4522Node: Declaration122799 4523Node: Instantiation123064 4524Node: Methods123691 4525Node: Accessing Arguments124082 4526Node: Returning a Value to ActionScript124478 4527Node: Additional fn_call Members124857 4528Node: Dynamic Properties125711 4529Node: The as_value Object Type127216 4530Node: Data Types127654 4531Node: Determining the Type127975 4532Node: Fetching the Value128507 4533Node: Setting the Value and Type128997 4534Node: Further Reading129591 4535Node: Object ActionScript Class130006 4536Node: The Methods of the Class130346 4537Node: The Properties of the Object Class130685 4538Node: Object Class Conformance131000 4539Node: Gnash Extensions132539 4540Node: Creating A New Extension134813 4541Node: Crafting an Extension136229 4542Node: Debugging An Extension140533 4543Node: Included Extensions142225 4544Node: Gtk Extension142669 4545Node: File I/O Extension143656 4546Node: MySQL Extension144842 4547Node: RTMP Protocol145693 4548Node: AMF Format155489 4549Node: Mozilla/Firefox NSAPI Plugin156465 4550Node: Plugin C API157483 4551Node: Plugin C++ API159342 4552Node: OpenGL and Threads162606 4553Node: Plugin Event Handling163934 4554Node: Appendix164903 4555Node: Code Style165055 4556Node: Authors168885 4557Node: GNU Free Documentation License169581 4558Node: 0_ PREAMBLE170344 4559Node: 1_ APPLICABILITY AND DEFINITIONS171650 4560Ref: fdl-document171875 4561Ref: fdl-modified172166 4562Ref: fdl-secondary172353 4563Ref: fdl-invariant172998 4564Ref: fdl-cover-texts173247 4565Ref: fdl-transparent173460 4566Ref: fdl-title-page174750 4567Node: 2_ VERBATIM COPYING175139 4568Node: 3_ COPYING IN QUANTITY176119 4569Node: 4_ MODIFICATIONS178476 4570Node: 5_ COMBINING DOCUMENTS184536 4571Node: 6_ COLLECTIONS OF DOCUMENTS186033 4572Node: 7_ AGGREGATION WITH INDEPENDENT WORKS186924 4573Node: 8_ TRANSLATION188152 4574Node: 9_ TERMINATION189055 4575Node: 10_ FUTURE REVISIONS OF THIS LICENSE189710 4576Node: Addendum190850 4577 4578End Tag Table 4579 4580 4581Local Variables: 4582coding: US-ASCII 4583End: 4584