home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / Misc / OTT-PHT3.DMS / in.adf / devdocs / paintmodes / paintmode.doc < prev    next >
Encoding:
Text File  |  1994-11-21  |  5.7 KB  |  226 lines
  1. Programming information for paintmode files 
  2. ===========================================
  3.  
  4. Copyright © Almathera Systems Ltd 1994. All Rights Reserved.
  5.  
  6. All programming examples and documentation is proprietary
  7. and may only be used to create paintmode files for use
  8. with the Photogenics program.
  9.  
  10. Any other use of this documentation and source is strictly
  11. prohibited. It may not be reproduced or copied without
  12. written authorisation from Almathera.
  13.  
  14. Permission is hereby given to allow free or commercial
  15. distribution of paintmode files for Photogenics written using
  16. this code. Almathera encourages the free distribution
  17. of paintmode files for use with Photogenics.
  18.  
  19. (ie. If you write a paintmode, you can do whatever you want with
  20. it!)
  21.  
  22. Paintmode files may not be distributed for use with any other
  23. Amiga software.
  24.  
  25. (ie. You can't reverse engineer our system and build your
  26. own image-processor around our files)
  27.  
  28. ---------------------------------------------------
  29. If you have any problems developing add-on files for
  30. Photogenics, then please contact:
  31.  
  32. Jolyon Ralph or Keith Smith on (UK) 0181 687 0040
  33. during office hours, or email to:
  34.  
  35. jralph@cix.compulink.co.uk
  36.  
  37. We'll be happy to help out where we can.
  38.  
  39. If you've come up with an excellent idea for a paintmode but
  40. can't program it yourself, then let us know and we might
  41. have a go ourselves, or call our BBS, someone may
  42. have already written one!
  43.  
  44. -----------------------------------------------------
  45.  
  46. What is a paintmode file? - Jolyon Ralph (21/11/94)
  47. ===================================================
  48. A paintmode is, like the GIO files, a standard system library.
  49. Unlike GIOs, the core code used for photogenics is an assembler
  50. routine (it should not be written in any other language). It
  51. is possible to write everything else in C or another language and
  52. link in the assembler, although all our examples are pure assembler.
  53.  
  54. The examples provided are writen for Hisoft Devpac 3.0 assembler,
  55. but do not use any special features and should quite easily
  56. convert for use with any other assembler.
  57.  
  58. Each library contains three functions
  59.  
  60. PaintInfo     - This returns information about the paintmode
  61. PaintAddr     - This returns the address of the actual assembler code
  62. PaintOptions - This sets optional values for the loader
  63.  
  64. See the examples for further information:
  65. ----------------------------------------
  66.  
  67. paintmode/PaintInfo                                      paintmode/PaintInfo
  68.  
  69.    NAME
  70.     PaintInfo -- Return information about paint mode
  71.  
  72.    SYNOPSIS
  73.     Information = PaintInfo()
  74.  
  75.     ULONG PaintInfo( void );
  76.     D0
  77.  
  78.    FUNCTION
  79.     This routine returns flags relevent to the operation of the Paint
  80.     mode. 
  81.     
  82.    INPUTS
  83.  
  84.    RESULTS
  85.     Information: The flags returned by the function.
  86.  
  87.     Valid flags returned are: (see paintmodes.i)
  88.  
  89.         PAINT_COLOUR - 
  90.         The mode uses the currently selected colour (eg Paint, Tint, etc.)
  91.  
  92.         PAINT_SECONDARY -
  93.         The mode requires a secondary buffer (eg RubThru)
  94.  
  95.         PAINT_BUFFERALL -
  96.         If your paint mode refers to other pixels on the image you
  97.         will have to buffer the image. This requires Undo and the
  98.         paintmode will not work with Undo disabled.
  99.  
  100.         PAINT_NOOPTIONS -
  101.         This loader does not have any user-settable options.
  102.  
  103.    NOTES
  104.  
  105.     It can also be used to identify a paint mode (as opposed to a
  106.     gio etc.) by checking the high word returned matches
  107.     the key
  108.  
  109.         result=PaintInfo();
  110.         if((result&0xffff0000)!=PAINT_KEY) Error("Not a paint mode!");
  111.  
  112.    SEE ALSO
  113.  
  114.    BUGS
  115.  
  116. paintmode/PaintAddr                                      paintmode/PaintAddr
  117.  
  118.    NAME
  119.     PaintAddr - Get the address of the paint mode assember code
  120.  
  121.    SYNOPSIS
  122.     addr = PaintAddr()
  123.  
  124.     APTR PaintAddr( void )
  125.     D0
  126.  
  127.    FUNCTION
  128.     This returns the address of the assembler code needed to operate
  129.     the paint mode. The assembler code should be imbedded into the
  130.     library. See the entry below for the assembler hook.
  131.  
  132.    INPUTS
  133.  
  134.    RESULTS
  135.     The address of the assembler hook.
  136.  
  137.    NOTES
  138.  
  139.    SEE ALSO
  140.  
  141.    BUGS
  142.  
  143. paintmode/PaintOptions                                paintmode/PaintOptions
  144.  
  145.    NAME
  146.     PaintOptions - Set options for paint mode
  147.  
  148.    SYNOPSIS
  149.  
  150.     Changed = PaintOptions(pgsbase, buffer)
  151.     
  152.     BOOL PaintOptions(struct PgsBase *,struct PhotoBuff *)
  153.     D0                        A0                        A1
  154.  
  155.    FUNCTION
  156.     Brings up a requester if necessary and sets internal values for the 
  157.    paint mode.
  158.  
  159.    INPUTS
  160.     pgsbase - open library pointer to the pgs.library
  161.     buffer  - pointer to the current active buffer
  162.  
  163.    RESULTS
  164.     If any change to the preferences was made changed is TRUE, else
  165.     false
  166.  
  167.    NOTES
  168.     If no preferences are needed, the code should be:
  169.  
  170.         moveq    #0,d0                ; set changed to false
  171.         rts
  172.  
  173.    SEE ALSO
  174.  
  175.    BUGS
  176.  
  177. paintmode/_assembler hook                         paintmode/_assembler hook
  178.  
  179.    NAME
  180.     _assembler hook - The actual painting routine
  181.  
  182.    SYNOPSIS
  183.     Cannot be called directly from library.
  184.  
  185.         (addr = PaintAddr)
  186.         move.l    addr,a6
  187.         jsr        (a6)
  188.  
  189.    FUNCTION
  190.     Paints one pixel. Called in a loop for the entire area to be
  191.     drawn. Transparency, alpha channels, etc. are handled seperately.
  192.  
  193.    INPUTS
  194.     d1    -    Current pixel red value 
  195.     d2    -    Current pixel green value
  196.     d3    -    Current pixel blue value
  197.     a5    -    Current PhotoInfo structure (see photogenics.i)
  198.  
  199.     important values to reference from a5
  200.  
  201.         PHI_x(a5)        - current X position of pixel        
  202.         PHI_y(a5)        - current Y position of pixel
  203.         PHI_red(a5)        - current colour red component
  204.         PHI_green(a5)    - current colour green component
  205.         PHI_blue(a5)    - current colour blue component
  206.         PHI_width(a5)    - width of current picture
  207.         PHI_height(a5)    - height of current picture
  208.  
  209.     a3    -    PgsBase
  210.  
  211.    RESULTS
  212.     d4    -    New pixel red value
  213.     d5    -     New pixel green value
  214.     d6    -    New pixel blue value
  215.  
  216.    NOTES
  217.     Do NOT trash D1,d2,d3 or ANY address register.
  218.  
  219.     These *must* be written in assembler for speed. 
  220.  
  221.    SEE ALSO
  222.     paintmode/PaintAddr
  223.  
  224.  
  225.  
  226.