home *** CD-ROM | disk | FTP | other *** search
/ A.C.E. 1 / ACE CD 1.iso / files / utils / framema2.dms / in.adf / DEVELOPER / docs / lib.doc
Encoding:
Text File  |  1993-05-08  |  20.4 KB  |  651 lines
  1. /************************************************************************
  2.     Date        Who Comment
  3.     ---------------------------------------------------------------------
  4.     03-03-93    ds  2.0-Redesign
  5.  
  6.     06-03-93    ds  - Preview-Funktionen für ADLOAD, FM-MAIN
  7.                     - FORCE_720-Flag für PrepWrite (für ADSAVE, PSHOW)
  8.                     - CallBack-Hook für PlayEDAN
  9.                     - GUI-Programme kommen in CLI-Kommandos.
  10.                     - SnapShot()
  11.  
  12.     12-03-93    ds  - Query-Redesign: GetDisplayInfo(), SetDisplayInfo()
  13.  
  14.     27-04-93    ds  - PrepSavEDAN() - Flags (EDAN_RAM_BUFFER)
  15.  
  16. *************************************************************************/
  17.  
  18.  
  19.  
  20. /************************************************************************
  21.  
  22.  Display-Related functions:
  23.  
  24. *************************************************************************/
  25.  
  26. -----------------------------------------------------------------------------
  27.  
  28. WORD DisplaySize(UWORD size_mode);
  29.     set size of display:
  30.     size_mode:
  31.         PDP_720
  32.         PDP_360
  33.         PDP_270
  34.         PDP_180
  35.         PDP_120
  36.         PDP_90
  37.  
  38.     width:  actual width in pixels
  39.     height: actual height in lines
  40.  
  41. -----------------------------------------------------------------------------
  42.  
  43. WORD DisplayPos(WORD *x, WORD *y);
  44.     set Display-position (relative to WB-Screen) for current DisplaySize.
  45.     X/Y: Pointers (!) to the position.
  46.  
  47.     Note:
  48.         It is not possible to position the display everywhere you want.
  49.         As of the current hardware-implementation, you could position the window
  50.         vertically an very scanline, but horizontally only on every 4th
  51.         position.  Unfortunately, Position 0 does not correspond with the
  52.         hardware-intern position 0 (which is right after the
  53.         Vertical-Blanking-Interrupt).  So depending on the Users position
  54.         of the WB-Screen, it may or it may not be possible to position the
  55.         Display on 0/0.  The software will move the display to the next
  56.         possible position on the right. Worst case your position is 3 Pixels
  57.         right from where you expected it.
  58.         The position is returned, which is why you have to pass pointers.
  59.  
  60.  
  61.  
  62.     Note: changing the position for DisplaSize 720 is impossible
  63.  
  64.     Returns: STATUS
  65.  
  66. -----------------------------------------------------------------------------
  67.  
  68. WORD DisplayMode(  UWORD mode, UWORD keymode);
  69.     set display-mode
  70.     flags:
  71.         PDP_OFF         Prisma OFF
  72.         PDP_AMIGA       Amiga only
  73.         PDP_PRISMA      Prisma only
  74.         PDP_PRISMA_KEY  Prisma ON, Amiga ON, keying according to keymode
  75.  
  76.     keymode:
  77.         number of keymode
  78.  
  79.     Note: Before setting the mode, this functions checks wether this mode
  80.           is allowed with the current Prefrences. E.g. PDP_OFF on
  81.           Mono-Monitor-Systems is not allowed. For safety reasons, it is NOT
  82.           possible to override.
  83.  
  84.     Returns: STATUS
  85.  
  86. WORD   QuerySize(WORD size, UWORD *width, UWORD *height)
  87.     Returns the width/height of a given DisplaySize
  88.  
  89.     size:   Size you are interested in (e.g. PDP_720) or -1 for current size;
  90.     width:  Pointer to UWORD where requested width is returned (or NULL)
  91.     height: Pointer to UWORD where requested width is returned (or NULL)
  92.     
  93.     Note:   The Height is measured in LACE, that means if you want to
  94.             open a window on a non-lace screen to cover the Display,
  95.             you have to divide it by two!
  96.  
  97.  
  98. WORD   GetDisplayInfo(struct FMDisplayInfo *info)
  99.     Copys the current Display-Settings in your structure
  100.  
  101.     info: Pointer to your DisplayInfo-buffer
  102.  
  103. WORD   SetDisplayInfo(struct FMDisplayInfo *info)
  104.     Sets the display to the parameters given in your DisplayInfo-Structure.
  105.     Useful for setting all parameters (size, mode, keymode, xpos, ypos) all
  106.     at once.
  107.  
  108.     info: Pointer to your DisplayInfo
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115. /************************************************************************
  116.  
  117.     RGB->YUV related functions (Showing RGB-Images on Prism-Display)
  118.  
  119. *************************************************************************/
  120.  
  121. -----------------------------------------------------------------------------
  122.  
  123. WORD   PrepWrite(  UWORD width, height, UWORD flags,
  124.                      UBYTE *rlut, UBYTE *glut, UBYTE *blut)
  125.  
  126.     Prepares a line-by-line transfer of Image-Data to display.
  127.     DisplaySize will be adjusted to the Image.
  128.     width/height:
  129.         size of image to be transfered
  130.     flags:
  131.         WRITE_COLOR:  the image is an RGB24-Colored image. Must
  132.                       be transfered via WriteRGB24Line()-calls
  133.  
  134.         WRITE_BW:     the image is 8-Bit-Grey-Scale - Image Must
  135.                       be transfered via WriteBW8Line()-calls
  136.  
  137.         WRITE_NO_422: Do not use 422-Mode.
  138.  
  139.         WRITE_FORCE_720:
  140.                     DisplaySize will always be 720x585, regardless
  141.                     of Image-Size. Smaler images will appear centered
  142.                     on the display.
  143.  
  144.  
  145.     rlut, glut, blut:
  146.                     Pointer to Look-Up-Table for Red/Green/Blue
  147.                     the look-up-tables are organized as
  148.                     UBYTE rlut[256]
  149.                     UBYTE glut[256]
  150.                     UBYTE blut[256]
  151.                     If you don't want to use LUTs, pass NULL-Pointers
  152.                     For BW-Images, the look-up-table is passed in the
  153.                     rlut-pointer
  154.  
  155.     Note: It is *NOT* safe to call any other prisma-function except
  156.           WriteRGB24Line(), WriteBW8Line() until an
  157.           EndWrite()-Call indicates end of transfer.
  158.           Each PrepWrite() must be followed by an EndWrite()
  159.  
  160. -----------------------------------------------------------------------------
  161.  
  162. WORD   WriteRGB24Line(UBYTE *r, UBYTE *g, UBYTE *b)
  163.     Transfers one line of RGB-Data to the display. The line will appear
  164.     immediatley on the display.
  165.  
  166.     r/g/b   Pointer to array containing Red, Green, Blue, organized as
  167.             UBYTE red_array[width]
  168.             UBYTE green_array[width]
  169.             UBYTE blue_array[width]
  170.  
  171.     Note: before calling this function, you must do a PrepWrite() with
  172.           the correct size. This functions does not check wether the given
  173.           buffers are valid, so be careful.
  174.  
  175.     Returns: STATUS
  176.  
  177. -----------------------------------------------------------------------------
  178.  
  179. WORD   WriteBW8Line(UBYTE *bw_line)
  180.     Transfers one line of RGB-Data to the display. The line will appear
  181.     immediatley on the display.
  182.  
  183.     bw_line Pointer to array containing BW-8-Bit data organized as
  184.             UBYTE bw_line[width]
  185.  
  186.     Note: before calling this function, you must do a PrepWrite() with
  187.           the correct size. This functions does not check wether the given
  188.           buffers are valid, so be careful.
  189.  
  190.     Returns: STATUS
  191.  
  192. -----------------------------------------------------------------------------
  193.  
  194. WORD   EndWrite()
  195.     Indicates that you have finished to transfer the image to the display
  196.     If this occures before the with PrepWrite() given numbers of lines
  197.     were written to the display, the rest will be filled with black lines.
  198.  
  199. -----------------------------------------------------------------------------
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211. /************************************************************************
  212.  
  213.     YUV->RGB related functions (Getting RGB-Images from Display)
  214.  
  215. *************************************************************************/
  216.  
  217. -----------------------------------------------------------------------------
  218.  
  219. WORD   PrepRead( UWORD width, height, UWORD flags)
  220.  
  221.     Prepares a line-by-line transfer of YUV-RAM to your buffer.
  222.     width/height:
  223.         size of image to be transfered
  224.         The image you get is always the center.
  225.  
  226.     flags:
  227.         READ_COLOR: the image is an RGB24-Colored image. Must
  228.                     be transfered via ReadRGB24Line()-calls
  229.  
  230.         READ_BW:    the image is 8-Bit-Grey-Scale - Image Must
  231.                     be transfered via ReadBW8Line()-calls
  232.  
  233.         READ_FIRST:
  234.         READ_SECOND:
  235.                     When DisplaySize is < PDP_720, you can determine
  236.                     which half-frame you'd like to read: the first one    
  237.                     or the second one. Default is READ_FIRST.
  238.  
  239.     Note: When Prism24 is attached, the Display will switch to
  240.           PDP_AMIGA-Mode until EndRead().
  241.  
  242.     Note: When DisplaySize is PDP_720 and you specify a width < 360,
  243.           every second pixel from Display will be skipped.
  244.  
  245.     Note: It is *NOT* safe to call any other prisma-function except
  246.           ReadRGB24Line(), ReadBW8Line() until an
  247.           EndWrite()-Call indicates end of transfer.
  248.           Each PrepRead() must be followed by an EndRead()
  249.  
  250. -----------------------------------------------------------------------------
  251.  
  252. WORD   ReadRGB24Line(UBYTE *r, UBYTE *g, UBYTE *b)
  253.     Transfers one line of RGB-Data to the buffer
  254.  
  255.     r/g/b   Pointer to array containing Red, Green, Blue, organized as
  256.             UBYTE red_array[width]
  257.             UBYTE green_array[width]
  258.             UBYTE blue_array[width]
  259.  
  260.     Note: before calling this function, you must do a PrepRead() with
  261.           the correct size. This functions does not check wether the given
  262.           buffers are valid, so be careful.
  263.  
  264.     Returns: STATUS
  265.  
  266. -----------------------------------------------------------------------------
  267.  
  268. WORD   ReadBW8Line(UBYTE *bw_line)
  269.     Transfers one line of RGB-Data to the buffer. The buffer ***MUST***
  270.     be large enough to fit one line, elsehwile you'll get heavy explosions!!!
  271.  
  272.     bw_line Pointer to array containing BW-8-Bit data organized as
  273.             UBYTE bw_line[width]
  274.  
  275.     Note: before calling this function, you must do a PrepRead() with
  276.           the correct size. This functions does not check wether the given
  277.           buffers are valid, so be careful.
  278.  
  279.     Returns: STATUS
  280.  
  281. -----------------------------------------------------------------------------
  282.  
  283. WORD   EndRead()
  284.     Indicates that you have finished to transfer the image to the buffer
  285.  
  286. -----------------------------------------------------------------------------
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297. /************************************************************************
  298.  
  299.  Loading files / EDAN-File-Handling
  300.  
  301. *************************************************************************/
  302.  
  303. -----------------------------------------------------------------------------
  304.  
  305. WORD   LoadFile(UBYTE *fname, UWORD flags)
  306.     Displays the given file on the Prisma-Display. Supported formats:
  307.     ILBM, RGB8, YUVN, EDAN
  308.  
  309.     fname: Pointer to filename
  310.  
  311.     flags: see PrepWrite()
  312.  
  313.     Note: when file-format is EDAN, only the first frame will be displayed
  314.  
  315. -----------------------------------------------------------------------------
  316.  
  317. WORD   PlayEDAN(UBYTE *fname, LONG (*frame_hook)())
  318.     Plays an EDAN-Animation
  319.     fname:
  320.         filename
  321.  
  322.     frame_hook:
  323.         To controll flow and speed of Animation, pass a pointer to
  324.         a function. This function can controll speed by delaying and
  325.         flow be specifing next frame.
  326.  
  327.         The function gets parameters in registers:
  328.         D0: UWORD current_frame (0 for first frame)
  329.         D1: UWORD num_of_frames
  330.  
  331.         Returns in D0 a long-word containing the number
  332.         of the next frame to be displayed. 0 for first frame, num_of_frames-1
  333.         for last frame. If the number is negative (<0) or >=num_if:frames,
  334.         playing will be stopped. The function is called the first time before
  335.         the first frame
  336.  
  337.         If you pass a NULL-Pointer, the Animation will be played one time
  338.         full speed.
  339.  
  340.  
  341.  
  342.  
  343. -----------------------------------------------------------------------------
  344.  
  345. WORD PrepLoadEDAN(UBYTE *fname, UWORD flags)
  346.     Prepares an EDAN-File for frame-by-frame display.
  347.     The file is opend and the display set accordingly, but NO frame
  348.     is shown. Do view the first frame, use FirstFrame()
  349.  
  350.     fname:
  351.         Filename of EDAN-File
  352.  
  353.     flags:
  354.         EDAN_RAM_BUFFER *** NOT YET IMPLEMENTED ***
  355.           Load ALL Frames AT ONCE into memory.
  356.  
  357.         EDAN_ORIGINAL_POS
  358.           Position Display at Original Position
  359.  
  360.  
  361.  
  362. -----------------------------------------------------------------------------
  363.  
  364. WORD   QueryEDAN(struct EDANInfo *info)
  365.     fills out the given buffer with some informations of File loaded/saved.
  366.     Must be called after PrepLoadEDAN() / PrepSaveEDAN() and before
  367.     EndLoadEDAN()/EndSaveEDAN()
  368.  
  369. -----------------------------------------------------------------------------
  370.  
  371. WORD   NextFrame()
  372.     Displays the next frame of an EDAN-Sequence.
  373.  
  374.     returns:
  375. -----------------------------------------------------------------------------
  376.  
  377. WORD   PreviousFrame()
  378.     Displays the next frame of an EDAN-Sequence.
  379.  
  380.     returns:
  381.  
  382. -----------------------------------------------------------------------------
  383.  
  384. WORD   FirstFrame()
  385.     Displays the first frame of an EDAN-Sequence.
  386.  
  387. -----------------------------------------------------------------------------
  388.  
  389. WORD   LastFrame()
  390.     Displays the last frame of an EDAN-Sequence.
  391.  
  392. -----------------------------------------------------------------------------
  393.  
  394. WORD   GotoFrame(UWORD n)
  395.     Displays the n-th frame of an EDAN-Sequence. 0 is the first on
  396.  
  397. -----------------------------------------------------------------------------
  398.  
  399. WORD EndLoadEDAN()
  400.     Closes the file after loading
  401.  
  402. -----------------------------------------------------------------------------
  403.  
  404. WORD   PrepSaveEDAN(UBYTE *fname, WORD nf, UWORD flags)
  405.     Prepares the frame-by-frame-saving of EDAN-sequences.
  406.  
  407.     fname: Name of File
  408.  
  409.     nf:    Number of Frames. -1 if you don't know how many frames you're going
  410.            to save.
  411.  
  412.     flags:
  413.            EDAN_BW:
  414.             Record Black&White
  415.  
  416.            EDAN_COLOR:
  417.             Record full color resolution
  418.  
  419.            EDAN_LACE:
  420.             When size==PDP_720, you can record lace if you wish.
  421.             size<PDP_720 is always NON-LACE
  422.  
  423.            EDAN_RAM_BUFFER: (NOT YET IMPLEMENTED)
  424.             The frames will be bufferd in RAM until EndSaveEDAN is called.
  425.             Then they are written to the file.  You MUST specifiy the number of
  426.             frames as the buffers are right away allocated. Function will fail
  427.             if not enough RAM is available.
  428.  
  429.            EDAN_NO_SYNC:    (NOT YET IMPLEMENTED)
  430.             Disables Frame-Sync while recording. Useful for saving
  431.             a frame which was e.g. SnapShot()ed or loaded.
  432.  
  433.     Note:   This size of EDAN will be current DisplaySize. Don't forget
  434.             to activate the Digitizer before recording. DONT'T CHANGE DISPLAYSIZE
  435.             WHILE RECORDING!
  436.  
  437.  
  438. -----------------------------------------------------------------------------
  439.  
  440. WORD   RecordFrame(VOID)
  441.     Saves the currently displayed frame to the file.
  442.     Don't forget to call EndSaveEDAN() when you're done.
  443.  
  444. -----------------------------------------------------------------------------
  445.  
  446. WORD EndSaveEDAN()
  447.  
  448. -----------------------------------------------------------------------------
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459. /************************************************************************
  460.  
  461.  Preview-Related-Functions:
  462.  
  463. *************************************************************************/
  464.  
  465. WORD   FastPreview(UWORD mode)
  466.     Opens a new screen and shows preview on it, until user
  467.     interrupts by pressing mousbutton or key. After breaking, the
  468.     next frame will be stored in full resolution (720x585) in YUV-RAM.
  469.  
  470.     Mode:           Display:        Screen:
  471.     MD_QUATER       160x128         320x256
  472.     MD_LORES        320x256         320x256
  473.     MD_HIRES        640x256         640x256
  474.  
  475. WORD   FastPreviewBmap(struct BitMap *bmap, struct Window *win, UWORD mode)
  476.     Show Fast Preview on given screen
  477.     bmap:   Pointer to bmap. Bmap must be large enough to fit
  478.             the Display.
  479.  
  480.     win:    Pointer to window with an IDCMP-Port attached. Preview continues
  481.             until an IDCMP-Message on the IDCMP-Port is recieved.  There it
  482.             is important that you have a least one IDCMP_MOUSEBUTTONS,
  483.             IDCMP_MENUPICK or IDCMP_VANILLAKEY set.
  484.  
  485.     Mode:           Display:        Screen:
  486.     MD_QUATER       160x128         320x256
  487.     MD_LORES        320x256         320x256
  488.     MD_HIRES        640x256         640x256
  489.  
  490.     Note: This function renders directly into the bitmap.
  491.  
  492.  
  493. /************************************************************************
  494.  
  495.  Prefrences-Functions:
  496.  
  497. *************************************************************************/
  498.  
  499. -----------------------------------------------------------------------------
  500.  
  501. WORD    GetFMPrefs(struct FMPref *pref, UWORD size)
  502.     returns the current settings
  503.  
  504.  
  505. -----------------------------------------------------------------------------
  506.  
  507. WORD    GetSavedPrefs(struct FMPref *pref, UWORD size)
  508.     returns the settings saved in NVRAM
  509.  
  510. -----------------------------------------------------------------------------
  511.  
  512. WORD    GetDefaultPrefs(struct FMPref *pref, UWORD size)
  513.     returns default settings
  514.  
  515. -----------------------------------------------------------------------------
  516.  
  517. WORD    UsePrefs(struct FMPref *pref, UWORD size)
  518.     makes the given settings active
  519.  
  520. -----------------------------------------------------------------------------
  521.  
  522. WORD    SavePrefs(struct FMPref *pref, UWORD size)
  523.     stores the given settings in NVRAM
  524.  
  525. -----------------------------------------------------------------------------
  526.  
  527. WORD    GetInfo(struct FMInfo *info, UWORD size)
  528.     struct FMInfo
  529.     {
  530.         UWORD   fm_ver; /* FrameMachine-BaseBoard-version  */
  531.         UWORD   fm_rev; /* FrameMachine-BaseBoard-revision  */
  532.  
  533.         UWORD   pm_ver; /* Prism-Board-version      */
  534.         UWORD   pm_rev; /* Prism-Board-revision     */
  535.  
  536.         UWORD   xil_ver;    /* Xilinx-File-version  */
  537.         UWORD   xil_rev;    /* Xilinx-File-revision */
  538.  
  539.         UWORD   lib_ver;    /* Library-Version      */
  540.         UWORD   liv_rev;    /* Library-Revision     */
  541.  
  542.     }
  543.  
  544. -----------------------------------------------------------------------------
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561. /************************************************************************
  562.  
  563.  MISC-Functions:
  564.  
  565. *************************************************************************/
  566.  
  567. -----------------------------------------------------------------------------
  568.  
  569. UBYTE *ExplainStatus(WORD status)
  570.     Return pointer to a zero-terminated string explaining the given
  571.     error-condition.
  572.  
  573.     status:
  574.         Error-Code returned by any prisma.library-funtion
  575.  
  576. -----------------------------------------------------------------------------
  577. VOID    DisplayStatus(WORD  status)
  578.     Pops up a little AutoRequest() explaining the error-condition to the
  579.     User.
  580.  
  581.     status:
  582.         Error-Condition from framemachine.library
  583.  
  584. -----------------------------------------------------------------------------
  585.  
  586. VOID    LockFM()
  587.     Gives you exclusive access to framemacine. If the machine
  588.     is currently locked by someone else, this function will wait for it to be
  589.     released. Nesting allowed.
  590.  
  591. -----------------------------------------------------------------------------
  592.  
  593. WORD    TryLockFM()
  594.     Trys to gain a lock on framemachine. If the machine is currently
  595.     locked by someone else, this function returns ERR_LOCKED. Use
  596.     WhoLocksFM() the get the name of the Task who as locked framemachine
  597.  
  598. WORD    UnLockFM()
  599.     Releases lock on fm gained be LockFM() or TryLockFM(). Nesting allowed
  600.  
  601. -----------------------------------------------------------------------------
  602.  
  603. UBYTE*  WhoLocksFM()
  604.  
  605.     Returns a pointer to a zero-terminated string containing the tasks name
  606.     currently locking framemachine. NULL if nobodys locking it.
  607.  
  608. -----------------------------------------------------------------------------
  609.  
  610. BOOL    PrismAttached()
  611.     Returns TRUE if Prism-Board is attached, else FALSE
  612.  
  613. -----------------------------------------------------------------------------
  614.  
  615. LONG QueryFlags()
  616.     flag-definitions see top of file
  617.  
  618. -----------------------------------------------------------------------------
  619.  
  620. WORD DigiState(BOOL on)
  621.     activate/deactivate digitzer. when activating the digitizer, the currently
  622.     display image will be destroyed.
  623.  
  624. -----------------------------------------------------------------------------
  625.  
  626. WORD SnapShot()
  627.     the next reachable frame is stored in full resolution in YUV-RAM.
  628.     DigiState is changed to FALSE. DisplaySize is changed to PDP_720.
  629.  
  630. -----------------------------------------------------------------------------
  631.  
  632. WORD   ClearDisplay()
  633.     Clears the display to black
  634.  
  635. -----------------------------------------------------------------------------
  636.  
  637. WORD    SendI2C(UBYTE *table, UWORD size)
  638.     Send several bytes on I2C-Bus (including Feature-Connector)
  639.  
  640.     table:  Pointer to array of UBYTEs of a least size-bytes
  641.     size:   size of array
  642.  
  643.     Note:   Using this function with the wrong values is critical.
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.