home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Amiga Shareware Floppies / ma83.dms / ma83.adf / ArtPro.lha / ArtPRO_Install / RenderLib / Doc / Autodoc / render.doc < prev    next >
Encoding:
Text File  |  1997-03-02  |  50.0 KB  |  1,511 lines
  1. TABLE OF CONTENTS
  2.  
  3. render.library/AddChunkyImageA
  4. render.library/AddHistogramA
  5. render.library/AddRGB
  6. render.library/AddRGBImageA
  7. render.library/AllocRenderMem
  8. render.library/AllocRenderVec
  9. render.library/BestPen
  10. render.library/Chunky2BitMapA
  11. render.library/Chunky2RGBA
  12. render.library/ConvertChunkyA
  13. render.library/CountRGB
  14. render.library/CreateHistogramA
  15. remder.library/CreatePaletteA
  16. render.library/CreatePenTableA
  17. render.library/CreateRMHandlerA
  18. render.library/CreateScaleEngineA
  19. render.library/DeleteHistogram
  20. render.library/DeletePalette
  21. render.library/DeleteRMHandler
  22. render.library/DeleteScaleEngine
  23. render.library/ExportPaletteA
  24. render.library/ExtractPaletteA
  25. render.library/FlushPalette
  26. render.library/FreeRenderMem
  27. render.library/FreeRenderVec
  28. render.library/ImportPaletteA
  29. render.library/Planar2ChunkyA
  30. render.library/QueryHistogram
  31. render.library/RenderA
  32. render.library/ScaleA
  33. render.library/ScaleOrdinate
  34. render.library/SortPaletteA
  35. render.library/AddChunkyImageA                 render.library/AddChunkyImageA
  36.  
  37.    NAME
  38.         AddChunkyImageA - add chunky bytes to a histogram.
  39.         AddChunkyImage  - varargs stub for AddChunkyImageA.
  40.  
  41.    SYNOPSIS
  42.         success = AddChunkyImageA(histogram,chunky,width,height,
  43.         d0                        a0        a1     d0    d1     
  44.                                   palette,taglist)
  45.                                   a2      a3
  46.         
  47.         ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
  48.                               APTR,struct TagItem *)
  49.         
  50.         ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
  51.                               APTR,tag,...,TAG_DONE)
  52.  
  53.    FUNCTION
  54.         This function adds an array of chunky bytes to a
  55.         histogram. The color information contained in the
  56.         chunky array gets stored in the histogram.
  57.  
  58.    INPUTS
  59.         histogram       - pointer to a histogram
  60.         chunky          - pointer to an array of chunky bytes
  61.         width           - width to be added [pixels]
  62.         height          - lines to be added [rows]
  63.         palette         - pointer to a palette object
  64.                           created with CreatePaletteA()
  65.         taglist         - pointer to an array of TagItems
  66.  
  67.    TAGS
  68.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  69.                 Default - equals to the specified width.
  70.  
  71.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  72.                 structure for progress display operations. Refer to
  73.                 render/renderhooks.h for further information.
  74.                 Default - NULL.
  75.         
  76.    RESULTS
  77.         success - return value to indicate whether the operation succeeded.
  78.                   You must at least check for ADDH_SUCCESS. Adding data to
  79.                   histograms may fail at any time and the histogram may
  80.                   thereof get inaccurate.
  81.  
  82.    NOTES
  83.         - It is not possible with this function to directly add a chunky
  84.           array that represents a HAM color scheme. In this case you have
  85.           to convert it to an RGB array via Chunky2RGBA(), and then to call
  86.           AddRGBImageA().
  87.            
  88.         - This function may call the progress callback Hook with
  89.           the PMSGTYPE_LINES_ADDED message.
  90.         
  91.    SEE ALSO
  92.         AddRGBImageA(), CreateHistogramA(), render/renderhooks.h
  93.  
  94.  
  95. render.library/AddHistogramA                     render.library/AddHistogramA
  96.  
  97.    NAME
  98.         AddHistogramA - add a histogram to another histogram.
  99.         AddHistogram  - varargs stub for AddHistogramA.
  100.  
  101.    SYNOPSIS
  102.         success = AddHistogramA(desthistogram,sourcehistogram,taglist)
  103.         d0                      a0            a1              a2
  104.         
  105.         ULONG AddHistogramA(APTR,APTR,struct TagItem *)
  106.         
  107.         ULONG AddHistogramA(APTR,APTR,tag,...,TAG_DONE)
  108.  
  109.    FUNCTION
  110.         This function adds a histogram to another histogram,
  111.         according to the following scheme:
  112.         
  113.         desthistogram + sourcehistogram -> desthistogram
  114.         
  115.         The color information contained in the source histogram
  116.         will be added to the destination histogram.
  117.  
  118.    INPUTS
  119.         desthistogram       - pointer to destination histogram
  120.         sourcehistogram     - pointer to source histogram
  121.         taglist             - pointer to an array of TagItems
  122.  
  123.    TAGS
  124.         None defined. Pass NULL.
  125.  
  126.    RESULTS
  127.         success - return value to indicate whether the operation succeeded.
  128.                   You must at least check for ADDH_SUCCESS. Adding data to
  129.                   histograms may fail at any time and the histogram may
  130.                   thereof get inaccurate.
  131.        
  132.    SEE ALSO
  133.         CreateHistogramA()
  134.  
  135.  
  136. render.library/AddRGB                                   render.library/AddRGB
  137.  
  138.    NAME
  139.         AddRGB - add a RGB value to a histogram.
  140.  
  141.    SYNOPSIS
  142.         success = AddRGB(histogram,RGB,count)
  143.         d0               a0        d0  d1
  144.         
  145.         ULONG AddRGB(APTR,ULONG,ULONG)
  146.  
  147.    FUNCTION
  148.         This function adds a single RGB value plus the number
  149.         of its representations to a histogram.
  150.  
  151.    INPUTS
  152.         histogram    - pointer to a histogram
  153.         RGB          - RGB value to be added
  154.         count        - number of represantations for that RGB value
  155.  
  156.    RESULTS
  157.         success - return value to indicate whether the operation succeeded.
  158.                   You must at least check for ADDH_SUCCESS. Adding data to
  159.                   histograms may fail at any time and the histogram may
  160.                   thereof get inaccurate.
  161.  
  162.    SEE ALSO
  163.         AddRGBImageA(), CreateHistogramA()
  164.  
  165.  
  166. render.library/AddRGBImageA                       render.library/AddRGBImageA
  167.  
  168.    NAME
  169.         AddRGBImageA - add an array of RGB data to a histogram.
  170.         AddRGBImage  - varargs stub for AddRGBImageA.
  171.  
  172.    SYNOPSIS
  173.         success = AddRGBImageA(histogram,rgb,width,height,taglist)
  174.         d0                     a0        a1  d0    d1     a2
  175.         
  176.         ULONG AddRGBImageA(APTR,ULONG *,UWORD,UWORD,struct TagItem *)
  177.         
  178.         ULONG AddRGBImage(APTR,ULONG *,UWORD,UWORD,tag,...,TAG_DONE) 
  179.  
  180.    FUNCTION
  181.         This function adds an array of RGB pixels to a
  182.         histogram. The color information contained in the
  183.         RGB array gets stored in the histogram.
  184.  
  185.    INPUTS
  186.         histogram       - pointer to a histogram
  187.         rgb             - pointer to an array of RGB data
  188.         width           - width to be added [pixels]
  189.         height          - lines to be added [rows]
  190.         taglist         - pointer to an array of TagItems
  191.  
  192.    TAGS
  193.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  194.                 Default - equals to the specified width.
  195.  
  196.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  197.                 structure for progress display operations. Refer to
  198.                 render/renderhooks.h for further information.
  199.                 Default - NULL.
  200.  
  201.    RESULTS
  202.         success - return value to indicate whether the operation succeeded.
  203.                   You must at least check for ADDH_SUCCESS. Adding data to
  204.                   histograms may fail at any time and the histogram may
  205.                   thereof get inaccurate.
  206.  
  207.    NOTES
  208.         - This function may call the progress callback Hook with
  209.           the PMSGTYPE_LINES_ADDED message.
  210.         
  211.    SEE ALSO
  212.         AddRGB(), CreateHistogramA(), render/renderhooks.h
  213.  
  214.  
  215. render.library/AllocRenderMem                   render.library/AllocRenderMem
  216.  
  217.    NAME
  218.         AllocRenderMem - allocate memory from a render-memhandler.
  219.  
  220.    SYNOPSIS
  221.         mem = AllocRenderMem(rendermemhandler,size)
  222.         d0                   a0               d0
  223.  
  224.         APTR AllocRenderMem(APTR, ULONG)
  225.  
  226.    FUNCTION
  227.         AllocRenderMem will allocate a memory block from a
  228.         render-memhandler, or from public memory. If there is no
  229.         memory block of the requested size available, NULL will be
  230.         returned. You must check this return value. The request
  231.         may fail at any time. Every call to this function must be
  232.         followed by a call to FreeRenderMem.
  233.  
  234.    INPUTS
  235.         rendermemhandler - pointer to a render-memhandler, or NULL.
  236.                            If you pass NULL, MEMF_ANY will be used.
  237.         size             - the size of the desired block in bytes
  238.  
  239.    RESULTS
  240.         mem              - pointer to a block of memory, or NULL if the
  241.                            allocation failed.
  242.  
  243.    NOTES
  244.         There is no real need for this function being available to
  245.         you, except for helping you to create a smart, lean and sexy
  246.         memory management - the idea is to enable your application
  247.         and the library to share a particular memory pool.
  248.  
  249.    SEE ALSO
  250.         FreeRenderMem(), AllocRenderVec(), CreateRMHandlerA()
  251.  
  252.  
  253. render.library/AllocRenderVec                   render.library/AllocRenderVec
  254.  
  255.    NAME
  256.         AllocRenderVec - allocate memory from a render-memhandler, 
  257.                          keeping track of the allocated size and
  258.                          the memhandler itself.
  259.  
  260.    SYNOPSIS
  261.         mem = AllocRenderVec(rendermemhandler,size)
  262.         d0                   a0               d0
  263.  
  264.         APTR AllocRenderVec(APTR, ULONG)
  265.  
  266.    FUNCTION
  267.         AllocRenderVec will allocate a memory block from a
  268.         render-memhandler, or from public memory. If there is no
  269.         memory block of the requested size available, NULL will be
  270.         returned. You must check this return value. The request
  271.         may fail at any time. Any call to this function must be
  272.         followed by a call to FreeRenderVec(). AllocRenderVec()
  273.         keeps track of the allocated size and the memhandler itself.
  274.  
  275.    INPUTS
  276.         rendermemhandler - pointer to a render-memhandler, or NULL.
  277.                            If you pass NULL, MEMF_ANY will be used.
  278.         size             - the size of the desired block in bytes
  279.  
  280.    RESULTS
  281.         mem              - pointer to a block of memory, or NULL
  282.                            if the allocation failed.
  283.  
  284.    SEE ALSO
  285.         FreeRenderVec(), AllocRenderMem(), CreateRMHandlerA()
  286.  
  287.  
  288. render.library/BestPen                                 render.library/BestPen
  289.  
  290.    NAME
  291.         BestPen - find the best matching pen.
  292.  
  293.    SYNOPSIS
  294.         pen = BestPen(palette,RGB)
  295.         d0            a0      d0
  296.         
  297.         LONG BestPen(APTR,ULONG)
  298.  
  299.    FUNCTION
  300.         Calculate a palette's pen number that matches best
  301.         a given RGB value.
  302.  
  303.    INPUTS
  304.         palette   - palette created with CreatePaletteA()
  305.         RGB       - RGB value to find a match for
  306.  
  307.    RESULTS
  308.         pen       - pen number or -1 if no pen could be found.
  309.                     (Usually this occurs when the palette is empty.)
  310.  
  311.  
  312. render.library/Chunky2BitMapA                   render.library/Chunky2BitMapA
  313.  
  314.    NAME
  315.         Chunky2BitMapA - convert chunky data to bitplanes.
  316.         Chunky2BitMap  - varargs stub for Chunky2BitMapA.
  317.  
  318.    SYNOPSIS
  319.         Chunky2BitMapA(chunky,sx,sy,width,height,bitmap,dx,dy,taglist)
  320.                        a0     d0 d1 d2    d3     a1     d4 d5 a2
  321.         
  322.         void Chunky2BitMapA(UBYTE *,UWORD,UWORD,UWORD,UWORD,
  323.                             struct BitMap *,UWORD,UWORD,struct TagItem *)
  324.         
  325.         void Chunky2BitMap(UBYTE *,UWORD,UWORD,UWORD,UWORD,
  326.                            struct BitMap *,UWORD,UWORD,tag,...,TAG_DONE) 
  327.  
  328.    FUNCTION
  329.         Converts an array of chunky bytes to the bitplanes
  330.         associated with a BitMap structure. You can specify
  331.         clip areas both inside the chunky array and the
  332.         BitMap. This function merges the data into the
  333.         destination BitMap if required. BMF_INTERLEAVED is
  334.         also handled.
  335.         
  336.         You may only process BMF_STANDARD bitmaps with this
  337.         function.
  338.  
  339.    INPUTS
  340.         chunky     - pointer to an array of chunky bytes
  341.         sx         - left edge inside the chunky array [pixels]
  342.         sy         - top edge inside the chunky array [rows]
  343.         width      - width [pixels]
  344.         height     - height [rows]
  345.         bitmap     - pointer to an initialized BitMap structure
  346.         dx         - destination left edge inside BitMap [pixels]
  347.         dy         - destination top edge inside BitMap [rows]
  348.         taglist    - pointer to an array of TagItems
  349.  
  350.    TAGS
  351.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  352.                 Default - equals to the specified width.
  353.  
  354.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  355.                 for an additional conversion of the pen numbers.
  356.                 Default - NULL.
  357.  
  358.    RESULTS
  359.         none
  360.  
  361.    IMPORTANT NOTES
  362.         Starting with v39, you are not allowed to assume foreign
  363.         BitMap structures being of a planar type. You may pass a
  364.         BitMap structure to this function only if the BMF_STANDARD
  365.         flag is set.
  366.  
  367.         Also remember to set-up your own BitMap structure with the
  368.         BMF_STANDARD flag if you wish to convert it with this
  369.         function. Consider Chunky2BitMapA() being low-level. The
  370.         BitMap structure involved here is intended to hold planar
  371.         information. Since v39, this is different to what
  372.         graphics.library might associate with a BitMap structure.
  373.  
  374.         Do NOT use this function with BitMap structures that are
  375.         actually being displayed. If you wish to transfer chunky
  376.         bytes to visible areas, use graphics.library functions, such
  377.         as WriteChunkyPixels(), or WritePixelArray8(). You may also
  378.         use Chunky2BitMapA() followed by BltBitMapRastPort() etc.
  379.  
  380.         With a graphics card supplied, WriteChunkyPixels() can be
  381.         hundereds times faster than Chunky2BitMapA() followed by
  382.         BltBitMapRastPort(). If you have to provide backward
  383.         compatibility, it is worth the effort to differenciate between
  384.         Kick 2.x and OS 3.x. Use Chunky2BitMapA() in the first case,
  385.         WritePixelArray8() in the second case, and WriteChunkyPixels()
  386.         if the system runs under OS3.1 and is supplied with a graphics
  387.         card.
  388.  
  389. SEE ALSO
  390.         Planar2ChunkyA(), graphics/gfx.h,
  391.         graphics.library/WriteChunkyPixels()
  392.  
  393.  
  394. render.library/Chunky2RGBA                         render.library/Chunky2RGBA
  395.  
  396.    NAME
  397.         Chunky2RGBA - convert an array of chunky bytes to RGB data.
  398.         Chunky2RGB  - varargs stub for Chunky2RGBA.
  399.  
  400.    SYNOPSIS
  401.         success = Chunky2RGBA(chunky,width,height,rgb,palette,taglist)
  402.         d0                    a0     d0    d1     a1  a2      a3
  403.         
  404.         ULONG Chunky2RGBA(UBYTE *,UWORD,UWORD,ULONG *,APTR,struct TagItem *)
  405.         
  406.         ULONG Chunky2RGB(UBYTE *,UWORD,UWORD,ULONG *,APTR,tag,...,TAG_DONE) 
  407.  
  408.    FUNCTION
  409.         This function converts an array of chunky bytes to RGB data.
  410.  
  411.    INPUTS
  412.         chunky      - pointer to an array of chunky bytes
  413.         width       - width to be converted [pixels]
  414.         height      - height to be converted [rows]
  415.         rgb         - pointer to RGB destination buffer
  416.         palette     - pointer to a palette object created
  417.                       with CreatePaletteA()
  418.         taglist     - pointer to an array of TagItems
  419.  
  420.    TAGS
  421.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  422.                 Default - equals to the specified width.
  423.  
  424.         RND_DestWidth (UWORD) - Total width of the RGB array [pixels].
  425.                 Default - equals to the specified width.
  426.  
  427.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  428.                 a pixel's actual color. Valid types:
  429.  
  430.                 COLORMODE_CLUT          - normal palette lookup
  431.                 COLORMODE_HAM8          - HAM8 mode palette lookup
  432.                 COLORMODE_HAM6          - HAM6 mode palette lookup
  433.                 
  434.                 Default - COLORMODE_CLUT.
  435.  
  436.         RND_LeftEdge (UWORD) - Horizontal starting position inside the
  437.                 chunky array [pixels]. This is mainly intended to allow
  438.                 the conversion of HAM clip areas.
  439.                 Default - 0.
  440.  
  441.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  442.                 structure for progress display operations. Refer to
  443.                 render/renderhooks.h for further information.
  444.                 Default - NULL.
  445.  
  446.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  447.                 for an additional conversion of the pen numbers.
  448.                 Default - NULL.
  449.                 Note: This is not defined for HAM modes.
  450.  
  451.    RESULTS
  452.         result  - CONV_SUCCESS to indicate that the operation
  453.                   succeeded. Currently, the only reason for this
  454.                   function to fail is CONV_CALLBACK_ABORTED.
  455.  
  456.    NOTES
  457.         - This function may call the progress callback Hook
  458.           with the PMSGTYPE_LINES_CONVERTED message type.
  459.  
  460.    SEE ALSO
  461.         render/render.h
  462.  
  463.  
  464. render.library/ConvertChunkyA                   render.library/ConvertChunkyA
  465.  
  466.    NAME
  467.         ConvertChunkyA - convert an array of chunky bytes to a new palette.
  468.         ConvertChunky  - varargs stub for ConvertChunkyA.
  469.  
  470.    SYNOPSIS
  471.         ConvertChunkyA(source,sourcepalette,width,height,dest,        
  472.                        a0     a1            d0    d1     a2   
  473.                        destpalette,taglist)
  474.                        a3          a4
  475.         
  476.         void ConvertChunkyA(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  477.                             APTR,struct TagItem *)
  478.         
  479.         void ConvertChunky(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  480.                            APTR,tag,...,TAG_DONE)
  481.  
  482.    FUNCTION
  483.         This function converts a source array of chunky bytes
  484.         to another array, and adapts it to a new palette.
  485.         Optionally, a secondary pen conversion is performed.
  486.  
  487.    INPUTS
  488.         source        - pointer to the source array of chunky data
  489.         sourcepalette - pointer to the source array's palette
  490.         width         - width to be converted [pixels]
  491.         height        - height to be converted [rows]
  492.         dest          - pointer to the destination chunky array
  493.         destpalette   - pointer to the destination array's palette
  494.         taglist       - pointer to an array of TagItems
  495.  
  496.    TAGS
  497.         RND_SourceWidth (UWORD) - Total width of source array [pixels].
  498.                 Default - equals to the width specified.
  499.  
  500.         RND_DestWidth (UWORD) - Total width of dest array [pixels].
  501.                 Default - equals to the width specified.
  502.  
  503.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  504.                 for a secondary conversion of the pen numbers.
  505.                 Default - NULL. 
  506.         
  507.    RESULTS
  508.         none
  509.         
  510.    SEE ALSO
  511.         CreatePenTableA(), CreatePaletteA()
  512.  
  513.  
  514. render.library/CreateHistogramA               render.library/CreateHistogramA
  515.  
  516.    NAME
  517.         CreateHistogramA - create and set up a histogram.
  518.         CreateHistogram  - varargs stub for CreateHistogramA.
  519.  
  520.    SYNOPSIS
  521.         hst = CreateHistogramA(taglist)
  522.         d0                     a1
  523.         
  524.         APTR CreateHistogramA(struct TagItem *)
  525.         
  526.         APTR CreateHistogram(tag,...,TAG_DONE)
  527.  
  528.    FUNCTION
  529.         Allocates and initializes a histogram.
  530.  
  531.    INPUTS
  532.         taglist - pointer to an array of TagItems
  533.  
  534.    TAGS
  535.         RND_RMHandler (ULONG) - pointer to a render-memhandler
  536.                 created with CreateRMHandlerA().
  537.                 Default - NULL.
  538.  
  539.         RND_HSType (UWORD) - Type of histogram. Valid types:
  540.  
  541.                 HSTYPE_12BIT            - 12bit dynamic histogram
  542.                 HSTYPE_15BIT            - 15bit dynamic histogram
  543.                 HSTYPE_18BIT            - 18bit dynamic histogram
  544.                 HSTYPE_21BIT            - 21bit dynamic histogram
  545.                 HSTYPE_24BIT            - 24bit dynamic histogram
  546.                 HSTYPE_12BIT_TURBO      - 12bit tabular histogram
  547.                 HSTYPE_15BIT_TURBO      - 15bit tabular histogram
  548.                 HSTYPE_18BIT_TURBO      - 18bit tabular histogram
  549.  
  550.                 Default - HSTYPE_15BIT_TURBO.
  551.  
  552.    RESULTS
  553.         histogram - pointer to a histogram ready for usage,
  554.                     or NULL if something went wrong.
  555.  
  556.    SEE ALSO
  557.         DeleteHistogram(), QueryHistogram(), render/render.h
  558.  
  559.  
  560. render.library/CountRGB                               render.library/CountRGB
  561.  
  562.    NAME
  563.         CountRGB     - count a RGB value in a histogram.
  564.  
  565.    SYNOPSIS
  566.         count = CountRGB(histogram,RGB)
  567.         d0               a0        d0
  568.         
  569.         ULONG CountRGB(APTR,ULONG)
  570.  
  571.    FUNCTION
  572.         Counts the number of occurances for a particular RGB value.
  573.         The result may depend on the histogram's accuracy.
  574.  
  575.    INPUTS
  576.         histogram - pointer to a histogram
  577.  
  578.    RESULTS
  579.         count     - number of representations for the
  580.                     specified RGB value.
  581.  
  582.    NOTE
  583.         You only get the exact result for 24bit histograms. The
  584.         lower the resolution, the more colors are actually put
  585.         together into one `category' of similar colors. A 24bit
  586.         histogram differenciates 16,7 million colors, a 15bit
  587.         histogram, for instance, only 32768.
  588.  
  589.  
  590. render.library/CreatePaletteA                   render.library/CreatePaletteA
  591.  
  592.    NAME
  593.         CreatePaletteA - create a palette.
  594.         CreatePalette  - vararg stub for CreatePaletteA.
  595.  
  596.    SYNOPSIS
  597.         palette = CreatePaletteA(taglist)
  598.         d0                       a1
  599.         
  600.         APTR CreatePaletteA(struct TagItem *)
  601.         
  602.         APTR CreatePalette(tag,...,TAG_DONE)
  603.  
  604.    FUNCTION
  605.         This function creates and initializes a palette
  606.         that can hold up to 256 color entries.
  607.  
  608.    INPUTS
  609.         taglist     - pointer to an array of TagItems
  610.  
  611.    TAGS
  612.         RND_HSType (ULONG) - the palette's resolution. Palette adaption
  613.                 accuracy and memory consumption depend on this constant.
  614.                 A palette's resolution is specified analogously to a
  615.                 histogram's resolution. Valid types are in the range
  616.                 from 12 to 18 bit:
  617.  
  618.                 HSTYPE_12BIT
  619.                 HSTYPE_15BIT
  620.                 HSTYPE_18BIT
  621.  
  622.                 Default - HSTYPE_15BIT.
  623.  
  624.         RND_RMHandler (ULONG) - pointer to a render-memhandler that was
  625.                 created with CreateRMHandler(). Default - NULL.
  626.         
  627.    RESULTS
  628.         palette  - a palette ready for usage,
  629.                    or NULL if something went wrong.
  630.  
  631.    SEE ALSO
  632.         DeletePalette(), ImportPaletteA(), ExportPaletteA(), 
  633.         ExtractPaletteA(), FlushPalette(), render/render.h
  634.  
  635.  
  636. render.library/CreatePenTableA                 render.library/CreatePenTableA
  637.  
  638.    NAME
  639.         CreatePenTableA - create a pen conversion table.
  640.         CreatePenTable  - varargs stub for CreatePenTableA.
  641.  
  642.    SYNOPSIS
  643.         CreatePenTableA(chunky,oldpalette,width,height,newpalette,
  644.                         a0     a1         d0    d1     a2
  645.                         pentab,taglist)
  646.                         a3     a4
  647.         
  648.         void CreatePenTableA(UBYTE *,APTR,UWORD,UWORD,APTR,
  649.                              UBYTE *,struct TagItem *)
  650.         
  651.         void CreatePenTable(UBYTE *,APTR,UWORD,UWORD,APTR,
  652.                             UBYTE *,tag,...,TAG_DONE)
  653.  
  654.    FUNCTION
  655.         This function creates a table for the conversion of a
  656.         particular array of chunky bytes. It scans through the
  657.         chunky array, adapts the found palette entries to a new
  658.         palette, and generates an output table of 256 UBYTEs.
  659.         
  660.         This function is equivalent to ConvertChunkyA(), except
  661.         for that it does not actually convert the chunky image,
  662.         but instead creates the conversion table for that palette
  663.         adaption.
  664.  
  665.    INPUTS
  666.         chunky      - pointer to an array of chunky bytes
  667.         oldpalette  - pointer to the original palette
  668.         width       - width to be converted [pixels]
  669.         height      - height to be converted [rows]
  670.         newpalette  - pointer to a palette to be adapted to
  671.         pentab      - pointer to the destination table
  672.         taglist     - pointer to an array of TagItems
  673.  
  674.    TAGS
  675.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  676.                 Default - equals to the specified width.
  677.  
  678.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  679.                 for a secondary conversion of the pen numbers.
  680.                 Default - NULL.
  681.         
  682.    RESULTS
  683.         none
  684.         
  685.    NOTES
  686.         The destination table is assumed to have 256 entries,
  687.         with no respect to what color indices actually occur in
  688.         the chunky image.
  689.  
  690.    SEE ALSO
  691.         ConvertChunkyA(), CreatePaletteA()
  692.  
  693.  
  694. render.library/CreateRMHandlerA               render.library/CreateRMHandlerA
  695.  
  696.    NAME
  697.         CreateRMHandlerA - Create and set up a memory handler.
  698.         CreateRMHandler  - varargs stub for CreateRMHandlerA.
  699.  
  700.    SYNOPSIS
  701.         rmh = CreateRMHandlerA(taglist)
  702.         d0                     a1
  703.         
  704.         APTR CreateRMHandlerA(struct TagItem *)
  705.         
  706.         APTR CreateRMHandler(tag,...,TAG_DONE)
  707.  
  708.    FUNCTION
  709.         This function allocates and initializes a render-memhandler.
  710.         This is a custom memory resource manager for histograms,
  711.         rendering, and many other operations. You may use a
  712.         render-memhandler for your own purposes, too.
  713.  
  714.         A render-memhandler helps to avoid memory fragmentation as
  715.         well as extreme stressing of the system's public memory lists.
  716.         Private memory management is supported as well as v39 exec
  717.         pools and common public memory. Future versions might provide
  718.         more types of memory management.
  719.  
  720.    INPUTS
  721.         taglist - pointer to an array of TagItems
  722.  
  723.    TAGS
  724.         RND_MemType (UWORD) - type of memory management. Valid types:
  725.  
  726.                 RMHTYPE_POOL            - v39 exec dynamic pool
  727.                 RMHTYPE_PRIVATE         - you supply a private memory pool
  728.                 RMHTYPE_PUBLIC          - use common public memory
  729.  
  730.                 Default - RMHTYPE_PUBLIC.
  731.  
  732.         RND_MemBlock (ULONG) - pointer to a block of memory
  733.                 used for private memory management. This tag
  734.                 is obligatory if you specify RMHTYPE_PRIVATE
  735.                 and is ignored otherwise. 
  736.                 Default - none.
  737.  
  738.         RND_MemSize (ULONG) - size of the memory block used
  739.                 for private memory management. This tag is
  740.                 obligatory if you specify RMHTYPE_PRIVATE
  741.                 and is ignored otherwise. 
  742.                 Default - none.
  743.  
  744.         RND_MemFlags (ULONG) - memory flags, as defined in
  745.                 exec/memory.h. These are ignored for
  746.                 RMHTYPE_PRIVATE. Default - MEMF_ANY.
  747.  
  748.    RESULTS
  749.         rmh - a render-memhandler ready for usage, or NULL if
  750.               something went wrong.
  751.  
  752.    NOTES
  753.         You must check for the presence of exec v39 before
  754.         you create a memhandler with RMHTYPE_POOL specified.
  755.  
  756.    SEE ALSO
  757.         AllocRenderMem(), AllocRenderVec(), DeleteRMHandler(),
  758.         exec.library/CreatePool(), render/render.h, exec/memory.h
  759.  
  760.  
  761. render.library/CreateScaleEngineA           render.library/CreateScaleEngineA
  762.  
  763.    NAME
  764.         CreateScaleEngineA - Create a scaling-engine.
  765.         CreateScaleEngine  - varargs stub for CreateScaleEngineA.
  766.  
  767.    SYNOPSIS
  768.         scaleengine = CreateScaleEngineA(sourcewidth,sourceheight,
  769.         d0                               d0          d1           
  770.                                          destwidth,destheight,taglist)
  771.                                          d2        d3         a1
  772.         
  773.         APTR CreateScaleEngineA(UWORD,UWORD,UWORD,
  774.                                 UWORD,struct TagItem *)
  775.         
  776.         APTR CreateScaleEngine(UWORD,UWORD,UWORD,
  777.                                UWORD,tag,...,TAG_DONE)
  778.  
  779.    FUNCTION
  780.         Allocates and initializes a scaling-engine for a specific
  781.         set of scaling parameters. Once set up, this scaling-engine
  782.         is highly optimized for these particular parameter
  783.         specifications.
  784.  
  785.    INPUTS
  786.         sourcewidth  - source width [pixels]
  787.         sourceheight - source height [rows]
  788.         destwidth    - destination width [pixels]
  789.         destheight   - destination height [rows]
  790.         taglist      - pointer to an array of tag items
  791.  
  792.    TAGS
  793.         RND_RMHandler (ULONG) - pointer to a render-memhandler,
  794.                 such as created with CreateRMHandlerA().
  795.                 Default - NULL.
  796.  
  797.         RND_PixelFormat (ULONG) - Type of data to process.
  798.                 Currently defined are PIXFMT_CHUNKY_CLUT
  799.                 and PIXFMT_0RGB_32. Default - PIXFMT_CHUNKY_CLUT.
  800.  
  801.    RESULTS
  802.         engine - a scaling-engine ready for usage, or NULL
  803.                  if something went wrong.
  804.  
  805.    SEE ALSO
  806.         DeleteScaleEngine(), ScaleA()
  807.  
  808.  
  809. render.library/DeleteHistogram                 render.library/DeleteHistogram
  810.  
  811.    NAME
  812.         DeleteHistogram - dispose a histogram.
  813.  
  814.    SYNOPSIS
  815.         DeleteHistogram(histogram)
  816.                         a0
  817.  
  818.         void DeleteHistogram(APTR)
  819.  
  820.    FUNCTION
  821.         Removes a histogram and frees all associated memory.
  822.  
  823.    INPUTS
  824.         histogram   - pointer to a histogram
  825.  
  826.    RESULTS
  827.         none
  828.  
  829.  
  830. render.library/DeleteRMHandler                 render.library/DeleteRMHandler
  831.  
  832.    NAME
  833.         DeleteRMHandler - free a render-memhandler.
  834.  
  835.    SYNOPSIS
  836.         DeleteRMHandler(rendermemhandler)
  837.                         a0
  838.  
  839.         void DeleteRMHandler(APTR)
  840.  
  841.    FUNCTION
  842.         DeleteRMHandler() will remove and free a previously created
  843.         render-memhandler. That does not imply that any outstanding
  844.         memory will be returned to the system or to whatever memory
  845.         ressources. You are responsible for freeing each memory block
  846.         that you have allocated from a render-memhandler.
  847.  
  848.    INPUTS
  849.         render-memhandler - a render-memhandler to be deleted.
  850.  
  851.    RESULTS
  852.         none
  853.  
  854.    NOTES
  855.         You are not allowed to call DeleteRMHandler() before
  856.         every single byte has been returned to the memhandler.
  857.  
  858.    SEE ALSO
  859.         CreateRMHandlerA()
  860.  
  861.  
  862. render.library/DeletePalette                     render.library/DeletePalette
  863.  
  864.    NAME
  865.         DeletePalette - dispose a palette.
  866.  
  867.    SYNOPSIS
  868.         DeletePalette(palette)
  869.                       a0
  870.  
  871.         void DeletePalette(APTR)
  872.  
  873.    FUNCTION
  874.         This function deletes a palette and frees all
  875.         associated memory.
  876.  
  877.    INPUTS
  878.         palette   - pointer to a palette, such as created
  879.                     with CreatePaletteA()
  880.  
  881.    RESULTS
  882.         none
  883.  
  884.    SEE ALSO
  885.         CreatePaletteA(), FlushPalette()
  886.  
  887.  
  888. render.library/DeleteScaleEngine             render.library/DeleteScaleEngine
  889.  
  890.    NAME
  891.         DeleteScaleEngine - dispose a scaling-engine.
  892.  
  893.    SYNOPSIS
  894.         DeleteScaleEngine(engine)
  895.                           a0
  896.  
  897.         void DeleteScaleEngine(APTR)
  898.  
  899.    FUNCTION
  900.         Deletes a scaling-engine and frees all associated memory.
  901.  
  902.    INPUTS
  903.         engine   - a scaling-engine to be removed
  904.  
  905.    RESULTS
  906.         none
  907.  
  908.    SEE ALSO
  909.         CreateScaleEngineA(), ScaleA()
  910.  
  911.  
  912. render.library/ExportPaletteA                   render.library/ExportPaletteA
  913.  
  914.    NAME
  915.         ExportPaletteA - export a palette.
  916.         ExportPalette  - varargs stub for ExportPaletteA.
  917.  
  918.    SYNOPSIS
  919.         ExportPaletteA(palette,buffer,taglist)
  920.                        a0      a1     a2
  921.         
  922.         ExportPaletteA(APTR,APTR,struct TagItem *)
  923.         
  924.         ExportPalette(APTR,APTR,tag,...,TAG_DONE)
  925.  
  926.    FUNCTION
  927.         This function exports a palette (or a part of it)
  928.         to a colortable.
  929.  
  930.    INPUTS
  931.         palette   - pointer to a palette created
  932.                     with CreatePaletteA()
  933.         buffer    - pointer to a destination buffer
  934.         taglist   - pointer to an array of tag items
  935.  
  936.    TAGS
  937.         RND_PaletteFormat (ULONG) - format of the color table
  938.                 to be exported. Valid types:
  939.  
  940.                 PALFMT_RGB32    - ULONG red,green,blue
  941.                 PALFMT_RGB8     - ULONG 0x00rrggbb
  942.                 PALFMT_RGB4     - UWORD 0xrgb
  943.  
  944.                 Default - PALFMT_RGB8.
  945.  
  946.         RND_FirstColor (ULONG) - first color entry to export.
  947.                 Default - 0.
  948.         
  949.         RND_NumColors (ULONG) - number of colors to export.
  950.                 Default - the number of colors inside the palette.
  951.  
  952.    RESULTS
  953.         none
  954.  
  955.    SEE ALSO
  956.         CreatePaletteA(), ImportPaletteA()
  957.  
  958.  
  959. render.library/ExtractPaletteA                 render.library/ExtractPaletteA
  960.  
  961.    NAME
  962.         ExtractPaletteA - extract a palette from a histogram.
  963.         ExtractPalette  - varargs stub for ExtractPaletteA.
  964.  
  965.    SYNOPSIS
  966.         success = ExtractPaletteA(histogram,palette,numcolors,taglist)
  967.         d0                        a0        a1      d0        a2
  968.         
  969.         ULONG ExtractPaletteA(APTR,ULONG *,UWORD,struct TagItem *)
  970.         
  971.         ULONG ExtractPalettA(APTR,ULONG *,UWORD,tag,...,TAG_DONE)
  972.  
  973.    FUNCTION
  974.         This function extracts a given number of colors from a
  975.         histogram. This results in a color lookup table (also called
  976.         a palette).
  977.  
  978.    INPUTS
  979.         histogram - pointer to a histogram
  980.         palette   - pointer to a palette created
  981.                     with CreatePaletteA()
  982.         numcolors - number of entries to extract
  983.         taglist   - pointer to an array of TagItems
  984.  
  985.    TAGS
  986.         RND_RMHandler (ULONG) - Custom memory handler created with
  987.                 CreateRMHandlerA(). This is used to handle intermediate
  988.                 buffers during quantization.
  989.                 Default - The histogram's memory handler.
  990.  
  991.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  992.                 structure for progress display operations. Refer to
  993.                 render/renderhooks.h for further information.
  994.                 Default - NULL.
  995.  
  996.         RND_RGBWeight (ULONG) - R/G/B quantization factors.
  997.                 They form a relative measurement between the R/G/B
  998.                 components, defining what color components should be
  999.                 preferred when the histogram gets decomposed.
  1000.                 Default - 0x010101 (all components are treat equally).
  1001.  
  1002.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  1003.                 a pixel's actual color. Currently this tag should be
  1004.                 set to COLORMODE_HAM6 if you extract a palette for the
  1005.                 use with a HAM6 image.
  1006.                 Default - COLORMODE_CLUT.
  1007.  
  1008.         RND_FirstColor (ULONG) - first color entry inside the palette
  1009.                 that will be used for the extracted colors. See also
  1010.                 ImportPaletteA() for further details. Default - 0.
  1011.  
  1012.         RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
  1013.                 that you want to dispose the current palette and
  1014.                 create a new one. If set to FALSE, the new color entries
  1015.                 are merged to the existing palette. Default - TRUE.
  1016.  
  1017.    RESULTS
  1018.         result  - returncode to indicate whether the operation
  1019.                   succeeded. You must at least check for
  1020.                   EXTP_SUCCESS.
  1021.  
  1022.    NOTES
  1023.         - This function may call the progress callback Hook
  1024.           with the PMSGTYPE_COLORS_CHOSEN message type.
  1025.  
  1026.    SEE ALSO
  1027.         CreateHistogramA(), CreatePaletteA(), ImportPaletteA(),
  1028.         render/render.h, render/renderhooks.h
  1029.  
  1030.  
  1031. render.library/FlushPalette                       render.library/FlushPalette
  1032.  
  1033.    NAME
  1034.         FlushPalette - flush all buffers from a palette.
  1035.  
  1036.    SYNOPSIS
  1037.         FlushPalette(palette)
  1038.                      a0
  1039.  
  1040.         void FlushPalette(APTR)
  1041.  
  1042.    FUNCTION
  1043.         This function flushes all buffers that might be
  1044.         associated with a palette.
  1045.  
  1046.    INPUTS
  1047.         palette   - pointer to a palette that was
  1048.                     created with CreatePaletteA()
  1049.  
  1050.    RESULTS
  1051.         none
  1052.  
  1053.    SEE ALSO
  1054.         DeletePalette()
  1055.  
  1056.  
  1057. render.library/FreeRenderMem                     render.library/FreeRenderMem
  1058.  
  1059.    NAME
  1060.         FreeRenderMem - return memory to a render-memhandler.
  1061.  
  1062.    SYNOPSIS
  1063.         FreeRenderMem(rendermemhandler,mem,size)
  1064.                       a0               a1  d0
  1065.  
  1066.         void FreeRenderMem(APTR,APTR,ULONG)
  1067.  
  1068.    FUNCTION
  1069.         Free a block of memory that was previously
  1070.         allocated with AllocRenderMem().
  1071.  
  1072.    INPUTS
  1073.         rendermemhandler - pointer to the render-memhandler you have
  1074.                            allocated the memory from
  1075.         mem              - pointer to the memory block to be returned
  1076.         size             - size of that memory block [bytes]
  1077.  
  1078.    RESULTS
  1079.         NONE
  1080.  
  1081.    SEE ALSO
  1082.         AllocRenderMem(), DeleteRMHandler()
  1083.  
  1084.  
  1085. render.library/FreeRenderVec                     render.library/FreeRenderVec
  1086.  
  1087.    NAME
  1088.         FreeRenderVec - return memory to a render-memhandler.
  1089.  
  1090.    SYNOPSIS
  1091.         FreeRenderVec(mem)
  1092.                       a0
  1093.  
  1094.         void FreeRenderVec(APTR)
  1095.  
  1096.    FUNCTION
  1097.         Free a block of memory that was previously
  1098.         allocated with AllocRenderVec().
  1099.  
  1100.    INPUTS
  1101.         mem - pointer to a memory block
  1102.               to be returned to its render-memhandler
  1103.  
  1104.    RESULTS
  1105.         NONE
  1106.  
  1107.    SEE ALSO
  1108.         AllocRenderVec(), DeleteRMHandler()
  1109.  
  1110.  
  1111. render.library/ImportPaletteA                   render.library/ImportPaletteA
  1112.  
  1113.    NAME
  1114.         ImportPaletteA - import a palette.
  1115.         ImportPalette  - varargs stub for ImportPaletteA.
  1116.  
  1117.    SYNOPSIS
  1118.         ImportPaletteA(palette,table,entries,taglist)
  1119.                        a0      a1    d0      a2
  1120.         
  1121.         ImportPaletteA(APTR,APTR,UWORD,struct TagItem *)
  1122.         
  1123.         ImportPalette(APTR,APTR,UWORD,tag,...,TAG_DONE)
  1124.         
  1125.    FUNCTION
  1126.         This function imports entries from a color table to
  1127.         a palette. You are allowed to import multiple times.
  1128.         When doing so, entries will be overwritten (not inserted).
  1129.         The palette automatically grows to the required number of
  1130.         entries. Remember to neither import more than 256 entries
  1131.         nor beyond the 256th entry.
  1132.  
  1133.    INPUTS
  1134.         palette   - pointer to a palette created
  1135.                     with CreatePaletteA()
  1136.         table     - pointer to the source color table
  1137.         entries   - number of color entries to import
  1138.         taglist   - pointer to an array of tag items
  1139.  
  1140.    TAGS
  1141.         RND_PaletteFormat (ULONG) - format of the color table
  1142.                 to be import. Valid types:
  1143.  
  1144.                 PALFMT_RGB32    - ULONG red,green,blue
  1145.                 PALFMT_RGB8     - ULONG 0x00rrggbb
  1146.                 PALFMT_RGB4     - UWORD 0xrgb
  1147.  
  1148.                 Default - PALFMT_RGB8.
  1149.  
  1150.         RND_FirstColor (ULONG) - first destination color entry
  1151.                 to import to. Default - 0.
  1152.  
  1153.         RND_EHBPalette (ULONG) - tag to indicate whether the
  1154.                 palette should be interpreted as for an
  1155.                 Extra-Halfbrite picture. Default - FALSE.
  1156.  
  1157.         RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
  1158.                 that you want to dispose the current palette and
  1159.                 import a new one. If set to FALSE, the palette is
  1160.                 merged. Default - TRUE.
  1161.  
  1162.    RESULTS
  1163.         none
  1164.  
  1165.    SEE ALSO
  1166.         CreatePaletteA(), ExportPaletteA(), render/render.h
  1167.  
  1168.  
  1169. render.library/Planar2ChunkyA                   render.library/Planar2ChunkyA
  1170.  
  1171.    NAME
  1172.         Planar2ChunkyA - convert bitplane data to chunky bytes.
  1173.         Planar2Chunky  - varargs stub for Planar2ChunkyA.
  1174.  
  1175.    SYNOPSIS
  1176.         Planar2ChunkyA(planetab,bytewidth,rows,depth,bytesperrow,
  1177.                        a0       d0        d1   d2    d3
  1178.                        chunkybuffer,taglist)
  1179.                        a1           a2
  1180.  
  1181.         void Planar2ChunkyA(PLANEPTR *,UWORD,UWORD,UWORD,UWORD,
  1182.                             UBYTE *,struct TagItem *)
  1183.         
  1184.         void Planar2Chunky(PLANEPTR *,UWORD,UWORD,UWORD,UWORD
  1185.                             UBYTE *,tag,...,TAG_DONE)
  1186.  
  1187.    FUNCTION
  1188.         Converts raw bitplane-oriented (planar) graphics to an array
  1189.         of chunky bytes.
  1190.  
  1191.    INPUTS
  1192.         planetab    - pointer to a table of planepointers
  1193.         bytewidth   - width [bytes]. This must be an even number.
  1194.         rows        - height [rows]
  1195.         depth       - number of bitplanes
  1196.         bytesperrow - total bytes per row in the source bitplanes.
  1197.                       This must be an even number. If you convert
  1198.                       interleaved bitplanes, multiply by depth.
  1199.         chunky      - pointer to the destination chunky buffer
  1200.         taglist     - pointer to an array of TagItems
  1201.  
  1202.    TAGS
  1203.         RND_DestWidth (UWORD) - Total width of chunky array [pixels].
  1204.                 Default - equals to bytewidth * 8.
  1205.  
  1206.                 You are explicitely allowed to use a destwidth that is
  1207.                 smaller than bytewidth * 8 pixels.
  1208.                 
  1209.                 Important note:
  1210.                 If you specify this tag, you must _still_ supply a
  1211.                 chunky buffer of at least bytewidth * 8 * rows bytes.
  1212.  
  1213.    NOTES
  1214.         Starting with v39, you are not allowed to assume foreign BitMap
  1215.         structures being of a planar type.  Before you grab a table of
  1216.         planepointers out of an unknown BitMap structure and pass it to
  1217.         this function, you have to check for the presence of the
  1218.         BMF_STANDARD flag.
  1219.  
  1220.    RESULTS
  1221.         none
  1222.  
  1223.    SEE ALSO
  1224.         Chunky2BitMapA(), graphics/gfx.h
  1225.  
  1226.  
  1227. render.library/QueryHistogram                   render.library/QueryHistogram
  1228.  
  1229.    NAME
  1230.         QueryHistogram - query a histogram parameter.
  1231.  
  1232.    SYNOPSIS
  1233.         value = QueryHistogram(histogram,tag)
  1234.         d0                     a0        d0
  1235.         
  1236.         ULONG QueryHistogram(APTR,Tag)
  1237.  
  1238.    FUNCTION
  1239.         Query one of a histogram's specifications
  1240.         via Tag parameter.
  1241.  
  1242.    INPUTS
  1243.         histogram - pointer to a histogram
  1244.         tag       - Tag to be queried
  1245.  
  1246.    TAGS
  1247.         RND_NumColors (ULONG) -
  1248.                 the number of different colors inside the histogram.
  1249.  
  1250.         RND_NumPixels (ULONG) -
  1251.                 the number of pixels that have been added to the
  1252.                 histogram.
  1253.  
  1254.         RND_RMHandler (ULONG) -
  1255.                 the histogram's render-memhandler.
  1256.  
  1257.         RND_HSType (UWORD) -
  1258.                 the histogram's type.
  1259.  
  1260.    RESULTS
  1261.         value    - the queried parameter.
  1262.  
  1263.    SEE ALSO
  1264.         CreateHistogramA()
  1265.  
  1266.  
  1267. render.library/RenderA                                 render.library/RenderA
  1268.  
  1269.    NAME
  1270.         RenderA - render an array of RGB data to chunky bytes.
  1271.         Render  - varargs stub for RenderA.
  1272.  
  1273.    SYNOPSIS
  1274.         success = RenderA(rgb,width,height,chunky,palette,taglist)
  1275.         d0                a0  d0    d1     a1     a2      a3
  1276.         
  1277.         ULONG RenderA(ULONG *,UWORD,UWORD,UBYTE *,APTR,struct TagItem *)
  1278.         
  1279.         ULONG Render(ULONG *,UWORD,UWORD,UBYTE *,APTR,tag,...,TAG_DONE)
  1280.  
  1281.    FUNCTION
  1282.         Render an array of RGB data to an array of chunky bytes.
  1283.  
  1284.    INPUTS
  1285.         rgb         - pointer to an array of RGB pixels
  1286.         width       - width to be converted [pixels]
  1287.         height      - height to be converted [rows]
  1288.         chunky      - pointer to the destination array
  1289.         palette     - pointer to a palette to be rendered to
  1290.         taglist     - pointer to an array of TagItems
  1291.  
  1292.    TAGS
  1293.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  1294.                 Default - equals to the specified width.
  1295.  
  1296.         RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
  1297.                 Default - equals to the specified width.
  1298.  
  1299.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  1300.                 a pixel's actual color. Valid types:
  1301.  
  1302.                 COLORMODE_CLUT          - normal palette lookup
  1303.                 COLORMODE_HAM8          - HAM8 mode palette lookup
  1304.                 COLORMODE_HAM6          - HAM6 mode palette lookup
  1305.                 
  1306.                 Default - COLORMODE_CLUT.
  1307.  
  1308.         RND_DitherMode (UWORD) - Error diffusion mode. Valid types:
  1309.  
  1310.                 DITHERMODE_NONE   - no error diffusion
  1311.  
  1312.                 DITHERMODE_FS     - Floyd-Steinberg
  1313.                                     Does not handle a dither amount.
  1314.  
  1315.                 DITHERMODE_RANDOM - Random dithering
  1316.                                     Handles RND_DitherAmount.
  1317.  
  1318.                 Default - DITHERMODE_NONE.
  1319.  
  1320.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  1321.                 structure for progress display operations. Refer to
  1322.                 render/renderhooks.h for further information.
  1323.                 Default - NULL.
  1324.  
  1325.         RND_OffsetColorZero (UWORD) - First color index to appear
  1326.                 in the rendered chunky image. This offset will be
  1327.                 added to the palette's indices. Default - 0.
  1328.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  1329.  
  1330.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  1331.                 for a secondary conversion of the pen numbers.
  1332.                 Default - NULL.
  1333.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  1334.  
  1335.         RND_LineHook (ULONG) - Pointer to a callback hook structure
  1336.                 for line-related operations during render. This hook
  1337.                 is executed once before a line is rendered and once
  1338.                 after a line has been completed. Refer to
  1339.                 render/renderhooks.h for further information.
  1340.                 Default - NULL.
  1341.  
  1342.         RND_DitherAmount (UWORD) - Dither intensity (0-255).
  1343.                 Only valid with certain dither modes (see above).
  1344.                 Default - 128.
  1345.  
  1346.    RESULTS
  1347.         result  - returncode to indicate whether the operation
  1348.                   succeeded. You must at least check for
  1349.                   REND_SUCCESS.
  1350.  
  1351.    NOTES
  1352.         - This function may call the progress callback Hook with
  1353.           the PMSGTYPE_LINES_RENDERED message type.
  1354.  
  1355.    SEE ALSO
  1356.         render/render.h, render/renderhooks.h
  1357.  
  1358.  
  1359. render.library/ScaleA                                   render.library/ScaleA
  1360.  
  1361.    NAME
  1362.         ScaleA - scale an image.
  1363.         Scale  - varargs stub for ScaleA.
  1364.  
  1365.    SYNOPSIS
  1366.         ScaleA(engine,source,dest,taglist)
  1367.                a0     a1     a2   a3
  1368.         
  1369.         void ScaleA(APTR,APTR,APTR,struct TagItem *)
  1370.         
  1371.         void Scale(APTR,APTR,APTR,tag,...,TAG_DONE)
  1372.  
  1373.    FUNCTION
  1374.         Scales a source array of pixels to another array.
  1375.  
  1376.    INPUTS
  1377.         engine  - pointer to a scaling-engine created
  1378.                   with CreateScaleEngineA()
  1379.         source  - pointer to source array of pixels
  1380.         dest    - pointer to destination array
  1381.         taglist - pointer to an array of TagItems
  1382.  
  1383.    TAGS
  1384.         RND_SourceWidth (UWORD) - Total width of the source array [pixels].
  1385.                 Default - equals to the source width the scaling-engine
  1386.                           was created with.
  1387.  
  1388.         RND_DestWidth (UWORD) - Total width of the dest array [pixels].
  1389.                 Default - equals to the destination width the
  1390.                           scaling-engine was created with.
  1391.    RESULTS
  1392.         none
  1393.  
  1394.    SEE ALSO
  1395.         CreateScaleEngineA()
  1396.  
  1397.  
  1398. render.library/ScaleOrdinate                     render.library/ScaleOrdinate
  1399.  
  1400.    NAME
  1401.         ScaleOrdinate - scale a single ordinate.
  1402.  
  1403.    SYNOPSIS
  1404.         scaled_ordinate = ScaleOrdinate(start,dest,ordinate)
  1405.         d0                              d0    d1   d2
  1406.  
  1407.         UWORD ScaleOrdinate(UWORD,UWORD,UWORD)
  1408.  
  1409.    FUNCTION
  1410.         This function scales a single ordinate. The algorythm
  1411.         used here is identical to what scaling-engines are
  1412.         created with.
  1413.         
  1414.    EXAMPLE        
  1415.         Assume you have a specific pair of coordinates
  1416.         that represent a particular pixel inside an image.
  1417.         You can use this function to determine the pixel's
  1418.         new coordinates after the image has been scaled:
  1419.  
  1420.         new_pixel_x = ScaleOrdinate(picwidth,newwidth,pixel_x);
  1421.         new_pixel_y = ScaleOrdinate(picheight,newheight,pixel_y);
  1422.  
  1423.    INPUTS
  1424.         start    - original value (e.g. width or height)
  1425.                    e.g. the original width of an image.
  1426.                    This value usually corresponds to a
  1427.                    start value with CreateScaleEngineA().
  1428.                    Must not be 0.
  1429.         dest     - destination value (e.g. width or height)
  1430.                    e.g. the scaled width of an image.
  1431.                    This value usually corresponds to a
  1432.                    dest value with CreateScaleEngineA().
  1433.                    Must not be 0.
  1434.         ordinate - a single ordinate (e.g. of a pixel).
  1435.                    Must be less than <start>.
  1436.  
  1437.    RESULTS
  1438.         scaled_ordinate - the new ordinate (after scaling)
  1439.         
  1440.    SEE ALSO
  1441.         CreateScaleEngineA()
  1442.  
  1443.  
  1444. render.library/SortPaletteA                       render.library/SortPaletteA
  1445.  
  1446.    NAME
  1447.         SortPaletteA - sort a palette.
  1448.         SortPalette  - varargs stub for SortPaletteA.
  1449.  
  1450.    SYNOPSIS
  1451.         success = SortPaletteA(palette,mode,taglist)
  1452.         d0                     a0      d0   a1
  1453.         
  1454.         ULONG SortPaletteA(APTR,ULONG,struct TagItem *)
  1455.         
  1456.         ULONG SortPalette(APTR,ULONG,tag,...,TAG_DONE)
  1457.  
  1458.    FUNCTION
  1459.         Sorts a palette according to a sort mode.
  1460.         Some sort modes apply to palettes solely, some
  1461.         others additionally require a histogram.
  1462.  
  1463.    INPUTS
  1464.         palette - pointer to a palette created
  1465.                   with CreatePaletteA().
  1466.  
  1467.         mode    - sort mode. Currently defined are:
  1468.  
  1469.                   PALMODE_BRIGHTNESS      - sort the palette entries
  1470.                                 by brightness.
  1471.  
  1472.                   PALMODE_SATURATION      - sort the palette entries
  1473.                                 by their color intensity.
  1474.  
  1475.                   PALMODE_POPULARITY      - sort the palette entries
  1476.                                 by the number of pixels that they
  1477.                                 represent. You must specify the
  1478.                                 RND_Histogram taglist argument.
  1479.  
  1480.                   PALMODE_REPRESENTATION  - sort the palette entries
  1481.                                 by the number of histogram entries
  1482.                                 that they represent. You must specify
  1483.                                 the RND_Histogram taglist argument.
  1484.                   
  1485.                   PALMODE_SIGNIFICANCE    - sort the palette entries
  1486.                                 by their optical significance for the
  1487.                                 human eye. Implementation is unknown
  1488.                                 to you and may change. You must supply
  1489.                                 the RND_Histogram taglist argument.
  1490.  
  1491.                   PALMODE_ASCENDING       - by default, sort direction
  1492.                                 is descending, i.e. precedence is
  1493.                                 `more-to-less' of the given effect.
  1494.                                 Combine with this flag to invert the
  1495.                                 sort direction.
  1496.  
  1497.         taglist - pointer to an array of tagitems.
  1498.  
  1499.    TAGS
  1500.         RND_Histogram (ULONG) - pointer to a histogram. This taglist
  1501.                 argument is obligatory for some sort modes. (See above)
  1502.  
  1503.    RESULTS
  1504.         success - return value to indicate whether the operation succeeded.
  1505.                   You must at least check for SORTP_SUCCESS.
  1506.  
  1507.    SEE ALSO
  1508.         render/render.h
  1509.  
  1510.  
  1511.