@database "render"
@master "Randgruppe:Temporary/RenderLib/Doc/Autodoc/render.doc"

@Node Main "render.doc"
    @{" AddChunkyImageA() " Link "AddChunkyImageA()"}
    @{" AddHistogramA() " Link "AddHistogramA()"}
    @{" AddRGB() " Link "AddRGB()"}
    @{" AddRGBImageA() " Link "AddRGBImageA()"}
    @{" AllocRenderMem() " Link "AllocRenderMem()"}
    @{" AllocRenderVec() " Link "AllocRenderVec()"}
    @{" BestPen() " Link "BestPen()"}
    @{" Chunky2BitMapA() " Link "Chunky2BitMapA()"}
    @{" Chunky2RGBA() " Link "Chunky2RGBA()"}
    @{" ConvertChunkyA() " Link "ConvertChunkyA()"}
    @{" CountRGB() " Link "CountRGB()"}
    @{" CreateHistogramA() " Link "CreateHistogramA()"}
    @{" CreatePaletteA() " Link "CreatePaletteA()"}
    @{" CreatePenTableA() " Link "CreatePenTableA()"}
    @{" CreateRMHandlerA() " Link "CreateRMHandlerA()"}
    @{" CreateScaleEngineA() " Link "CreateScaleEngineA()"}
    @{" DeleteHistogram() " Link "DeleteHistogram()"}
    @{" DeletePalette() " Link "DeletePalette()"}
    @{" DeleteRMHandler() " Link "DeleteRMHandler()"}
    @{" DeleteScaleEngine() " Link "DeleteScaleEngine()"}
    @{" ExportPaletteA() " Link "ExportPaletteA()"}
    @{" ExtractPaletteA() " Link "ExtractPaletteA()"}
    @{" FlushPalette() " Link "FlushPalette()"}
    @{" FreeRenderMem() " Link "FreeRenderMem()"}
    @{" FreeRenderVec() " Link "FreeRenderVec()"}
    @{" ImportPaletteA() " Link "ImportPaletteA()"}
    @{" Planar2ChunkyA() " Link "Planar2ChunkyA()"}
    @{" QueryHistogram() " Link "QueryHistogram()"}
    @{" RenderA() " Link "RenderA()"}
    @{" ScaleA() " Link "ScaleA()"}
    @{" ScaleOrdinate() " Link "ScaleOrdinate()"}
    @{" SortPaletteA() " Link "SortPaletteA()"}
@EndNode

@Node "AddChunkyImageA()" "render.library/AddChunkyImageA"

@{b}   NAME@{ub}
        AddChunkyImageA - add chunky bytes to a histogram.
        AddChunkyImage  - varargs stub for AddChunkyImageA.

@{b}   SYNOPSIS@{ub}
        success = AddChunkyImageA(histogram,chunky,width,height,
        d0                        a0        a1     d0    d1     
                                  palette,taglist)
                                  a2      a3
        
        ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
                              APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
                              APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function adds an array of chunky bytes to a
        histogram. The color information contained in the
        chunky array gets stored in the histogram.

@{b}   INPUTS@{ub}
        histogram       - pointer to a histogram
        chunky          - pointer to an array of chunky bytes
        width           - width to be added [pixels]
        height          - lines to be added [rows]
        palette         - pointer to a palette object
                          created with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        taglist         - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.
        
@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   NOTES@{ub}
        - It is not possible with this function to directly add a chunky
          array that represents a HAM color scheme. In this case you have
          to convert it to an RGB array via @{"Chunky2RGBA()" Link "Chunky2RGBA()"}, and then to call
          @{"AddRGBImageA()" Link "AddRGBImageA()"}.
           
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_ADDED message.
        
@{b}   SEE ALSO@{ub}
        @{"AddRGBImageA()" Link "AddRGBImageA()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "AddHistogramA()" "render.library/AddHistogramA"

@{b}   NAME@{ub}
        AddHistogramA - add a histogram to another histogram.
        AddHistogram  - varargs stub for AddHistogramA.

@{b}   SYNOPSIS@{ub}
        success = AddHistogramA(desthistogram,sourcehistogram,taglist)
        d0                      a0            a1              a2
        
        ULONG AddHistogramA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddHistogramA(APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function adds a histogram to another histogram,
        according to the following scheme:
        
        desthistogram + sourcehistogram -> desthistogram
        
        The color information contained in the source histogram
        will be added to the destination histogram.

@{b}   INPUTS@{ub}
        desthistogram       - pointer to destination histogram
        sourcehistogram     - pointer to source histogram
        taglist             - pointer to an array of TagItems

@{b}   TAGS@{ub}
        None defined. Pass NULL.

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.
       
@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "AddRGB()" "render.library/AddRGB"

@{b}   NAME@{ub}
        AddRGB - add a RGB value to a histogram.

@{b}   SYNOPSIS@{ub}
        success = AddRGB(histogram,RGB,count)
        d0               a0        d0  d1
        
        ULONG AddRGB(APTR,ULONG,ULONG)

@{b}   FUNCTION@{ub}
        This function adds a single RGB value plus the number
        of its representations to a histogram.

@{b}   INPUTS@{ub}
        histogram    - pointer to a histogram
        RGB          - RGB value to be added
        count        - number of represantations for that RGB value

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   SEE ALSO@{ub}
        @{"AddRGBImageA()" Link "AddRGBImageA()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "AddRGBImageA()" "render.library/AddRGBImageA"

@{b}   NAME@{ub}
        AddRGBImageA - add an array of RGB data to a histogram.
        AddRGBImage  - varargs stub for AddRGBImageA.

@{b}   SYNOPSIS@{ub}
        success = AddRGBImageA(histogram,rgb,width,height,taglist)
        d0                     a0        a1  d0    d1     a2
        
        ULONG AddRGBImageA(APTR,ULONG *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG AddRGBImage(APTR,ULONG *,UWORD,UWORD,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        This function adds an array of RGB pixels to a
        histogram. The color information contained in the
        RGB array gets stored in the histogram.

@{b}   INPUTS@{ub}
        histogram       - pointer to a histogram
        rgb             - pointer to an array of RGB data
        width           - width to be added [pixels]
        height          - lines to be added [rows]
        taglist         - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for ADDH_SUCCESS. Adding data to
                  histograms may fail at any time and the histogram may
                  thereof get inaccurate.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_ADDED message.
        
@{b}   SEE ALSO@{ub}
        @{"AddRGB()" Link "AddRGB()"}, @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "AllocRenderMem()" "render.library/AllocRenderMem"

@{b}   NAME@{ub}
        AllocRenderMem - allocate memory from a render-memhandler.

@{b}   SYNOPSIS@{ub}
        mem = AllocRenderMem(rendermemhandler,size)
        d0                   a0               d0

        APTR AllocRenderMem(APTR, ULONG)

@{b}   FUNCTION@{ub}
        AllocRenderMem will allocate a memory block from a
        render-memhandler, or from public memory. If there is no
        memory block of the requested size available, NULL will be
        returned. You must check this return value. The request
        may fail at any time. Every call to this function must be
        followed by a call to @{"FreeRenderMem" Link "render/FreeRenderMem()"}.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to a render-memhandler, or NULL.
                           If you pass NULL, MEMF_ANY will be used.
        size             - the size of the desired block in bytes

@{b}   RESULTS@{ub}
        mem              - pointer to a block of memory, or NULL if the
                           allocation failed.

@{b}   NOTES@{ub}
        There is no real need for this function being available to
        you, except for helping you to create a smart, lean and sexy
        memory management - the idea is to enable your application
        and the library to share a particular memory pool.

@{b}   SEE ALSO@{ub}
        @{"FreeRenderMem()" Link "FreeRenderMem()"}, @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "AllocRenderVec()" "render.library/AllocRenderVec"

@{b}   NAME@{ub}
        AllocRenderVec - allocate memory from a render-memhandler, 
                         keeping track of the allocated size and
                         the memhandler itself.

@{b}   SYNOPSIS@{ub}
        mem = AllocRenderVec(rendermemhandler,size)
        d0                   a0               d0

        APTR AllocRenderVec(APTR, ULONG)

@{b}   FUNCTION@{ub}
        AllocRenderVec will allocate a memory block from a
        render-memhandler, or from public memory. If there is no
        memory block of the requested size available, NULL will be
        returned. You must check this return value. The request
        may fail at any time. Any call to this function must be
        followed by a call to @{"FreeRenderVec()" Link "FreeRenderVec()"}. AllocRenderVec()
        keeps track of the allocated size and the memhandler itself.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to a render-memhandler, or NULL.
                           If you pass NULL, MEMF_ANY will be used.
        size             - the size of the desired block in bytes

@{b}   RESULTS@{ub}
        mem              - pointer to a block of memory, or NULL
                           if the allocation failed.

@{b}   SEE ALSO@{ub}
        @{"FreeRenderVec()" Link "FreeRenderVec()"}, @{"AllocRenderMem()" Link "AllocRenderMem()"}, @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "BestPen()" "render.library/BestPen"

@{b}   NAME@{ub}
        BestPen - find the best matching pen.

@{b}   SYNOPSIS@{ub}
        pen = BestPen(palette,RGB)
        d0            a0      d0
        
        LONG BestPen(APTR,ULONG)

@{b}   FUNCTION@{ub}
        Calculate a palette's pen number that matches best
        a given RGB value.

@{b}   INPUTS@{ub}
        palette   - palette created with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        RGB       - RGB value to find a match for

@{b}   RESULTS@{ub}
        pen       - pen number or -1 if no pen could be found.
                    (Usually this occurs when the palette is empty.)


@EndNode

@Node "Chunky2BitMapA()" "render.library/Chunky2BitMapA"

@{b}   NAME@{ub}
        Chunky2BitMapA - convert chunky data to bitplanes.
        Chunky2BitMap  - varargs stub for Chunky2BitMapA.

@{b}   SYNOPSIS@{ub}
        Chunky2BitMapA(chunky,sx,sy,width,height,bitmap,dx,dy,taglist)
                       a0     d0 d1 d2    d3     a1     d4 d5 a2
        
        void Chunky2BitMapA(UBYTE *,UWORD,UWORD,UWORD,UWORD,
                            struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void Chunky2BitMap(UBYTE *,UWORD,UWORD,UWORD,UWORD,
                           struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *,UWORD,UWORD,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        Converts an array of chunky bytes to the bitplanes
        associated with a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure. You can specify
        clip areas both inside the chunky array and the
        @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}. This function merges the data into the
        destination @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} if required. BMF_INTERLEAVED is
        also handled.
        
        You may only process BMF_STANDARD bitmaps with this
        function.

@{b}   INPUTS@{ub}
        chunky     - pointer to an array of chunky bytes
        sx         - left edge inside the chunky array [pixels]
        sy         - top edge inside the chunky array [rows]
        width      - width [pixels]
        height     - height [rows]
        bitmap     - pointer to an initialized @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure
        dx         - destination left edge inside @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [pixels]
        dy         - destination top edge inside @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [rows]
        taglist    - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for an additional conversion of the pen numbers.
                Default - NULL.

@{b}   RESULTS@{ub}
        none

@{b}   IMPORTANT NOTES@{ub}
        Starting with v39, you are not allowed to assume foreign
        @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structures being of a planar type. You may pass a
        @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure to this function only if the BMF_STANDARD
        flag is set.

        Also remember to set-up your own @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure with the
        BMF_STANDARD flag if you wish to convert it with this
        function. Consider Chunky2BitMapA() being low-level. The
        @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure involved here is intended to hold planar
        information. Since v39, this is different to what
        graphics.library might associate with a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure.

        Do NOT use this function with @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structures that are
        actually being displayed. If you wish to transfer chunky
        bytes to visible areas, use graphics.library functions, such
        as @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}, or @{"WritePixelArray8()" Link "graphics/WritePixelArray8()"}. You may also
        use Chunky2BitMapA() followed by @{"BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"} etc.

        With a graphics card supplied, @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"} can be
        hundereds times faster than Chunky2BitMapA() followed by
        @{"BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"}. If you have to provide backward
        compatibility, it is worth the effort to differenciate between
        Kick 2.x and OS 3.x. Use Chunky2BitMapA() in the first case,
        @{"WritePixelArray8()" Link "graphics/WritePixelArray8()"} in the second case, and @{"WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}
        if the system runs under OS3.1 and is supplied with a graphics
        card.

SEE ALSO
        @{"Planar2ChunkyA()" Link "Planar2ChunkyA()"}, @{"graphics/gfx.h" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 0},
        @{"graphics.library/WriteChunkyPixels()" Link "graphics/WriteChunkyPixels()"}


@EndNode

@Node "Chunky2RGBA()" "render.library/Chunky2RGBA"

@{b}   NAME@{ub}
        Chunky2RGBA - convert an array of chunky bytes to RGB data.
        Chunky2RGB  - varargs stub for Chunky2RGBA.

@{b}   SYNOPSIS@{ub}
        success = Chunky2RGBA(chunky,width,height,rgb,palette,taglist)
        d0                    a0     d0    d1     a1  a2      a3
        
        ULONG Chunky2RGBA(UBYTE *,UWORD,UWORD,ULONG *,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG Chunky2RGB(UBYTE *,UWORD,UWORD,ULONG *,APTR,tag,...,TAG_DONE) 

@{b}   FUNCTION@{ub}
        This function converts an array of chunky bytes to RGB data.

@{b}   INPUTS@{ub}
        chunky      - pointer to an array of chunky bytes
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        rgb         - pointer to RGB destination buffer
        palette     - pointer to a palette object created
                      with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Valid types:

                COLORMODE_CLUT          - normal palette lookup
                COLORMODE_HAM8          - HAM8 mode palette lookup
                COLORMODE_HAM6          - HAM6 mode palette lookup
                
                Default - COLORMODE_CLUT.

        RND_LeftEdge (UWORD) - Horizontal starting position inside the
                chunky array [pixels]. This is mainly intended to allow
                the conversion of HAM clip areas.
                Default - 0.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for an additional conversion of the pen numbers.
                Default - NULL.
                Note: This is not defined for HAM modes.

@{b}   RESULTS@{ub}
        result  - CONV_SUCCESS to indicate that the operation
                  succeeded. Currently, the only reason for this
                  function to fail is CONV_CALLBACK_ABORTED.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27}
          with the PMSGTYPE_LINES_CONVERTED message type.

@{b}   SEE ALSO@{ub}
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "ConvertChunkyA()" "render.library/ConvertChunkyA"

@{b}   NAME@{ub}
        ConvertChunkyA - convert an array of chunky bytes to a new palette.
        ConvertChunky  - varargs stub for ConvertChunkyA.

@{b}   SYNOPSIS@{ub}
        ConvertChunkyA(source,sourcepalette,width,height,dest,        
                       a0     a1            d0    d1     a2   
                       destpalette,taglist)
                       a3          a4
        
        void ConvertChunkyA(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                            APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void ConvertChunky(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
                           APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function converts a source array of chunky bytes
        to another array, and adapts it to a new palette.
        Optionally, a secondary pen conversion is performed.

@{b}   INPUTS@{ub}
        source        - pointer to the source array of chunky data
        sourcepalette - pointer to the source array's palette
        width         - width to be converted [pixels]
        height        - height to be converted [rows]
        dest          - pointer to the destination chunky array
        destpalette   - pointer to the destination array's palette
        taglist       - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of source array [pixels].
                Default - equals to the width specified.

        RND_DestWidth (UWORD) - Total width of dest array [pixels].
                Default - equals to the width specified.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL. 
        
@{b}   RESULTS@{ub}
        none
        
@{b}   SEE ALSO@{ub}
        @{"CreatePenTableA()" Link "CreatePenTableA()"}, @{"CreatePaletteA()" Link "CreatePaletteA()"}


@EndNode

@Node "CreateHistogramA()" "render.library/CreateHistogramA"

@{b}   NAME@{ub}
        CreateHistogramA - create and set up a histogram.
        CreateHistogram  - varargs stub for CreateHistogramA.

@{b}   SYNOPSIS@{ub}
        hst = CreateHistogramA(taglist)
        d0                     a1
        
        APTR CreateHistogramA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateHistogram(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Allocates and initializes a histogram.

@{b}   INPUTS@{ub}
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - pointer to a render-memhandler
                created with @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}.
                Default - NULL.

        RND_HSType (UWORD) - Type of histogram. Valid types:

                HSTYPE_12BIT            - 12bit dynamic histogram
                HSTYPE_15BIT            - 15bit dynamic histogram
                HSTYPE_18BIT            - 18bit dynamic histogram
                HSTYPE_21BIT            - 21bit dynamic histogram
                HSTYPE_24BIT            - 24bit dynamic histogram
                HSTYPE_12BIT_TURBO      - 12bit tabular histogram
                HSTYPE_15BIT_TURBO      - 15bit tabular histogram
                HSTYPE_18BIT_TURBO      - 18bit tabular histogram

                Default - HSTYPE_15BIT_TURBO.

@{b}   RESULTS@{ub}
        histogram - pointer to a histogram ready for usage,
                    or NULL if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeleteHistogram()" Link "DeleteHistogram()"}, @{"QueryHistogram()" Link "QueryHistogram()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "CountRGB()" "render.library/CountRGB"

@{b}   NAME@{ub}
        CountRGB     - count a RGB value in a histogram.

@{b}   SYNOPSIS@{ub}
        count = CountRGB(histogram,RGB)
        d0               a0        d0
        
        ULONG CountRGB(APTR,ULONG)

@{b}   FUNCTION@{ub}
        Counts the number of occurances for a particular RGB value.
        The result may depend on the histogram's accuracy.

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram

@{b}   RESULTS@{ub}
        count     - number of representations for the
                    specified RGB value.

@{b}   NOTE@{ub}
        You only get the exact result for 24bit histograms. The
        lower the resolution, the more colors are actually put
        together into one `category' of similar colors. A 24bit
        histogram differenciates 16,7 million colors, a 15bit
        histogram, for instance, only 32768.


@EndNode

@Node "CreatePaletteA()" "render.library/CreatePaletteA"

@{b}   NAME@{ub}
        CreatePaletteA - create a palette.
        CreatePalette  - vararg stub for CreatePaletteA.

@{b}   SYNOPSIS@{ub}
        palette = CreatePaletteA(taglist)
        d0                       a1
        
        APTR CreatePaletteA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreatePalette(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function creates and initializes a palette
        that can hold up to 256 color entries.

@{b}   INPUTS@{ub}
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_HSType (ULONG) - the palette's resolution. Palette adaption
                accuracy and memory consumption depend on this constant.
                A palette's resolution is specified analogously to a
                histogram's resolution. Valid types are in the range
                from 12 to 18 bit:

                HSTYPE_12BIT
                HSTYPE_15BIT
                HSTYPE_18BIT

                Default - HSTYPE_15BIT.

        RND_RMHandler (ULONG) - pointer to a render-memhandler that was
                created with CreateRMHandler(). Default - NULL.
        
@{b}   RESULTS@{ub}
        palette  - a palette ready for usage,
                   or NULL if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeletePalette()" Link "DeletePalette()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"}, @{"ExportPaletteA()" Link "ExportPaletteA()"}, 
        @{"ExtractPaletteA()" Link "ExtractPaletteA()"}, @{"FlushPalette()" Link "FlushPalette()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "CreatePenTableA()" "render.library/CreatePenTableA"

@{b}   NAME@{ub}
        CreatePenTableA - create a pen conversion table.
        CreatePenTable  - varargs stub for CreatePenTableA.

@{b}   SYNOPSIS@{ub}
        CreatePenTableA(chunky,oldpalette,width,height,newpalette,
                        a0     a1         d0    d1     a2
                        pentab,taglist)
                        a3     a4
        
        void CreatePenTableA(UBYTE *,APTR,UWORD,UWORD,APTR,
                             UBYTE *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void CreatePenTable(UBYTE *,APTR,UWORD,UWORD,APTR,
                            UBYTE *,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function creates a table for the conversion of a
        particular array of chunky bytes. It scans through the
        chunky array, adapts the found palette entries to a new
        palette, and generates an output table of 256 UBYTEs.
        
        This function is equivalent to @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, except
        for that it does not actually convert the chunky image,
        but instead creates the conversion table for that palette
        adaption.

@{b}   INPUTS@{ub}
        chunky      - pointer to an array of chunky bytes
        oldpalette  - pointer to the original palette
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        newpalette  - pointer to a palette to be adapted to
        pentab      - pointer to the destination table
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.
        
@{b}   RESULTS@{ub}
        none
        
@{b}   NOTES@{ub}
        The destination table is assumed to have 256 entries,
        with no respect to what color indices actually occur in
        the chunky image.

@{b}   SEE ALSO@{ub}
        @{"ConvertChunkyA()" Link "ConvertChunkyA()"}, @{"CreatePaletteA()" Link "CreatePaletteA()"}


@EndNode

@Node "CreateRMHandlerA()" "render.library/CreateRMHandlerA"

@{b}   NAME@{ub}
        CreateRMHandlerA - Create and set up a memory handler.
        CreateRMHandler  - varargs stub for CreateRMHandlerA.

@{b}   SYNOPSIS@{ub}
        rmh = CreateRMHandlerA(taglist)
        d0                     a1
        
        APTR CreateRMHandlerA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateRMHandler(tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function allocates and initializes a render-memhandler.
        This is a custom memory resource manager for histograms,
        rendering, and many other operations. You may use a
        render-memhandler for your own purposes, too.

        A render-memhandler helps to avoid memory fragmentation as
        well as extreme stressing of the system's public memory lists.
        Private memory management is supported as well as v39 exec
        pools and common public memory. Future versions might provide
        more types of memory management.

@{b}   INPUTS@{ub}
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_MemType (UWORD) - type of memory management. Valid types:

                RMHTYPE_POOL            - v39 exec dynamic pool
                RMHTYPE_PRIVATE         - you supply a private memory pool
                RMHTYPE_PUBLIC          - use common public memory

                Default - RMHTYPE_PUBLIC.

        RND_MemBlock (ULONG) - pointer to a block of memory
                used for private memory management. This tag
                is obligatory if you specify RMHTYPE_PRIVATE
                and is ignored otherwise. 
                Default - none.

        RND_MemSize (ULONG) - size of the memory block used
                for private memory management. This tag is
                obligatory if you specify RMHTYPE_PRIVATE
                and is ignored otherwise. 
                Default - none.

        RND_MemFlags (ULONG) - memory flags, as defined in
                @{"exec/memory.h" Link "TEXT_INCLUDE:exec/memory.h/Main" 0}. These are ignored for
                RMHTYPE_PRIVATE. Default - MEMF_ANY.

@{b}   RESULTS@{ub}
        rmh - a render-memhandler ready for usage, or NULL if
              something went wrong.

@{b}   NOTES@{ub}
        You must check for the presence of exec v39 before
        you create a memhandler with RMHTYPE_POOL specified.

@{b}   SEE ALSO@{ub}
        @{"AllocRenderMem()" Link "AllocRenderMem()"}, @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"DeleteRMHandler()" Link "DeleteRMHandler()"},
        @{"exec.library/CreatePool()" Link "exec/CreatePool()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"exec/memory.h" Link "TEXT_INCLUDE:exec/memory.h/Main" 0}


@EndNode

@Node "CreateScaleEngineA()" "render.library/CreateScaleEngineA"

@{b}   NAME@{ub}
        CreateScaleEngineA - Create a scaling-engine.
        CreateScaleEngine  - varargs stub for CreateScaleEngineA.

@{b}   SYNOPSIS@{ub}
        scaleengine = CreateScaleEngineA(sourcewidth,sourceheight,
        d0                               d0          d1           
                                         destwidth,destheight,taglist)
                                         d2        d3         a1
        
        APTR CreateScaleEngineA(UWORD,UWORD,UWORD,
                                UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreateScaleEngine(UWORD,UWORD,UWORD,
                               UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Allocates and initializes a scaling-engine for a specific
        set of scaling parameters. Once set up, this scaling-engine
        is highly optimized for these particular parameter
        specifications.

@{b}   INPUTS@{ub}
        sourcewidth  - source width [pixels]
        sourceheight - source height [rows]
        destwidth    - destination width [pixels]
        destheight   - destination height [rows]
        taglist      - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - pointer to a render-memhandler,
                such as created with @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}.
                Default - NULL.

        RND_PixelFormat (ULONG) - Type of data to process.
                Currently defined are PIXFMT_CHUNKY_CLUT
                and PIXFMT_0RGB_32. Default - PIXFMT_CHUNKY_CLUT.

@{b}   RESULTS@{ub}
        engine - a scaling-engine ready for usage, or NULL
                 if something went wrong.

@{b}   SEE ALSO@{ub}
        @{"DeleteScaleEngine()" Link "DeleteScaleEngine()"}, @{"ScaleA()" Link "ScaleA()"}


@EndNode

@Node "DeleteHistogram()" "render.library/DeleteHistogram"

@{b}   NAME@{ub}
        DeleteHistogram - dispose a histogram.

@{b}   SYNOPSIS@{ub}
        DeleteHistogram(histogram)
                        a0

        void DeleteHistogram(APTR)

@{b}   FUNCTION@{ub}
        Removes a histogram and frees all associated memory.

@{b}   INPUTS@{ub}
        histogram   - pointer to a histogram

@{b}   RESULTS@{ub}
        none


@EndNode

@Node "DeleteRMHandler()" "render.library/DeleteRMHandler"

@{b}   NAME@{ub}
        DeleteRMHandler - free a render-memhandler.

@{b}   SYNOPSIS@{ub}
        DeleteRMHandler(rendermemhandler)
                        a0

        void DeleteRMHandler(APTR)

@{b}   FUNCTION@{ub}
        DeleteRMHandler() will remove and free a previously created
        render-memhandler. That does not imply that any outstanding
        memory will be returned to the system or to whatever memory
        ressources. You are responsible for freeing each memory block
        that you have allocated from a render-memhandler.

@{b}   INPUTS@{ub}
        render-memhandler - a render-memhandler to be deleted.

@{b}   RESULTS@{ub}
        none

@{b}   NOTES@{ub}
        You are not allowed to call DeleteRMHandler() before
        every single byte has been returned to the memhandler.

@{b}   SEE ALSO@{ub}
        @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}


@EndNode

@Node "DeletePalette()" "render.library/DeletePalette"

@{b}   NAME@{ub}
        DeletePalette - dispose a palette.

@{b}   SYNOPSIS@{ub}
        DeletePalette(palette)
                      a0

        void DeletePalette(APTR)

@{b}   FUNCTION@{ub}
        This function deletes a palette and frees all
        associated memory.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette, such as created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"FlushPalette()" Link "FlushPalette()"}


@EndNode

@Node "DeleteScaleEngine()" "render.library/DeleteScaleEngine"

@{b}   NAME@{ub}
        DeleteScaleEngine - dispose a scaling-engine.

@{b}   SYNOPSIS@{ub}
        DeleteScaleEngine(engine)
                          a0

        void DeleteScaleEngine(APTR)

@{b}   FUNCTION@{ub}
        Deletes a scaling-engine and frees all associated memory.

@{b}   INPUTS@{ub}
        engine   - a scaling-engine to be removed

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}, @{"ScaleA()" Link "ScaleA()"}


@EndNode

@Node "ExportPaletteA()" "render.library/ExportPaletteA"

@{b}   NAME@{ub}
        ExportPaletteA - export a palette.
        ExportPalette  - varargs stub for ExportPaletteA.

@{b}   SYNOPSIS@{ub}
        ExportPaletteA(palette,buffer,taglist)
                       a0      a1     a2
        
        ExportPaletteA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ExportPalette(APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function exports a palette (or a part of it)
        to a colortable.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        buffer    - pointer to a destination buffer
        taglist   - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_PaletteFormat (ULONG) - format of the color table
                to be exported. Valid types:

                PALFMT_RGB32    - ULONG red,green,blue
                PALFMT_RGB8     - ULONG 0x00rrggbb
                PALFMT_RGB4     - UWORD 0xrgb

                Default - PALFMT_RGB8.

        RND_FirstColor (ULONG) - first color entry to export.
                Default - 0.
        
        RND_NumColors (ULONG) - number of colors to export.
                Default - the number of colors inside the palette.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"}


@EndNode

@Node "ExtractPaletteA()" "render.library/ExtractPaletteA"

@{b}   NAME@{ub}
        ExtractPaletteA - extract a palette from a histogram.
        ExtractPalette  - varargs stub for ExtractPaletteA.

@{b}   SYNOPSIS@{ub}
        success = ExtractPaletteA(histogram,palette,numcolors,taglist)
        d0                        a0        a1      d0        a2
        
        ULONG ExtractPaletteA(APTR,ULONG *,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG ExtractPalettA(APTR,ULONG *,UWORD,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        This function extracts a given number of colors from a
        histogram. This results in a color lookup table (also called
        a palette).

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        numcolors - number of entries to extract
        taglist   - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_RMHandler (ULONG) - @{"Custom" Link "TEXT_INCLUDE:hardware/custom.h/Main" 24} memory handler created with
                @{"CreateRMHandlerA()" Link "CreateRMHandlerA()"}. This is used to handle intermediate
                buffers during quantization.
                Default - The histogram's memory handler.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_RGBWeight (ULONG) - R/G/B quantization factors.
                They form a relative measurement between the R/G/B
                components, defining what color components should be
                preferred when the histogram gets decomposed.
                Default - 0x010101 (all components are treat equally).

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Currently this tag should be
                set to COLORMODE_HAM6 if you extract a palette for the
                use with a HAM6 image.
                Default - COLORMODE_CLUT.

        RND_FirstColor (ULONG) - first color entry inside the palette
                that will be used for the extracted colors. See also
                @{"ImportPaletteA()" Link "ImportPaletteA()"} for further details. Default - 0.

        RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
                that you want to dispose the current palette and
                create a new one. If set to FALSE, the new color entries
                are merged to the existing palette. Default - TRUE.

@{b}   RESULTS@{ub}
        result  - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  EXTP_SUCCESS.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27}
          with the PMSGTYPE_COLORS_CHOSEN message type.

@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}, @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ImportPaletteA()" Link "ImportPaletteA()"},
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "FlushPalette()" "render.library/FlushPalette"

@{b}   NAME@{ub}
        FlushPalette - flush all buffers from a palette.

@{b}   SYNOPSIS@{ub}
        FlushPalette(palette)
                     a0

        void FlushPalette(APTR)

@{b}   FUNCTION@{ub}
        This function flushes all buffers that might be
        associated with a palette.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette that was
                    created with @{"CreatePaletteA()" Link "CreatePaletteA()"}

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"DeletePalette()" Link "DeletePalette()"}


@EndNode

@Node "FreeRenderMem()" "render.library/FreeRenderMem"

@{b}   NAME@{ub}
        FreeRenderMem - return memory to a render-memhandler.

@{b}   SYNOPSIS@{ub}
        FreeRenderMem(rendermemhandler,mem,size)
                      a0               a1  d0

        void FreeRenderMem(APTR,APTR,ULONG)

@{b}   FUNCTION@{ub}
        Free a block of memory that was previously
        allocated with @{"AllocRenderMem()" Link "AllocRenderMem()"}.

@{b}   INPUTS@{ub}
        rendermemhandler - pointer to the render-memhandler you have
                           allocated the memory from
        mem              - pointer to the memory block to be returned
        size             - size of that memory block [bytes]

@{b}   RESULTS@{ub}
        NONE

@{b}   SEE ALSO@{ub}
        @{"AllocRenderMem()" Link "AllocRenderMem()"}, @{"DeleteRMHandler()" Link "DeleteRMHandler()"}


@EndNode

@Node "FreeRenderVec()" "render.library/FreeRenderVec"

@{b}   NAME@{ub}
        FreeRenderVec - return memory to a render-memhandler.

@{b}   SYNOPSIS@{ub}
        FreeRenderVec(mem)
                      a0

        void FreeRenderVec(APTR)

@{b}   FUNCTION@{ub}
        Free a block of memory that was previously
        allocated with @{"AllocRenderVec()" Link "AllocRenderVec()"}.

@{b}   INPUTS@{ub}
        mem - pointer to a memory block
              to be returned to its render-memhandler

@{b}   RESULTS@{ub}
        NONE

@{b}   SEE ALSO@{ub}
        @{"AllocRenderVec()" Link "AllocRenderVec()"}, @{"DeleteRMHandler()" Link "DeleteRMHandler()"}


@EndNode

@Node "ImportPaletteA()" "render.library/ImportPaletteA"

@{b}   NAME@{ub}
        ImportPaletteA - import a palette.
        ImportPalette  - varargs stub for ImportPaletteA.

@{b}   SYNOPSIS@{ub}
        ImportPaletteA(palette,table,entries,taglist)
                       a0      a1    d0      a2
        
        ImportPaletteA(APTR,APTR,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ImportPalette(APTR,APTR,UWORD,tag,...,TAG_DONE)
        
@{b}   FUNCTION@{ub}
        This function imports entries from a color table to
        a palette. You are allowed to import multiple times.
        When doing so, entries will be overwritten (not inserted).
        The palette automatically grows to the required number of
        entries. @{"Remember" Link "TEXT_INCLUDE:intuition/intuition.h/Main" 1430} to neither import more than 256 entries
        nor beyond the 256th entry.

@{b}   INPUTS@{ub}
        palette   - pointer to a palette created
                    with @{"CreatePaletteA()" Link "CreatePaletteA()"}
        table     - pointer to the source color table
        entries   - number of color entries to import
        taglist   - pointer to an array of tag items

@{b}   TAGS@{ub}
        RND_PaletteFormat (ULONG) - format of the color table
                to be import. Valid types:

                PALFMT_RGB32    - ULONG red,green,blue
                PALFMT_RGB8     - ULONG 0x00rrggbb
                PALFMT_RGB4     - UWORD 0xrgb

                Default - PALFMT_RGB8.

        RND_FirstColor (ULONG) - first destination color entry
                to import to. Default - 0.

        RND_EHBPalette (ULONG) - tag to indicate whether the
                palette should be interpreted as for an
                Extra-Halfbrite picture. Default - FALSE.

        RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
                that you want to dispose the current palette and
                import a new one. If set to FALSE, the palette is
                merged. Default - TRUE.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreatePaletteA()" Link "CreatePaletteA()"}, @{"ExportPaletteA()" Link "ExportPaletteA()"}, @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

@Node "Planar2ChunkyA()" "render.library/Planar2ChunkyA"

@{b}   NAME@{ub}
        Planar2ChunkyA - convert bitplane data to chunky bytes.
        Planar2Chunky  - varargs stub for Planar2ChunkyA.

@{b}   SYNOPSIS@{ub}
        Planar2ChunkyA(planetab,bytewidth,rows,depth,bytesperrow,
                       a0       d0        d1   d2    d3
                       chunkybuffer,taglist)
                       a1           a2

        void Planar2ChunkyA(PLANEPTR *,UWORD,UWORD,UWORD,UWORD,
                            UBYTE *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void Planar2Chunky(PLANEPTR *,UWORD,UWORD,UWORD,UWORD
                            UBYTE *,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Converts raw bitplane-oriented (planar) graphics to an array
        of chunky bytes.

@{b}   INPUTS@{ub}
        planetab    - pointer to a table of planepointers
        bytewidth   - width [bytes]. This must be an even number.
        rows        - height [rows]
        depth       - number of bitplanes
        bytesperrow - total bytes per row in the source bitplanes.
                      This must be an even number. If you convert
                      interleaved bitplanes, multiply by depth.
        chunky      - pointer to the destination chunky buffer
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_DestWidth (UWORD) - Total width of chunky array [pixels].
                Default - equals to bytewidth * 8.

                You are explicitely allowed to use a destwidth that is
                smaller than bytewidth * 8 pixels.
                
                Important note:
                If you specify this tag, you must _still_ supply a
                chunky buffer of at least bytewidth * 8 * rows bytes.

@{b}   NOTES@{ub}
        Starting with v39, you are not allowed to assume foreign @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}
        structures being of a planar type.  Before you grab a table of
        planepointers out of an unknown @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure and pass it to
        this function, you have to check for the presence of the
        BMF_STANDARD flag.

@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"Chunky2BitMapA()" Link "Chunky2BitMapA()"}, @{"graphics/gfx.h" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 0}


@EndNode

@Node "QueryHistogram()" "render.library/QueryHistogram"

@{b}   NAME@{ub}
        QueryHistogram - query a histogram parameter.

@{b}   SYNOPSIS@{ub}
        value = QueryHistogram(histogram,tag)
        d0                     a0        d0
        
        ULONG QueryHistogram(APTR,Tag)

@{b}   FUNCTION@{ub}
        Query one of a histogram's specifications
        via @{"Tag" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 29} parameter.

@{b}   INPUTS@{ub}
        histogram - pointer to a histogram
        tag       - @{"Tag" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 29} to be queried

@{b}   TAGS@{ub}
        RND_NumColors (ULONG) -
                the number of different colors inside the histogram.

        RND_NumPixels (ULONG) -
                the number of pixels that have been added to the
                histogram.

        RND_RMHandler (ULONG) -
                the histogram's render-memhandler.

        RND_HSType (UWORD) -
                the histogram's type.

@{b}   RESULTS@{ub}
        value    - the queried parameter.

@{b}   SEE ALSO@{ub}
        @{"CreateHistogramA()" Link "CreateHistogramA()"}


@EndNode

@Node "RenderA()" "render.library/RenderA"

@{b}   NAME@{ub}
        RenderA - render an array of RGB data to chunky bytes.
        Render  - varargs stub for RenderA.

@{b}   SYNOPSIS@{ub}
        success = RenderA(rgb,width,height,chunky,palette,taglist)
        d0                a0  d0    d1     a1     a2      a3
        
        ULONG RenderA(ULONG *,UWORD,UWORD,UBYTE *,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG Render(ULONG *,UWORD,UWORD,UBYTE *,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Render an array of RGB data to an array of chunky bytes.

@{b}   INPUTS@{ub}
        rgb         - pointer to an array of RGB pixels
        width       - width to be converted [pixels]
        height      - height to be converted [rows]
        chunky      - pointer to the destination array
        palette     - pointer to a palette to be rendered to
        taglist     - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
                Default - equals to the specified width.

        RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
                Default - equals to the specified width.

        RND_ColorMode (ULONG) - Color mode that defines how to determine
                a pixel's actual color. Valid types:

                COLORMODE_CLUT          - normal palette lookup
                COLORMODE_HAM8          - HAM8 mode palette lookup
                COLORMODE_HAM6          - HAM6 mode palette lookup
                
                Default - COLORMODE_CLUT.

        RND_DitherMode (UWORD) - Error diffusion mode. Valid types:

                DITHERMODE_NONE   - no error diffusion

                DITHERMODE_FS     - Floyd-Steinberg
                                    Does not handle a dither amount.

                DITHERMODE_RANDOM - Random dithering
                                    Handles RND_DitherAmount.

                Default - DITHERMODE_NONE.

        RND_ProgressHook (ULONG) - Pointer to a callback hook
                structure for progress display operations. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_OffsetColorZero (UWORD) - First color index to appear
                in the rendered chunky image. This offset will be
                added to the palette's indices. Default - 0.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
                for a secondary conversion of the pen numbers.
                Default - NULL.
                Note: RND_PenTable overrides RND_OffsetColorZero.

        RND_LineHook (ULONG) - Pointer to a callback hook structure
                for line-related operations during render. This hook
                is executed once before a line is rendered and once
                after a line has been completed. Refer to
                @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0} for further information.
                Default - NULL.

        RND_DitherAmount (UWORD) - Dither intensity (0-255).
                Only valid with certain dither modes (see above).
                Default - 128.

@{b}   RESULTS@{ub}
        result  - returncode to indicate whether the operation
                  succeeded. You must at least check for
                  REND_SUCCESS.

@{b}   NOTES@{ub}
        - This function may call the progress callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} with
          the PMSGTYPE_LINES_RENDERED message type.

@{b}   SEE ALSO@{ub}
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}, @{"render/renderhooks.h" Link "TEXT_INCLUDE:render/renderhooks.h/Main" 0}


@EndNode

@Node "ScaleA()" "render.library/ScaleA"

@{b}   NAME@{ub}
        ScaleA - scale an image.
        Scale  - varargs stub for ScaleA.

@{b}   SYNOPSIS@{ub}
        ScaleA(engine,source,dest,taglist)
               a0     a1     a2   a3
        
        void ScaleA(APTR,APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        void Scale(APTR,APTR,APTR,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Scales a source array of pixels to another array.

@{b}   INPUTS@{ub}
        engine  - pointer to a scaling-engine created
                  with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}
        source  - pointer to source array of pixels
        dest    - pointer to destination array
        taglist - pointer to an array of TagItems

@{b}   TAGS@{ub}
        RND_SourceWidth (UWORD) - Total width of the source array [pixels].
                Default - equals to the source width the scaling-engine
                          was created with.

        RND_DestWidth (UWORD) - Total width of the dest array [pixels].
                Default - equals to the destination width the
                          scaling-engine was created with.
@{b}   RESULTS@{ub}
        none

@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}


@EndNode

@Node "ScaleOrdinate()" "render.library/ScaleOrdinate"

@{b}   NAME@{ub}
        ScaleOrdinate - scale a single ordinate.

@{b}   SYNOPSIS@{ub}
        scaled_ordinate = ScaleOrdinate(start,dest,ordinate)
        d0                              d0    d1   d2

        UWORD ScaleOrdinate(UWORD,UWORD,UWORD)

@{b}   FUNCTION@{ub}
        This function scales a single ordinate. The algorythm
        used here is identical to what scaling-engines are
        created with.
        
@{b}   EXAMPLE        @{ub}
        Assume you have a specific pair of coordinates
        that represent a particular pixel inside an image.
        You can use this function to determine the pixel's
        new coordinates after the image has been scaled:

        new_pixel_x = ScaleOrdinate(picwidth,newwidth,pixel_x);
        new_pixel_y = ScaleOrdinate(picheight,newheight,pixel_y);

@{b}   INPUTS@{ub}
        start    - original value (e.g. width or height)
                   e.g. the original width of an image.
                   This value usually corresponds to a
                   start value with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}.
                   Must not be 0.
        dest     - destination value (e.g. width or height)
                   e.g. the scaled width of an image.
                   This value usually corresponds to a
                   dest value with @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}.
                   Must not be 0.
        ordinate - a single ordinate (e.g. of a pixel).
                   Must be less than <start>.

@{b}   RESULTS@{ub}
        scaled_ordinate - the new ordinate (after scaling)
        
@{b}   SEE ALSO@{ub}
        @{"CreateScaleEngineA()" Link "CreateScaleEngineA()"}


@EndNode

@Node "SortPaletteA()" "render.library/SortPaletteA"

@{b}   NAME@{ub}
        SortPaletteA - sort a palette.
        SortPalette  - varargs stub for SortPaletteA.

@{b}   SYNOPSIS@{ub}
        success = SortPaletteA(palette,mode,taglist)
        d0                     a0      d0   a1
        
        ULONG SortPaletteA(APTR,ULONG,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        ULONG SortPalette(APTR,ULONG,tag,...,TAG_DONE)

@{b}   FUNCTION@{ub}
        Sorts a palette according to a sort mode.
        Some sort modes apply to palettes solely, some
        others additionally require a histogram.

@{b}   INPUTS@{ub}
        palette - pointer to a palette created
                  with @{"CreatePaletteA()" Link "CreatePaletteA()"}.

        mode    - sort mode. Currently defined are:

                  PALMODE_BRIGHTNESS      - sort the palette entries
                                by brightness.

                  PALMODE_SATURATION      - sort the palette entries
                                by their color intensity.

                  PALMODE_POPULARITY      - sort the palette entries
                                by the number of pixels that they
                                represent. You must specify the
                                RND_Histogram taglist argument.

                  PALMODE_REPRESENTATION  - sort the palette entries
                                by the number of histogram entries
                                that they represent. You must specify
                                the RND_Histogram taglist argument.
                  
                  PALMODE_SIGNIFICANCE    - sort the palette entries
                                by their optical significance for the
                                human eye. Implementation is unknown
                                to you and may change. You must supply
                                the RND_Histogram taglist argument.

                  PALMODE_ASCENDING       - by default, sort direction
                                is descending, i.e. precedence is
                                `more-to-less' of the given effect.
                                Combine with this flag to invert the
                                sort direction.

        taglist - pointer to an array of tagitems.

@{b}   TAGS@{ub}
        RND_Histogram (ULONG) - pointer to a histogram. This taglist
                argument is obligatory for some sort modes. (See above)

@{b}   RESULTS@{ub}
        success - return value to indicate whether the operation succeeded.
                  You must at least check for SORTP_SUCCESS.

@{b}   SEE ALSO@{ub}
        @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}


@EndNode

