home *** CD-ROM | disk | FTP | other *** search
/ TopWare 18: Liquid / Image.iso / liquid / top2124 / framer.doc next >
Text File  |  1994-02-04  |  25KB  |  631 lines
  1.  
  2.                                FRAMER Version 1.0
  3.                         Copyright (C) 1994 P.J. Scholtz
  4.                               All rights reserved.
  5.                                                                         
  6.  
  7.             P.J. Scholtz                     +27 (021) 22-2174 Office
  8.             P.O. Box 237                     +27 (021) 22-2178 Fax
  9.             Stellenbosch                     +27 (021) 24-2208 BBS
  10.             7599
  11.             South Africa                     
  12.             
  13.             Fidonet  5:7102/110
  14.             Internet Pieter.Scholtz@f110.n7102.z5.fidonet.ORG
  15.  
  16.  
  17.                       
  18.           CONTENTS
  19.  
  20.           1) Introduction
  21.           2) Shareware
  22.           3) Registration
  23.           4) Legal
  24.           5) Documentation
  25.           6) FRAMER installation
  26.           7) GRABIT installation
  27.           8) GRABIT usage notes
  28.           9) Making objects
  29.          10) FRAMER functions and procedures
  30.          11) Run-time error messages
  31.          12) Software license agreement
  32.         
  33.  
  34.  
  35.           1) INTRODUCTION :
  36.  
  37.           FRAMER is a  library (DLL) for use  with Windows 3.1 which
  38.           allows  for the programming of  FRAME GRABBER cards,  also
  39.           called  Video-in-a-Window.  It contains extensive routines
  40.           for  anything  from  reading  and  writing  a  pixel right
  41.           through to animation.
  42.  
  43.           It can be used to write a variety of software applications
  44.           such as:
  45.                    - Police identi-kit
  46.                    - Hairdressing hair fitting simulation
  47.                    - Security/alarm
  48.                    - Tourist (project them into another scenario)
  49.                    - Plastic surgery
  50.                    - Animation
  51.                    - Games
  52.                    - Video overlaying
  53.  
  54.           It is designed for frame grabber cards based on the Chips& 
  55.           Technology  chipset  82C9001A  (PC-Video :  Video Window -
  56.           Controller).
  57.          
  58.           Cards based on this chipset include:
  59.  
  60.                    - Creative Labs: VideoBlaster
  61.                    - PE-Von: PV100
  62.                    - Adda: Aver 2000
  63.                    - Aitech: Pro PC Video
  64.  
  65.  
  66.           2) SHAREWARE :
  67.           
  68.           This  software is  marketed  under the  Shareware concept.
  69.           Unlike Public Domain software,  Shareware may only be used
  70.           in strict  accordance  with its  registration policy.  The
  71.           concept  of  "look before you buy"  in no way  reduces the
  72.           fact that you have to pay for the software.
  73.  
  74.  
  75.           3) REGISTRATION :
  76.           
  77.           P.J. Scholtz grants you the non-exclusive right to use one
  78.           copy of the object code version of the FRAMER software for
  79.           use on your computer system.  You are entitled to evaluate
  80.           the  software on a  royalty free  basis for  30 days.  Use
  81.           after the 30 day  evaluation period is  subject to payment
  82.           of the license fee specified below.
  83.  
  84.           FRAMER.DLL single user license                  US$ 100.00
  85.  
  86.           Note  that each copy of  FRAMER (i.e. on each  computer it
  87.           runs  concurrently) must be  registered.  Which means that
  88.           any  software you  develop and sell  using FRAMER requires
  89.           a registration for each copy you sell.
  90.  
  91.           There  are no fees for using the  example source code. You
  92.           may modify and sell it as  long as the registration fee is
  93.           paid for each copy of FRAMER.DLL.
  94.  
  95.           Please fill in the attached ORDER.DOC order form.  
  96.  
  97.  
  98.           4) LEGAL
  99.  
  100.           The  FRAMER software has  been tested  extensively using a
  101.           host of  different  systems  and  configurations.  However
  102.           P.J. Scholtz  does  not  accept any  liability for  damage
  103.           caused  by  the use  of  this software.  The  use of  this
  104.           software is at your own risk.
  105.  
  106.  
  107.           5) DOCUMENTATION
  108.  
  109.           FRAMER requires Windows to run in 386 Enhanced Mode.
  110.  
  111.           The documentation of FRAMER is in the form of three source
  112.           code examples.  Two are for  Visual Basic and the third is
  113.           for Turbo Pascal for Windows.
  114.  
  115.           First  look at the  Pascal source then at the  Basic ALARM
  116.           source and lastly at the Basic GRABIT source.  That is the
  117.           order of complexity.
  118.  
  119.           This first version of  FRAMER is not very forgiving if you
  120.           pass  incorrect   parameters.   When  you get  a General -
  121.           Protection Fault (GPF) then you know that something wasn't
  122.           passed  correctly or has not been set up correctly.  Trace
  123.           to the  offending statement  and check  the parameters ...
  124.           If a GPF occurs  then you need to exit and  reload Windows
  125.           to refresh the FRAMER DLL.  An example of when a GPF would
  126.           occur is when colour-mixing an  image and over-running the
  127.           right-hand-side of the screen.
  128.           
  129.           
  130.           6) FRAMER INSTALLATION
  131.  
  132.           The first order of  business is to set up the DLL's.  Your
  133.           frame grabber is supplied with it's own standard DLL.  The
  134.           VideoBlaster has a DLL called  PCVIDEO.DLL. For the Adda -
  135.           2000 it is AV2K.DLL, PV100 is PV100.DLL etc.
  136.  
  137.           Copy  the  above  DLL  to  \WINDOWS\FRAMEGRB.DLL.   FRAMER
  138.           requires you to call it  FRAMEGRB.DLL and it also requires
  139.           it to be installed in the \WINDOWS directory.
  140.  
  141.           Copy FRAMER.DLL into \WINDOWS as well.  The example source
  142.           files requires it there. You can change it to whatever you
  143.           prefer.
  144.  
  145.           
  146.           7) GRABIT installation
  147.           
  148.           GRABIT  requires 8MB of RAM installed in your  computer to
  149.           run.  Don't even try  running it with  4MB:  you will wait
  150.           forever ...
  151.  
  152.           I you do  not have  Visual Basic  installed  then you will
  153.           need  to  download   VBRUN300.DLL  to  run  ALARM.EXE  and
  154.           GRABIT.EXE.  VBRUN300.DLL  should  be  installed  in  your
  155.           \WINDOWS\SYSTEM directory.
  156.  
  157.           Before running GRABIT you  must install the FRAMER DLL and
  158.           your frame grabbers DLL.
  159.  
  160.           Create the directory C:\WINDOWS\GRABIT
  161.           Copy all the GRABIT.ZIP files into C:\WINDOWS\GRABIT
  162.           Copy all the GRABDATA.ZIP files into C:\WINDOWS\GRABIT
  163.  
  164.           The following files need to exist for GRABIT to run. A batch file
  165.           is supplied to do the copying. It is called MAKEGRAB.BAT.
  166.  
  167.           Copy SLIDE1.MMP to STORE0.MMP
  168.           Copy SLIDE1.MMP to STORE1.MMP
  169.           Copy SLIDE1.MMP to STORE2.MMP
  170.           Copy SLIDE1.MMP to STORE3.MMP
  171.           Copy SLIDE1.MMP to PROFILE.MMP
  172.           Copy SLIDE1.MMP to BEFORE.MMP
  173.           Copy SLIDE1.MMP to FRONT.MMP
  174.  
  175.           Copy SLIDE2.MMP to LOGO.MMP
  176.  
  177.  
  178.           8) GRABIT USAGE NOTES
  179.  
  180.           While  video is  live and  clicking on  file 1-3  (via the
  181.           camera icon)  the video will be frozen and  the frame will
  182.           be stored to that file. Video will go back to live after 2
  183.           seconds.
  184.  
  185.           When selecting freeze, file 1 will be loaded to the frozen
  186.           screen.
  187.  
  188.           Using file 1-3 via the  camera icon you can load different
  189.           backgrounds while an object is on the frozen screen.
  190.  
  191.           The first  time you  select  an object after  freezing the
  192.           video  the color  chart will  appear after  selecting  the
  193.           object.  After that you need to  specifically select color
  194.           to change the colors.
  195.  
  196.           You can click the object icon while in live video. It will 
  197.           freeze frame and load the object selection screen.
  198.  
  199.           When you  select a  color  from  the color  chart you  are
  200.           actually selecting a color range.  The colors displayed on
  201.           the color chart are averages.
  202.  
  203.           Clicking the color icon  will display the color options as
  204.           well as  two color ranges.  The top one is for  the object
  205.           color and the second is the brush color. The options allow
  206.           for  changing the  object color,  the brush  color and  to
  207.           change the  object to grey-scale.  The black lines  on the
  208.           color-bars indicate the current color. Click on the color-
  209.           bar to move  the black line to that  position and have the
  210.           color changed.
  211.  
  212.           The first option via the fx icon is for zooming the object
  213.           up/down and vertical/horizontal. The pull & push option is
  214.           for squaring  a section of the  object and  up/downing the
  215.           squared area in a vertical or horizontal direction. Mirror
  216.           flips the object horizontally. Object sink in combines the
  217.           current object with the background.  The scroll-bar on the
  218.           end indicates the size of: movement, zoom and pull & push.
  219.           The top is maximum and the bottom is minimum.  The scroll-
  220.           bar can be  adjusted via the key-pad:  9 = maximum and 1 =
  221.           minimum. Pressing 0 on the key-pad will clear the icons of 
  222.           the screen so you can see the complete screen.
  223.  
  224.           After  selecting pull & push  the cursor will change.  You
  225.           then need to  select the starting  corner of the  area you
  226.           wish to  work with.  After  selecting the  starting corner
  227.           move the cursor to block the area you want. Click a second
  228.           time to  finalise the  block  selection.  Now you  need to
  229.           click next to one side of  the four side of the rectangle.
  230.           Four button  will appear  where  you clicked. Use  plus to
  231.           enlarge, minus to shrink. When done select yes to make the
  232.           changes permanent or no to undo the changes.
  233.  
  234.           The save  option via the file icon  can store four images.
  235.           It will save over the first  one when you have saved four.
  236.           The load option will  display the four saved images, click
  237.           on the one you like and  it will be displayed full-screen.
  238.           The logo  option will display the logo file LOGO.MMP.  The
  239.           print option simply clears the icons of the screen.
  240.  
  241.           Whenever a image  is displayed  full-screen,  clicking the
  242.           mouse will return the icons.
  243.  
  244.           The icon in the  lower-right-hand corner  is your 'cursor-
  245.           keys'. Click once in the  relevant square to move a single
  246.           step (remember the scroll-bar under fx for the step size).
  247.           Click  and  keep  the  button   depressed  for  continuous
  248.           movement.
  249.  
  250.           The small  square next to  the movement icon is the  brush
  251.           size. Click it to step through the three sizes.
  252.  
  253.           Click on quit to exit the software.
  254.  
  255.           Double click the top-right-hand icon for a slide-show.
  256.  
  257.           Click and keep  the button depressed on  the undo icon for
  258.           step-by-step undo.  Double click  the undo for  a complete
  259.           undo.
  260.  
  261.           The  left mouse  button  paints on  the object, the  right
  262.           mouse  button  erases.  You  can only  paint/erase in  the
  263.           rectangular area of the object.
  264.  
  265.           When you  select a new object  it will be zoomed to  the x
  266.           and y zoom % of the previous object.
  267.  
  268.  
  269.           9) MAKING OBJECTS
  270.           
  271.           Probably the  most important feature of the  FRAMER DLL is
  272.           the ability to mask objects.  This allows for a variety of
  273.           software to  be designed.  Each object  needs to be in the
  274.           .MMP format. Your frame grabber is supplied with a utility
  275.           for viewing video and it  allows for saving and storing in
  276.           a few  formats.  It is  also  supplied  with  TRG2MMP  and
  277.           MMP2TRG.
  278.  
  279.           An object file requires a corresponding .RLE file. This is
  280.           a  Run-Length-Encoded  file  which  maps  the  object.  It
  281.           indicates  which pixels are to be displayed and  which are
  282.           "see-through".
  283.  
  284.           The process of making a object is as follows:
  285.  
  286.           1. Capture  an image and save it as a 24 bit  .TGA (Targa)
  287.              file.
  288.           2. Size the image so its width (X size) is divisible by 4.
  289.           3. Use editing software and  paint the "see-through" parts 
  290.              black (RGB 0,0,0).
  291.           4. Run RLE&MMP  in the  directory which  contains the .TGA
  292.              file
  293.  
  294.           RLE&MMP requires TRG2MMP.EXE to be in the path. The result
  295.           will be a  .MMP,  .RLE  and a .RGB file.  The .RGB file is
  296.           used  by the  GRABIT  Basic  source example.  The  routine
  297.           MASKIMAGE requires .MMP and .RLE files.
  298.  
  299.           Don't use MMP2TRG as it  creates 16 .TGA files and RLE&MMP
  300.           requires  24 bit .TGA  files.  Use the Windows  utility to
  301.           convert .MMP files to 24 bit .TGA.
  302.  
  303.           10) FRAMER FUNCTIONS AND PROCEDURES
  304.  
  305.           SaveMMP       : Save a rectangular area from the active 
  306.                           page. Extension not assumed. File will be 
  307.                           in the .MMP format. SaveMMP is a function.
  308.             Filename    : String
  309.             X Start, 
  310.             Y Start,
  311.             X Size,
  312.             Y Size      : Word
  313.  
  314.           LoadMMP       : Load to the active page at X,Y. Extension 
  315.                           not assumed. File must be in the .MMP 
  316.                           format. LoadMMP is a function.
  317.             Filename    : String
  318.             X Start,
  319.             Y Start     : Word
  320.  
  321.           SaveICO       : Same as SaveMMP but stores in the frame -
  322.                           grabber buffer format. SaveICO is a 
  323.                           function.
  324.           
  325.           LoadICO       : Same as LoadMMP but expects file to be in
  326.                           the frame grabber buffer format. LoadICO
  327.                           is a function.
  328.  
  329.           SetActivePage : Sets the active page for FRAMER.DLL to
  330.                           work with. SetActivePage is a procedure.
  331.             Page        : word
  332.  
  333.           ClearPage     : Blacks the specified page. ClearPage is
  334.                           a procedure.
  335.             Page        : word
  336.  
  337.           MaskImage     : Masks an object. Extensions are assumed
  338.                           to be .MMP and .RLE. MaskImage is a 
  339.                           function.
  340.             Filename    : string
  341.             X Start,
  342.             Y Start,
  343.             ForceLoad,
  344.             SourcePage,
  345.             Destination : word
  346.  
  347.           BlockRGB      : Fills a block on the active page. BlockRGB
  348.                           is a procedure.
  349.             X Start,
  350.             Y Start,
  351.             X Size,
  352.             Y Size,
  353.             Red,
  354.             Green,
  355.             Blue        : word
  356.  
  357.           RGBPutPixel   : Puts a pixel on the active page.
  358.                           Specified in the RGB format.
  359.                           RGBPutPixel is a procedure.
  360.             X Start,
  361.             Y Start,
  362.             Red,
  363.             Green,
  364.             Blue        : word
  365.  
  366.           RGBGetPixel   : Gets a pixel from the active page.
  367.                           Specified in the RGB format.
  368.                           RGBGetPixel is a procedure.
  369.             X Start,
  370.             Y Start,
  371.             Red,
  372.             Green,
  373.             Blue        : word
  374.  
  375.           YuvGetPixel   : Gets a pixel from the active page.
  376.                           Specified in the YUV format.
  377.                           YUVPutPixel is a procedure.
  378.             X Start,
  379.             Y Start,
  380.             Luma,
  381.             Chroma1,
  382.             Chroma2     : word
  383.           
  384.           YUVGetPixel   : Gets a pixel from the active page.
  385.                           Specified in the YUV format.
  386.                           YUVGetPixel is a procedure.
  387.             X Start,
  388.             Y Start,
  389.             Luma,
  390.             Chroma1,
  391.             Chroma2     : word
  392.  
  393.           CopyBlock     : Copies a block from one page to another.
  394.                           CopyBlock is a procedure.
  395.             X Start,
  396.             Y Start,
  397.             X Size,
  398.             Y Size,
  399.             SourcePage,
  400.             Destination : word
  401.           
  402.           MoveBlock     : Moves/Copies a block from one page to
  403.                           another. MoveBlock is a procedure.
  404.             X Start,
  405.             Y Start,
  406.             X Size,
  407.             Y Size,
  408.             X Destination,
  409.             Y Destination,
  410.             SourcePage,
  411.             Destination : word
  412.           
  413.           ColourChange  : Changes the colour of the active page.
  414.                           Area indicated by the currently loaded
  415.                           object. A value of 100% indicates no 
  416.                           change. ColourChange is a procedure.
  417.             Red Start,
  418.             Green Start,
  419.             Blue Start,
  420.             Red %,
  421.             Green %,
  422.             Blue %      : word
  423.           
  424.           ColMixImage   : Loads an object to the active page and 
  425.                           changes the colour. Assumes extensions
  426.                           .MMP and .RLE. a value of 100% indicates
  427.                           no change. ColMixImage is a function.
  428.             Filename    : string
  429.             X Start,
  430.             Y Start,
  431.             Forceload,
  432.             DestinationPage,
  433.             Red Start,
  434.             Green Start,
  435.             Blue Start,
  436.             Red %,
  437.             Green %,
  438.             Blue %      : word
  439.  
  440.           ColourBlock   : Colours a block on the active page.
  441.                           ColourBlock is a procedure.
  442.             X Start,
  443.             Y Start,
  444.             X Size,
  445.             Y Size,
  446.             X Addition,
  447.             Y Addition,
  448.             Red %,
  449.             Green %,
  450.             Blue %      : word
  451.  
  452.           UpdateRleBlock: Updates the currently loaded .RLE.
  453.                           UpdateRleBlock is a procedure.
  454.             X Start,
  455.             Y Start,
  456.             X Size,
  457.             Y Size,
  458.             AddRemove   : word
  459.  
  460.           UpDateRleCircle:Updates the currently loaded .RLE.
  461.                           UpDateRleCircle is a procedure.
  462.             X Start,
  463.             Y Start,
  464.             AddRemove   : word
  465.           
  466.          YZoomImage     : Zooms the active page. 100 % indicates
  467.                           no change. Zooms the area indicated by
  468.                           the currently loaded object. YZoomImage 
  469.                           is a function.
  470.            Factor       : word
  471.  
  472.          YZoomBlock     : Zooms a block on the active page. 100 %
  473.                           indicates no change. YZoomBlock is a
  474.                           function.
  475.            X Start,               
  476.            Y Start,
  477.            X End,
  478.            Y End,
  479.            Factor,
  480.            Direction    : word
  481.  
  482.          XZoomImage     : Zooms the active page. 100 % indicates
  483.                           no change. Zooms the area indicated by
  484.                           the currently loaded object. XZoomImage 
  485.                           is a function.
  486.            Factor       : word
  487.  
  488.          XZoomBlock     : Zooms a block on the active page. 100 %
  489.                           indicates no change. XZoomBlock is a
  490.                           function.
  491.            X Start,               
  492.            Y Start,
  493.            X End,
  494.            Y End,
  495.            Factor,
  496.            Direction    : word
  497.  
  498.           InitVariance  : Initialises the circular brush random
  499.                           value. InitVariance is a procedure.
  500.             Value       : word
  501.  
  502.           InitColours   : Initialises the colours of the brush.
  503.                           InitColours is a procedure.
  504.  
  505.             Red,
  506.             Green,
  507.             Blue        : word
  508.  
  509.           DrawCircle    : Draw a circle on the active page.
  510.                           DrawCircle is a procedure.
  511.             X Start,
  512.             Y Start     : word
  513.  
  514.           ClearCircle   : Erase a circle on the active page.
  515.                           ClearCircle is a procedure
  516.             X Start,
  517.             Y Start     : word
  518.  
  519.           CopyCircle    : Copies a circle from one page to another.
  520.                           CopyCircle is a procedure.
  521.             X Start,
  522.             Y Start,
  523.             SourcePage,
  524.             Destination : word
  525.  
  526.           Freememory    : Frees memory allocated during InitDll.
  527.                           Freememory is a procedure.
  528.  
  529.           InitDll       : Initialises FRAMER.DLL for the number of
  530.                           pages required and for the specific type
  531.                           of frame grabber.
  532.             Pages,
  533.             CardType    : word
  534.  
  535.           StoreRle      : Make a internal backup of the currently
  536.                           loaded .RLE. StoreRle is a procedure.
  537.  
  538.           ReStoreRle    : Restores the backed up .RLE. ReStoreRle
  539.                           is a procedure.
  540.  
  541.           StoreBlock    : Make a internal backup of the area on the
  542.                           active page. StoreBlock is a procedure.
  543.             X Start,
  544.             Y Start,
  545.             X Size,
  546.             Y Size      : word
  547.  
  548.           ReStoreBlock  : Restores the backup block to the active
  549.                           page. ReStoreBlock is a procedure.
  550.  
  551.           
  552.           11) RUN-TIME ERROR MESSAGES
  553.  
  554.           The following are a list of FRAMER.DLL run-time errors.
  555.  
  556.           Error # Error Message
  557.           1       Invalid function number
  558.           2       File not found
  559.           3       Path not found
  560.           4       Too many open files
  561.           5       File access denied
  562.           6       Invalid file handle
  563.           12      Invalid file access code
  564.           15      Invalid drive number
  565.           16      Cannot remove current directory
  566.           17      Cannot rename across drives
  567.           100     Disk read error
  568.           101     Disk write error
  569.           102     File not assigned
  570.           103     File not open
  571.           104     File not open for input
  572.           105     File not open for output
  573.           106     Invalid numeric format
  574.           200     Division by zero
  575.           201     Range check error
  576.           202     Stack overflow error
  577.           203     Heap overflow error
  578.           204     Invalid pointer operation
  579.           205     Floating point overflow
  580.           206     Floating point underflow
  581.           207     Invalid floating point operation
  582.           210     Object not initialised
  583.           211     Call to abstract method
  584.           212     Stream registration error
  585.           213     Collection index out of range
  586.           214     Collection overflow error
  587.  
  588.           If you are running a Visual Basic program and a error pops
  589.           up that simply states "ERROR" then it might very well be a
  590.           division by zero error in a complex formula.
  591.  
  592.  
  593.           12) SOFTWARE LICENSE AGREEMENT
  594.  
  595.           By using  this software, you  agree to  the terms  of this
  596.           agreement.
  597.  
  598.           No warranties are expressed or implied.  In no event shall
  599.           P.J. Scholtz be held liable for damages resulting from the
  600.           use or  misuse of this product,  including but not limited
  601.           to implied warranties of fitness for a particular purpose.
  602.  
  603.           The shareware  version may be  freely distributed as  long
  604.           as  all files  stay together  and are not  modified in any
  605.           way.  No cost  may be charged  for the  shareware  version
  606.           beyond  normal  and  reasonable  copying and  distribution
  607.           expenses.
  608.  
  609.           No products  developed  with this software  shall be  sold
  610.           unless this software has been registered with P.J. Scholtz.
  611.          
  612.           At no time for  any reason shall this  software be reverse 
  613.           engineered, decompiled or disassembled.
  614.  
  615.           This software may not be rented or leased.
  616.  
  617.           This  software may  be used  only on one  terminal or  one
  618.           computer  at any one given  moment in time.  This software
  619.           may not be  installed on a  network of  any type.  Contact
  620.           P.J. Scholtz for networking options.
  621.  
  622.           The ownership of this software  may be transferred as long
  623.           as  P.J. Scholtz is  notified in  writing of  the transfer
  624.           date  and  new  owner. The  new  owner must  agree to this
  625.           contract. The transfer must include all registered updates
  626.           and previously registered versions. The original owner may
  627.           not  retain  any  copies in  any  form  of the  registered
  628.           software or its documents.
  629.  
  630. -----------------------------------------------------------------------------
  631.