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