home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 1 / Mecomp-CD.iso / amiga / datatypes / film_datatype / film.datatype.doc < prev    next >
Text File  |  1997-04-18  |  17KB  |  456 lines
  1. TABLE OF CONTENTS
  2.  
  3. film.datatype/--datasheed--
  4. film.datatype/--input_format--
  5. film.datatype/ADTM_LOADFRAME
  6. film.datatype/ADTM_UNLOADFRAME
  7. film.datatype/DTM_FRAMEBOX
  8. film.datatype/DTM_WRITE
  9. film.datatype/GM_LAYOUT
  10. film.datatype/OM_DISPOSE
  11. film.datatype/OM_NEW
  12. film.datatype/preferences
  13. film.datatype/--datasheed--                       film.datatype/--datasheed--
  14.  
  15.    NAME
  16.        film.datatype -- data type for IFF FILM movies
  17.  
  18.    SUPERCLASS
  19.        animation.datatype
  20.  
  21.    DESCRIPTION
  22.        The film datatype, a sub-class of the animation.datatype, is
  23.        used load and play IFF FILM movies.
  24.  
  25.    METHODS
  26.        OM_NEW -- Create a new animation object from a description file. The
  27.            source may only be a file.
  28.  
  29.        OM_DISPOSE -- Dispose instance and contents (frames, colormaps,
  30.            sounds etc.), then pass msg to superclass
  31.  
  32.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  33.            method will be executed like OM_SET downstairs.
  34.  
  35.        OM_SET -- Pass msg to superclass and call GM_RENDER if retval from
  36.            superclass was != 0UL.
  37.  
  38.        GM_LAYOUT 
  39.        DTM_PROCLAYOUT -- Collect information from superclass, set up
  40.            struct DTSpecialInfo and send an OM_NOTIFY containing usefull
  41.            attributes.
  42.  
  43.        DTM_FRAMEBOX -- Set up object for a specified environment if
  44.            FRAMEF_SPECIFY was set in (dtf -> dtf_FrameFlags).
  45.  
  46.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  47.            from internal FrameNode list like bitmap, colormap and sound.
  48.  
  49.        ADTM_UNLOADFRAME -- Release resources obtained by ADTM_LOADFRAME like
  50.            bitmaps, colormaps etc.
  51.  
  52.        DTM_WRITE -- Save data in local (IFF FILM) or superclass (IFF ILBM)
  53.            format.
  54.  
  55.        All other methods are passed unchanged to superclass.
  56.  
  57.    ATTRIBUTES
  58.        Following attributes are set by the object and are READ-ONLY for
  59.        applications:
  60.        DTA_ObjName       -- reserved
  61.        DTA_ObjAuthor     -- reserved
  62.        DTA_ObjAnnotation -- reserved
  63.        DTA_ObjCopyright  -- reserved
  64.        DTA_ObjVersion    -- reserved
  65.        DTA_NominalVert   -- same as ADTA_Width
  66.        DTA_NominalHoriz  -- same as ADTA_Height
  67.        ADTA_Width        -- Set by ILBM BitMapHeader
  68.        ADTA_Height       -- Set by ILBM BitMapHeader
  69.        ADTA_Depth        -- Set by ILBM BitMapHeader
  70.  
  71.    BUGS
  72.        - In large videos, the frames at the end will be played slower than
  73.          those at the beginning of the file. This is the result of the
  74.          sequential search internally used (only serious with more than 25000
  75.          frames (mc6030/50mhz)).
  76.          May or may not be fixed.
  77.  
  78.        - Currently, after a full playback mainly all frames are cached
  79.          because animation.datatype does not flush enougth frane during
  80.          playback. This is not a bug of animation.datatype. I don't know that
  81.          return codes of the ADTM_LOADFRAME method which causes
  82.          animation.datatype to flush unused frames. Without information from
  83.          CBM, Amiga Technologies or David Junod I cannot fix this bug.
  84.          Comments welcome !
  85.  
  86.    TODO
  87.  
  88.    HISTORY
  89.        V1.1
  90.          First public release.
  91.  
  92.        V1.2
  93.          - Implemented relative seeking, which speeds up loading.
  94.  
  95.          - Moved and removed some bounds checking code in the ILBM BODY
  96.            loader.
  97.  
  98.          - Moved, removed and new code: Small cleanup.
  99.  
  100.          - Now supports a prefs file.
  101.  
  102.          - If a ILBM CAMG-Chunks is missing in the movie and no MODEID
  103.            option was set, BestModeID is used to get the best matching
  104.            screen mode.
  105.  
  106.        V1.3
  107.          - Now uses interleaved bitmaps for faster loading.
  108.  
  109.          - Small code cleanup.
  110.  
  111.        V1.4
  112.          - Recompiled with SAS/C 6.57.
  113.  
  114.          - Fixed a small mistake in the template, which may cause crashes
  115.            or other things (not seen, but...).
  116.  
  117.          - Implemented VERBOSE prefs switch (verbose information).
  118.  
  119.          - Stack check included. Forces a stack size of 16KB.
  120.  
  121.          - Implemented LOADALL prefs switch (load all frames into memory).
  122.  
  123.        V1.5
  124.          - Now supports IFF ILBM CMAPs in the CAT CELLs (dynamic palette
  125.            changes), which are supported by animation.datatype V41 or
  126.            "DBufDTAnim".
  127.  
  128.          - Uses OpenFromLock when obtaining a fh for random frame access.
  129.            This allows the usage of "virtual filesystems" (datatypes.library
  130.            V45 allows such things).
  131.  
  132.          - Now the high order bits of each color gun are replicated through 
  133.            the whole INT32 in the colormap.
  134.  
  135.          - Now uses EXPERIMENTAL stack swapping code. The "Need more stack"
  136.            requester has been gone for this reason.
  137.  
  138.          - Fixed a bug in LibExpunge (didn't check lib_OpenCnt), which is
  139.            also present in all my other external BOOSI classes (and
  140.            datatypes).
  141.            Thanks to Guenter Niki (gniki@informatik.uni-rostok.de) for
  142.            reporting this bug.
  143.  
  144.          - Now supports saving in the local format (e.g. IFF FILM).
  145.            Note that saveing begins with the __current__ frame and can be
  146.            controlled with the ADTA_Frame, ADTA_Frames and 
  147.            ADTA_FrameIncrement attributes.
  148.  
  149.          - Now support DTST_RAM (creates an empty film.datatype object).
  150.  
  151.          - Now supports subclasses of film.datatype, mainly to fill in
  152.            the ADTM_LOADFRAME/ADTM_UNLOADFRAME methods when using an empty
  153.            (e.g. created with DTST_RAM) film.datatype object.
  154.  
  155.    NOTES
  156.  
  157.    SEE ALSO
  158.        animation.datatype,
  159.        mpegsystem.datatype, mpegvideo.datatype,
  160.        picmovie.datatype,
  161.        cdxl.datatype. avi.datatype, quicktime.datatype,
  162.        directory.datatype,
  163.        markabletextdtclass
  164.  
  165. film.datatype/--input_format--                 film.datatype/--input_format--
  166.  
  167.     NAME
  168.         IFF FILM -- ILBM frames with interleaved 8SVX samples
  169.  
  170.     DESCRIPTION
  171.         A IFF FILM stream contains uncompressed video and audio data.
  172.         The LIST section contains a ILBM part and a 8SVX part, which
  173.         must contain a ILBM BMHD (BitMapHeader), a ILBM CMAP
  174.         (global colormap), a ILMB CAMG (amiga view mod id) and a 8SVX VHDR
  175.         (VoiceHeader). Other information (like a 8SVX CHAN chunk are
  176.         optional).
  177.  
  178.         After this "header" part, the single animation frames will follow.
  179.         A "frame" consists of a CAT CELL, which contains the video (FORM ILBM
  180.         BODY) and audio (FORM 8SVX BODY) data; a ILBM CMAP is optional when 
  181.         palette changes occurs.
  182.         Each ILBM/8SVX BODY must have exactly the same size, and as a result,
  183.         all CELLs have the same size (usefull for continous reading).
  184.  
  185.         Example (created with "sift"):
  186.         . LIST 736892 FILM
  187.         . . PROP 100 ILBM          ; shared ILBM properties
  188.         . . . BMHD 20 ILBM
  189.         . . . CAMG 4 ILBM
  190.         . . . CMAP 48 ILBM
  191.         . . PROP 44 8SVX           ; shared 8SVX properties
  192.         . . . VHDR 20 8SVX
  193.         . . . CHAN 4 8SVX
  194.         . . CAT  16000 CELL        ; 1st cell (frame of movie)
  195.         . . . FORM 14532 ILBM
  196.         . . . . BODY 14520 ILBM    ;   ILBM BitMap data
  197.         . . . FORM 1448 8SVX
  198.         . . . . BODY 1436 8SVX     ;   8SVX Sample data
  199.         . . CAT  16000 CELL        ; 2nd cell
  200.         . . . FORM 14532 ILBM
  201.         . . . . BODY 14520 ILBM    ;   ILBM BitMap data
  202.         . . . FORM 1448 8SVX
  203.         . . . . BODY 1436 8SVX     ;   8SVX Sample data
  204.         . . CAT  16000 CELL        ; 3rd cell
  205.         . . . FORM 14532 ILBM
  206.         . . . . BODY 14520 ILBM    ;   ILBM BitMap data
  207.         . . . FORM 1448 8SVX
  208.         . . . . BODY 1436 8SVX     ;   8SVX Sample data
  209.         and so on....
  210.  
  211.     SEE ALSO
  212.         - AminetCD2:gfx/show/AGMSFilm2.LhA, which includes a much better
  213.           description, the history and background of the IFF FILM format.
  214.  
  215.         - Aminet:gfx/conv/DumpDTAnim#?.LhA as an implementation of an
  216.           IFF FILM writer
  217.  
  218.         - ARKM Devices: IFF part
  219.  
  220.         - iffparse.library autodocs
  221.  
  222. film.datatype/ADTM_LOADFRAME                     film.datatype/ADTM_LOADFRAME
  223.  
  224.     NAME
  225.         ADTM_LOADFRAME -- Load frame
  226.  
  227.     FUNCTION
  228.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  229.         data of the animation.
  230.         The given timestamp will be used to find a matching timestamp
  231.         in the internal FrameNode list. If it was found, the corresponding
  232.         timing, bitmap, and sound data are stored into the struct
  233.         adtFrame. If the bitmap wasn't loaded, this method attempts to
  234.         load it from disk.
  235.  
  236.     RESULT
  237.         Returns always non-zero,
  238.         the bitmap ptr if a bitmap was found,
  239.         1UL otherwise.
  240.  
  241. film.datatype/ADTM_UNLOADFRAME                 film.datatype/ADTM_UNLOADFRAME
  242.  
  243.     NAME
  244.         ADTM_UNLOADFRAME -- Load frame contents
  245.  
  246.     FUNCTION
  247.         The ADTM_UNLOADFRAME method is used to release the contents of a
  248.         animation frame.
  249.  
  250.         This method frees the bitmap data found in adtFrame.
  251.  
  252.     RESULT
  253.         Returns always 0UL.
  254.  
  255. film.datatype/DTM_FRAMEBOX                         film.datatype/DTM_FRAMEBOX
  256.  
  257.     NAME
  258.         DTM_FRAMEBOX -- Set up object for a specified environment
  259.  
  260.     FUNCTION
  261.         The DTM_FRAMEBOX method is used to set up for a specified
  262.         environment. This method is passed to the superclass after
  263.         film.datatype instance finished it's work.
  264.  
  265.         Only if FRAMEF_SPECIFY is set in (dtf -> dtf_FrameFlags), the
  266.         film.datatype instance will modify the ADTA_Remap to FALSE if
  267.         the NOREMAP switch in the prefs file was set and the animation
  268.         depth matches the given (frameinfo -> fri_Screen -> BitMap . Depth)
  269.         depth.
  270.  
  271.     RESULT
  272.         The value from the superclass is returned.
  273.  
  274.     SEE ALSO
  275.         3.1_Examples2:DataTypes/Src/ClipView/clipview.c
  276.  
  277. film.datatype/DTM_WRITE                               film.datatype/DTM_WRITE
  278.  
  279.     NAME
  280.         DTM_WRITE -- Save data
  281.  
  282.     FUNCTION
  283.         This method saves the object's contents to disk.
  284.  
  285.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  286.         superclass, animation.datatype, which writes a single IFF ILBM
  287.         picture.
  288.  
  289.         If dtw_mode is DTWM_RAW, the object saved an IFF FILM stream to
  290.         the filehandle given, starting with the current frame until
  291.         the end is reached.
  292.         The sequence saved can be controlled by the ADTA_Frame, ADTA_Frames 
  293.         and ADTA_FrameIncrement attributes (see TAGS section below).
  294.  
  295.     TAGS
  296.         When writing the local ("raw") format, IFF FILM, the following
  297.         attributes are recognized:
  298.  
  299.         ADTA_Frame (ULONG) - start frame, saving starts here.
  300.             Defaults to the current frame displayed.
  301.  
  302.         ADTA_Frames (ULONG) - the number of frames to be saved,
  303.             Defaults to (max_num_of_frames - curr_frame).
  304.  
  305.         ADTA_FrameIncrement (ULONG) - frame increment when saving.
  306.             Defaults to 1, which means: "jump to next frame".
  307.  
  308.     BUGS
  309.         Any other ADTA_FrameIncrement value than 1 causes that
  310.         the sound of the skipped frames got lost. A recommened way would be
  311.         to append their sound to the next frame(s).
  312.  
  313.     RESULT
  314.         Returns 0 for failure (IoErr() returns result2), non-zero
  315.         for success.
  316.  
  317. film.datatype/GM_LAYOUT                               film.datatype/GM_LAYOUT
  318.  
  319.    NAME
  320.        GM_LAYOUT      -- Layout animation object
  321.        DTM_PROCLAYOUT -- Layout animation object on application's task
  322.  
  323.    FUNCTION
  324.        This method is passed to the superclass first.
  325.        Then it collects information from superclass, set up
  326.        struct DTSpecialInfo and send an OM_NOTIFY containing the following
  327.        attributes:
  328.        DTA_VisibleVert,   (DTA_Domain -> Height)
  329.        DTA_TotalVert,     (same as ADTA_Height)
  330.        DTA_NominalVert,   (same as ADTA_Height)
  331.        DTA_VertUnit,      1UL,
  332.        DTA_VisibleHoriz,  (DTA_Domain -> Width),
  333.        DTA_TotalHoriz,    (same as ADTA_Width),
  334.        DTA_NominalHoriz,  (same as ADTA_Width),
  335.        DTA_HorizUnit,     1UL,
  336.        GA_ID,             (GadgetID),
  337.        DTA_Title,         (same as DTA_Name),
  338.        DTA_Busy,          FALSE,
  339.        DTA_Sync,          TRUE
  340.  
  341.     RESULT
  342.         The value from the superclass is returned.
  343.  
  344. film.datatype/OM_DISPOSE                             film.datatype/OM_DISPOSE
  345.  
  346.     NAME
  347.         OM_DISPOSE -- Delete a film.datatype object.
  348.  
  349.     FUNCTION
  350.         The OM_DISPOSE method is used to delete an instance of the
  351.         film.datatype class. This method is pass to the superclass when
  352.         it has completed.
  353.         This method frees all frame nodes and their contents (bitmaps,
  354.         sounds etc.).
  355.  
  356.     RESULT
  357.         The object is deleted. 0UL is returned.
  358.  
  359. film.datatype/OM_NEW                                     film.datatype/OM_NEW
  360.  
  361.     NAME
  362.         OM_NEW -- Create a film.datatype object.
  363.  
  364.     FUNCTION
  365.         The OM_NEW method is used to create an instance of the film.datatype
  366.         class.  This method is passed to the superclass first. After this,
  367.         film.datatype parses the description file and makes a scan through
  368.         the data to get index information. The samples are loaded directly
  369.         (due their small size), frame bitmaps are loaded if the input
  370.         stream isn't seekable (e.g. IFF handle/clipboard).
  371.  
  372.     ATTRIBUTES
  373.         The following attributes can be specified at creation time.
  374.  
  375.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  376.             attribute. DTST_FILE, DTST_CLIPBOARD and DTST_RAM are supported.
  377.             If any other type was set in a given DTA_SourceType,
  378.             OM_NEW will be rejected.
  379.             Defaults to DTST_FILE.
  380.  
  381.         DTA_Handle -- For both supported DTST_FILE and DTST_CLIPBOARD, a
  382.             (struct IFFHandle *) is expected.
  383.             (DTST_FILE expects a IFF Stream handle because this is a IFF
  384.             type DataType (DTF_IFF)).
  385.             A DTST_RAM (create empty object) source type requires a NULL
  386.             handle.
  387.  
  388.     BUGS
  389.         Before V1.3, this autodoc described that a DTA_Handle with a
  390.         DTA_SourceType of DTST_FILE takes a DOS filehandle as an argument.
  391.         This was WRONG ! Because this is a DTF_IFF type datatype, DTST_FILE
  392.         takes also an IFF Stream handle as an argument.
  393.  
  394.     RESULT
  395.         If the object was created a pointer to the object is returned,
  396.         otherwise NULL is returned.
  397.  
  398. film.datatype/preferences                           film.datatype/preferences
  399.  
  400.    NAME
  401.        preferences
  402.  
  403.    DESCRIPTION
  404.        The "ENV:Classes/DataTypes/film.prefs" file contains global
  405.        settings for the datatype.
  406.        The preferences file is an ASCII file containing one line where the
  407.        preferences can be set.
  408.        It can be superset by a local variable with the same name.
  409.  
  410.        Each line can contain settings, special settings for some projects
  411.        can be set using the MATCHPROJECT option.
  412.        Lines beginning with a '#' or ';' chars are treated as comments.
  413.        Lines are limitted to 256 chars.
  414.  
  415.    TEMPLATE
  416.        MATCHPROJECT/K,MODEID/K/N,NOREMAP/S,FPS/K/N,VOLUME/K/N,LOADALL/S,
  417.        VERBOSE/S
  418.  
  419.        MATCHPROJECT -- The settings in this line belongs only to this
  420.            project(s), e.g. if the case-insensitive pattern does not match,
  421.            this line is ignored.
  422.            The maximum length of the pattern is 256 chars.
  423.            Defaults to #?, which matches any project.
  424.  
  425.        MODEID -- Select screen mode id of datatype (will be stored in
  426.            ADTA_ModeID). Note that the DOS ReadArgs function used for parsing
  427.            fetches a SIGNED long. The bit 31 will be represented by minus
  428.            '-'. (example: "MODEID=266240" sets the mode to the A2024 screen
  429.            mode id)
  430.            Defaults to 0, which means: Use the best screenmode available
  431.            for the given width, height and depth.
  432.  
  433.        FPS -- frames per second
  434.            Defaults to 0, which means: overtake fps rate from video stream.
  435.            Setting the FPS value also affects an attched sound. The period
  436.            of the sample (e.g. the playback speed) will everytimes as long
  437.            as the frame is displayed.
  438.  
  439.        VOLUME -- Volume of the sound when playing.
  440.            Defaults to 64, which is the maximum. A value greater than 64 will
  441.            be set to 64.
  442.  
  443.        LOADALL -- Load all frames into memory.
  444.  
  445.        VERBOSE -- Print out verbose information about the movie like
  446.            width, height, depth, number of frames, FPS-Rate etc.
  447.  
  448.    NOTE
  449.        An invalid prefs file line will be ignored.
  450.  
  451.    BUGS
  452.        - Low memory may cause that the prefs file won't be parsed.
  453.  
  454.        - Lines are limitted to 256 chars
  455.  
  456.