@database "guigfx"
@master "Data:Temporary/GuiGFXLib/doc/autodoc/guigfx.doc"

@Node Main "guigfx.doc"
    @{" AddPaletteA() " Link "AddPaletteA()"}
    @{" AddPictureA() " Link "AddPictureA()"}
    @{" AddPixelArrayA() " Link "AddPixelArrayA()"}
    @{" ClonePictureA() " Link "ClonePictureA()"}
    @{" CreatePenShareMapA() " Link "CreatePenShareMapA()"}
    @{" CreatePictureBitMapA() " Link "CreatePictureBitMapA()"}
    @{" DeletePenShareMap() " Link "DeletePenShareMap()"}
    @{" DeletePicture() " Link "DeletePicture()"}
    @{" DoPictureMethodA() " Link "DoPictureMethodA()"}
    @{" DrawPictureA() " Link "DrawPictureA()"}
    @{" GetPictureAttrsA() " Link "GetPictureAttrsA()"}
    @{" IsPictureA() " Link "IsPictureA()"}
    @{" LoadPictureA() " Link "LoadPictureA()"}
    @{" LockPictureA() " Link "LockPictureA()"}
    @{" MakePictureA() " Link "MakePictureA()"}
    @{" ObtainDrawHandleA() " Link "ObtainDrawHandleA()"}
    @{" ReadPictureA() " Link "ReadPictureA()"}
    @{" ReleaseDrawHandle() " Link "ReleaseDrawHandle()"}
    @{" RemColorHandle() " Link "RemColorHandle()"}
    @{" UnLockPicture() " Link "UnLockPicture()"}
@EndNode

@Node "AddPaletteA()" "guigfx.library/AddPaletteA"

@{b}    NAME@{ub}
        AddPaletteA - add a palette's colors to a pen-sharemap.
        AddPalette  - varargs stub for AddPaletteA.

@{b}    SYNOPSIS@{ub}
        colorhandle = AddPaletteA(psm,palette,taglist)
        d0                        a0  a1      a2

        APTR AddPaletteA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR AddPalette(APTR,APTR,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function adds a palette's colors to a pen-sharemap.

@{b}    INPUTS@{ub}
        psm         - pointer to a pen-sharemap
        palette     - pointer to a color table
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_PaletteFormat (ULONG) - format of the palette. Currently
                defined are:
                      
                PALFMT_RGB8
                        ULONG 0x00rrggbb

                PALFMT_RGB32
                        ULONG red,green,blue. This is the @{"LoadRGB32()" Link "graphics/LoadRGB32()"}
                        format without trailing longword.

                Default: PALFMT_RGB8
                
        GGFX_NumColors (ULONG) - number of colors in the color table.
                Currently, this argument is mandatory. Default: 0
        
        GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
                With this factor, you can specify a 'significance'
                for the palette being added. The higher this value, the
                more important becomes the palette's color information.
                Default: 1

@{b}    RESULTS@{ub}
        colorhandle - identifier for a particular dependency between
                      color information and a pen-sharemap. Under normal
                      circumstances, there is no need to store a
                      colorhandle, unless you wish to manually remove 
                      it via @{"RemColorHandle()" Link "RemColorHandle()"}. NULL if something went wrong.

@{b}    NOTES@{ub}
        An example is provided with the documentation for @{"AddPictureA()" Link "AddPictureA()"}.

@{b}    SEE ALSO@{ub}
        @{"RemColorHandle()" Link "RemColorHandle()"}, @{"AddPictureA()" Link "AddPictureA()"}, @{"AddPixelArrayA()" Link "AddPixelArrayA()"},
        @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, @{"DeletePenShareMap()" Link "DeletePenShareMap()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}


@EndNode

@Node "AddPictureA()" "guigfx.library/AddPictureA"

@{b}    NAME@{ub}
        AddPictureA - add a picture's color information to a pen-sharemap.
        AddPicture  - varargs stub for AddPictureA.

@{b}    SYNOPSIS@{ub}
        colorhandle = AddPictureA(psm,picture,taglist)
        d0                        a0  a1      a2

        APTR AddPictureA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR AddPicture(APTR,APTR,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function adds a picture's color information to
        a pen-sharemap.

@{b}    INPUTS@{ub}
        psm         - pointer to a pen-sharemap
        picture     - pointer to a picture
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
                With this factor, you can specify a 'significance'
                for this particular color instance. The higher this
                value, the more important becomes the color information
                related to it. Default: 1
        
@{b}    RESULTS@{ub}
        colorhandle - identifier for a particular dependency between
                      color information and a pen-sharemap. Under normal
                      circumstances, there is no need to store a
                      colorhandle, unless you wish to manually remove 
                      it via @{"RemColorHandle()" Link "RemColorHandle()"}. NULL if something went wrong.

@{b}    EXAMPLE@{ub}
        Assume there were three different pictures to be drawn.

        a) a noisy background
        b) a logo of your company
        c) navigation icons

        you might want to differenciate the significances for these 
        pictures as follows:

        AddPicture(psm, backpic, GGFX_Weight, 2, TAG_DONE);
        AddPicture(psm, logopic, GGFX_Weight, 3, TAG_DONE);
        AddPicture(psm, navpic, GGFX_Weight, 5, TAG_DONE);

        the backpic's influence on the allocated pens would be 20%, the logo
        contributed with 30%, and the navigation buttons would be taken into
        account with 50% then.

@{b}    NOTES@{ub}
        
@{b}    SEE ALSO@{ub}
        @{"RemColorHandle()" Link "RemColorHandle()"}, @{"AddPaletteA()" Link "AddPaletteA()"}, @{"AddPixelArrayA()" Link "AddPixelArrayA()"},
        @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, @{"DeletePenShareMap()" Link "DeletePenShareMap()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}


@EndNode

@Node "AddPixelArrayA()" "guigfx.library/AddPixelArrayA"

@{b}    NAME@{ub}
        AddPixelArrayA - add a pixel array's color information to a
                         pen-sharemap.
        AddPixelArray  - varargs stub for AddPixelArrayA.

@{b}    SYNOPSIS@{ub}
        colorhandle = AddPixelArrayA(psm,array,width,height,taglist)
        d0                           a0  a1    d0    d1     a2

        APTR AddPixelArrayA(APTR,APTR,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR AddPixelArray(APTR,APTR,UWORD,UWORD,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function adds a pixel array's color information to a
        pen-sharemap.

@{b}    INPUTS@{ub}
        psm         - pointer to a pen-sharemap
        pixelarray  - pointer to a pixel array
        width       - pixel array's width [pixels]
        height      - pixel array's height [rows]
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_PixelFormat (ULONG) - pixel format. Currently defined are

                PIXFMT_CHUNKY_CLUT
                        chunky bytes, directly acting as indices
                        to a color-lookup-table. You must specify the
                        GGFX_Palette and GGFX_NumColors tags as well.
                
                PIXFMT_0RGB_32
                        truecolor pixels (ULONG 0x00rrggbb).

                Default: PIXFMT_CHUNKY_CLUT               

        GGFX_Palette (APTR) - pointer to a color table. Mandatory for
                PIXFMT_CHUNKY_CLUT (see above).
                Default: none

        GGFX_NumColors (ULONG) - number of colors in the color table.
                Mandatory for PIXFMT_CHUNKY_CLUT (see above).
                Default: none

        GGFX_PaletteFormat (ULONG) - format of the palette. Currently
                defined are:
                      
                PALFMT_RGB8
                        ULONG 0x00rrggbb

                PALFMT_RGB32
                        ULONG red,green,blue. This is the @{"LoadRGB32()" Link "graphics/LoadRGB32()"}
                        format without trailing longword.

                Default: PALFMT_RGB8

        GGFX_Weight (ULONG) - weight factor. Valid range: 1...255.
                With this factor, you can specify a 'significance'
                for this particular color instance. The higher this
                value, the more important becomes the color information
                related to it. Default: 1
        
@{b}    RESULTS@{ub}
        colorhandle - identifier for a particular dependency between
                      color information and a pen-sharemap. Under normal
                      circumstances, there is no need to store a
                      colorhandle, unless you wish to manually remove 
                      it via @{"RemColorHandle()" Link "RemColorHandle()"}. NULL if something went wrong.

@{b}    NOTES@{ub}
        An example is provided with the documentation for @{"AddPictureA()" Link "AddPictureA()"}.

@{b}    SEE ALSO@{ub}
        @{"RemColorHandle()" Link "RemColorHandle()"}, @{"AddPaletteA()" Link "AddPaletteA()"}, @{"AddPictureA()" Link "AddPictureA()"},
        @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, @{"DeletePenShareMap()" Link "DeletePenShareMap()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}


@EndNode

@Node "ClonePictureA()" "guigfx.library/ClonePictureA"

@{b}    NAME@{ub}
        ClonePictureA - create a duplicate from a picture.
        ClonePicture  - varargs stub for ClonePictureA.

@{b}    SYNOPSIS@{ub}
        newpicture = ClonePictureA(picture,taglist)
        d0                         a0      a1

        APTR ClonePictureA(APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR ClonePicture(APTR,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function creates a duplicate from a picture. Memory will
        be allocated, and the picture will be copied including all its
        attributes. Optionally, the picture is cloned only in part.

@{b}    INPUTS@{ub}
        picture     - pointer to a picture
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_SourceX (ULONG)
                left edge inside the picture where to fetch the pixels
                from [pixels]. Default: 0.

        GGFX_SourceY (ULONG)
                top edge inside the picture where to fetch the pixels
                from [rows]. Default: 0.

        GGFX_SourceWidth (ULONG)
                width of an area inside the picture [pixels].
                Default: The picture's width.

        GGFX_SourceHeight (ULONG)
                height of an area inside the picture [rows].
                Default: The picture's height.

        GGFX_DestWidth (ULONG)
                width of the new picture [pixels].
                Default: The picture's width.

        GGFX_DestHeight (ULONG)
                height of the new picture [rows].
                Default: The picture's height.

@{b}    RESULTS@{ub}
        newpicture  - a vanilla copy of the specified picture (or a
                      part of it), or NULL if there was not enough memory
                      available.

@{b}    SEE ALSO@{ub}
        @{"MakePictureA()" Link "MakePictureA()"}, @{"DeletePicture()" Link "DeletePicture()"}


@EndNode

@Node "CreatePenShareMapA()" "guigfx.library/CreatePenShareMapA"

@{b}    NAME@{ub}
        CreatePenShareMapA - create a screen-pen manager.
        CreatePenShareMap  - varargs stub for CreatePenShareMapA.

@{b}    SYNOPSIS@{ub}
        psm = CreatePenShareMap(taglist)
        d0                      a0

        APTR CreatePenShareMapA(struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)
        
        APTR CreatePenShareMap(tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function creates a screen-pen manager.

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

@{b}    TAGS@{ub}
        GGFX_HSType (ULONG) - internal histogram type, according to
                the histogram types defined in @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}.
                Better you never touch this tag, unless you know exactly
                what you are doing. Also consider reading the 'memory' text
                file supplied with the render.library distribution.
                Default: HSTYPE_12BIT_TURBO
        
@{b}    RESULTS@{ub}
        psm   - a pen-sharemap ready for usage or NULL if there was not
                enough memory available.

@{b}    NOTES@{ub}
        A pen-sharemap does not necessarily lead to pen allocation when
        passed to @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}. This depends on the RastPort's
        environment. A pen-sharemap is actually not more than a mere
        histogram that collects color information.
        
@{b}    SEE ALSO@{ub}
        @{"DeletePenShareMap()" Link "DeletePenShareMap()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}, @{"AddPictureA()" Link "AddPictureA()"},
        @{"AddPaletteA()" Link "AddPaletteA()"}, @{"AddPixelArrayA()" Link "AddPixelArrayA()"}


@EndNode

@Node "CreatePictureBitMapA()" "guigfx.library/CreatePictureBitMapA"

@{b}    NAME@{ub}
        CreatePictureBitMapA - create a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} from a picture.
        CreatePictureBitMap  - varargs stub for CreatePictureBitMapA.

@{b}    SYNOPSIS@{ub}
        bitmap = CreatePictureBitMapA(drawhandle,picture,tags)
        d0                            a0         a1      a2

        struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *CreatePictureBitMapA(APTR,APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        struct @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} *CreatePictureBitMap(APTR,APTR,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function creates a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} from a picture. This @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} will
        be applicable for the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} and @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} associated with
        the specified drawhandle. Optionally, the @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} will be scaled
        to the specified dimensions. A clip area inside the picture may
        be specified as well.

@{b}    INPUTS@{ub}
        drawhandle  - pointer to a drawhandle from @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}
        picture     - pointer to a picture
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_DestWidth (ULONG)
                destination width for the @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [pixels].
                Default: the picture's width.

        GGFX_DestHeight (ULONG)
                destination height for the @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} [rows].
                Default: the picture's height.

        GGFX_SourceX (ULONG)
                left edge inside the picture where to fetch the pixels
                from [pixels]. Default: 0.

        GGFX_SourceY (ULONG)
                top edge inside the picture where to fetch the pixels
                from [rows]. Default: 0.

        GGFX_SourceWidth (ULONG)
                width of an area inside the picture [pixels].
                Default: The picture's width.

        GGFX_SourceHeight (ULONG)
                height of an area inside the picture [rows].
                Default: The picture's height.

        GGFX_CallBackHook (struct @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} *)
                pointer to a callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} structure. The associated
                callback function will be called from time to time
                while the picture is being rendered to the @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}.
                The callback has to return TRUE for continuation or FALSE
                for abortion. It will be submitted a pointer to the
                picture for the object, and a message of the following
                type:

                        ULONG GGFX_MSGTYPE_LINEDRAWN
                        ULONG line_number
                
                Also refer to the example provided with @{"DrawPictureA()" Link "DrawPictureA()"}.
                Default: NULL.

        GGFX_DitherMode (ULONG) - dither mode. Currently available are:

                DITHERMODE_NONE
                        no dithering at all
                
                DITHERMODE_FS
                        Floyd-Steinberg dithering
                        
                DITHERMODE_RANDOM
                        Random dithering. This mode is significantly
                        slower than Floyd-Steinberg dithering.

                DITHERMODE_EDD
                        EDD dithering. This mode is faster than
                        Floyd-Steinberg dithering.
 
                Default: The drawhandle's dithermode.

        GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
                Currently, this value is of any use only for
                DITHERMODE_RANDOM. Default: The drawhandle's dither amount.

@{b}    RESULTS@{ub}
        bitmap     - a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure ready for being blitted to
                     the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} via @{"graphics.library/BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"},
                     or NULL if there was not enough memory available.

@{b}    SEE ALSO@{ub}
        @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}, @{"DrawPictureA()" Link "DrawPictureA()"}, @{"graphics.library/FreeBitMap()" Link "graphics/FreeBitMap()"}
        @{"graphics.library/BltBitMapRastPort()" Link "graphics/BltBitMapRastPort()"}


@EndNode

@Node "DeletePenShareMap()" "guigfx.library/DeletePenShareMap"

@{b}    NAME@{ub}
        DeletePenShareMap - dispose a pen-sharemap.

@{b}    SYNOPSIS@{ub}
        DeletePenShareMap(psm)
                          a0

        void DeletePenShareMap(APTR)

@{b}    FUNCTION@{ub}
        This function discards a pen-sharemap and frees all associated
        memory and colorhandles.

@{b}    INPUTS@{ub}
        psm      - pointer to a pen-sharemap to be deleted.
        
@{b}    SEE ALSO@{ub}
        @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, @{"RemColorHandle()" Link "RemColorHandle()"}


@EndNode

@Node "DeletePicture()" "guigfx.library/DeletePicture"

@{b}    NAME@{ub}
        DeletePicture - dispose a picture.

@{b}    SYNOPSIS@{ub}
        DeletePicture(picture)
                      a0

        void DeletePicture(APTR)

@{b}    FUNCTION@{ub}
        This function discards a picture and frees all associated
        memory.

@{b}    INPUTS@{ub}
        picture    - pointer to a picture to be deleted.
        
@{b}    SEE ALSO@{ub}
        @{"MakePictureA()" Link "MakePictureA()"}


@EndNode

@Node "DoPictureMethodA()" "guigfx.library/DoPictureMethodA"

@{b}    NAME@{ub}
        DoPictureMethodA - apply a method to a picture.
        DoPictureMethod  - varargs stub for DoPictureMethodA.

@{b}    SYNOPSIS@{ub}
        result = DoPictureMethodA(picture,method,arguments)
                                  a0      d0     a1

        ULONG DoPictureMethodA(APTR,ULONG,ULONG *)
        
        ULONG DoPictureMethod(APTR,ULONG,argument,...)

@{b}    FUNCTION@{ub}
        This function applies a method to a picture. Arguments and
        results depend on the specified method.

@{b}    INPUTS@{ub}
        picture    - pointer to a picture
        method     - method identifier (see below)
        arguments  - pointer to a list of arguments (see below)

@{b}    METHODS@{ub}

        PICMTHD_CREATEALPHAMASK        rgb, tags

                this method creates an alpha-channel for the given picture.
                The alpha-channel will be the difference for each pixel in
                the picture against the specified 0x00rrggbb value.
                Optionally, a clip area inside the source picture may be
                specified.
                
                TAGS
                        GGFX_SourceX (ULONG)
                                source left edge in the second picture
                                [pixels]. Default: 0

                        GGFX_SourceY (ULONG)
                                source top edge in the picture [rows].
                                Default: 0

                        GGFX_SourceWidth (ULONG)
                                width of an area in the picture [pixels].
                                Default: the picture's width.

                        GGFX_SourceHeight (ULONG)
                                height of an area in the picture [rows].
                                Default: the picture's height.

                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_SETALPHA


        PICMTHD_CROP    x, y, width, height, tags
        
                crop a picture to a rectangle defined throughout
                position (x|y) and dimensions (width|height)

                TAGS
                        none defined

                RESULTS
                        success (boolean)


        PICMTHD_FLIPX    tags

                flip image (or a part of it) horizontally.

                TAGS
                        GGFX_DestX (ULONG)
                                left edge of the area to flip [pixels]
                                Default: 0

                        GGFX_DestY (ULONG)
                                top edge of the area to flip [rows]
                                Default: 0

                        GGFX_DestWidth (ULONG)
                                width of the area to be flipped [pixels]
                                Default: the picture's width.

                        GGFX_DestHeight (ULONG)
                                height of the area to be flipped [rows]
                                Default: the picture's height.

                RESULTS
                        success (boolean)


        PICMTHD_FLIPY    tags

                flip image (or a part of it) vertically.

                TAGS
                        GGFX_DestX (ULONG)
                                left edge of the area to flip [pixels]
                                Default: 0

                        GGFX_DestY (ULONG)
                                top edge of the area to flip [rows]
                                Default: 0

                        GGFX_DestWidth (ULONG)
                                width of the area to be flipped [pixels]
                                Default: the picture's width.

                        GGFX_DestHeight (ULONG)
                                height of the area to be flipped [rows]
                                Default: the picture's height.

                RESULTS
                        success (boolean)


        PICMTHD_INSERT  second_picture, tags
        
                insert a second picture (or a part of it) to the current
                picture. Clip areas may be specified both inside the current
                and the second picture. The processed pixels will be scaled
                to the specified dimensions, if necessary.
                
                TAGS
                        GGFX_SourceX (ULONG)
                                source left edge where to fetch the pixels
                                from in the second picture [pixels].
                                Default: 0

                        GGFX_SourceY (ULONG)
                                source top edge where to fetch the pixels
                                from in the second picture [rows].
                                Default: 0

                        GGFX_SourceWidth (ULONG)
                                width of an area in the second picture
                                [pixels]. Default: the second picture's
                                width.

                        GGFX_SourceHeight (ULONG)
                                height of an area in the second picture
                                [rows]. Default: the second picture's
                                height.

                        GGFX_DestX (ULONG)
                                destination left edge where to insert
                                the pixels into the current picture
                                [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination top edge where to insert
                                the pixels into the current picture
                                [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width to be inserted in the current picture.
                                [pixels]. Default: the current picture's width.

                        GGFX_DestHeight (ULONG)
                                height to be inserted in the current picture.
                                [rows]. Default: the current picture's height.
                                
                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)


        PICMTHD_MAPDRAWHANDLE   drawhandle, tags

                map a picture for optimized drawing to a drawhandle's
                @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}. Drawing a picture via @{"DrawPictureA()" Link "DrawPictureA()"} is much
                faster thereafter.

                TAGS
                        none defined

                RESULTS
                        success (boolean)

                NOTES
                        - The internal representation of a picture may
                          change at any time. The specified pixel format
                          is only valid until the next call to
                          DoPictureMethodA(). Use @{"GetPictureAttrsA()" Link "GetPictureAttrsA()"} to
                          find out about the current format.

                        - You risk to lose color information, i.e. when
                          a truecolor picture has to be rendered to a
                          8bit @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}, for instance.

        PICMTHD_MIX     second_picture, tags
        
                mix a second picture to the current picture. Clip areas
                may be specified both inside the current and the second
                picture. The processed pixels will be scaled to the
                specified dimensions, if necessary.
                
                TAGS
                        GGFX_Ratio (ULONG)
                                mix ratio (0...255). Default: 128

                        GGFX_SourceX (ULONG)
                                source left edge where to fetch pixels
                                from in the second picture [pixels].
                                Default: 0

                        GGFX_SourceY (ULONG)
                                source top edge where to fetch pixels
                                from in the second picture [rows].
                                Default: 0

                        GGFX_SourceWidth (ULONG)
                                width of an area in the second picture
                                [pixels]. Default: the second picture's
                                width.

                        GGFX_SourceHeight (ULONG)
                                height of an area in the second picture
                                [rows]. Default: the second picture's
                                height.

                        GGFX_DestX (ULONG)
                                destination left edge where to apply
                                the operation to in the current picture
                                [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination top edge where to apply
                                the operation to in the current picture
                                [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width of an area for the operation to be
                                applied to in the current picture [pixels].
                                Default: the current picture's width.

                        GGFX_DestHeight (ULONG)
                                height of an area for the operation to be
                                applied to in the current picture [rows].
                                Default: the current picture's height.
                                
                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_MIXALPHA


        PICMTHD_MIXALPHA        secondpicture, tags
        
                mix a second picture to the current picture via
                alpha-channel. Clip areas may be specified both inside
                the current and the second picture. The processed pixels
                will be scaled to the specified dimensions, if necessary.
                
                TAGS
                        GGFX_DestX (ULONG)
                                destination left edge where to apply
                                the operation to in the current picture
                                [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination left edge where to apply
                                the operation to in the current picture
                                [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width of an area for the operation to be
                                applied to in the current picture [pixels].
                                Default: the current picture's width.

                        GGFX_DestHeight (ULONG)
                                height of an area for the operation to be
                                applied to in the current picture [rows].
                                Default: the current picture's height.
                                
                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_SETALPHA, PICMTHD_MIX


        PICMTHD_RENDER  pixelformat, tags

                render a picture to a specified pixel format. Valid pixel
                formats are as follows:

                        PIXFMT_CHUNKY_CLUT
                                chunky bytes
                        
                        PIXFMT_0RGB_32
                                ULONG 0x00rrggbb truecolor data

                        PIXFMT_RGB_24
                                UBYTE 0xrr,0xgg,0xbb truecolor data
                
                TAGS
                        none defined
                        
                RESULTS
                        success (boolean)

                NOTES
                        - The internal representation of a picture may
                          change at any time. The specified pixel format
                          is only valid until the next call to
                          DoPictureMethodA(). Use @{"GetPictureAttrsA()" Link "GetPictureAttrsA()"} to
                          find out about the current format.

                        - You risk to lose color information, i.e. when
                          a truecolor picture has to be rendered to a
                          8bit @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}, for instance.


        PICMTHD_SCALE   width, height, tags
        
                scale a picture to the specified dimensions.
                
                TAGS
                        none defined

                RESULTS
                        success (boolean)
                        
                NOTE
                        This function fails if applied to a static
                        buffer, and when the image needs to grow. In this
                        case, specify GGFX_Independent or set a larger
                        buffer with GGFX_BufferSize when creating the
                        picture with @{"MakePictureA()" Link "MakePictureA()"}.


        PICMTHD_SETALPHA        alpha-array, width, height, tags

                set an alpha-channel array for the current picture.
                The alpha-channel is a plain array of chunky-bytes,
                defining a mixing ratio for each pixel. The
                alpha-channel array will be scaled to fit exactly to
                the current picture, unless you specify other
                dimensions. Passing a NULL pointer for alpha-array
                will discard an existing alpha-channel.

                TAGS
                        GGFX_DestX (ULONG)
                                destination left edge where to insert
                                the alpha-channel into the current
                                picture [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination top edge where to insert
                                the alpha-channel into the current
                                picture [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width to be inserted to the current
                                picture [pixels]. Default: the current
                                picture's width.

                        GGFX_DestHeight (ULONG)
                                height to be inserted to the current
                                picture [rows]. Default: the current
                                picture's height.

                RESULTS
                        success (boolean)
                
                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_CREATEALPHAMASK


        PICMTHD_TEXTURE  texturepic, coordinates, tags
        
                draw a texture to the current picture, texture-mapped
                via an array of coordinates. texturepic is a pointer to
                a picture that contains the texture, coordinates is a
                pointer to an array of 4 WORD pairs of x/y coordinates
                each. They form a trapezoid inside the current picture
                for the texture picture to be mapped to. border clipping
                is fully implemented.

                TAGS
                        GGFX_SourceX (ULONG)
                                source left edge inside the texture
                                [pixels]. Default: 0

                        GGFX_SourceY (ULONG)
                                source top edge inside the texture
                                [rows]. Default: 0

                        GGFX_SourceWidth (ULONG)
                                texture width [pixels]. Default:
                                the texturepic's width.

                        GGFX_SourceHeight (ULONG)
                                texture height [rows]. Default:
                                the texturepic's height.

                        GGFX_DestX (ULONG)
                                destination left edge where to apply
                                the trapezoid to the current picture
                                [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination top edge where to apply
                                the trapezoid to the current picture
                                [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                maximum width to be inserted to the
                                current picture [pixels]. Default: the
                                current picture's width.

                        GGFX_DestHeight (ULONG)
                                maximum height to be inserted to the
                                current picture [rows]. Default: the
                                current picture's height.
                        
                RESULTS
                        success (boolean)

                NOTES
                        this method depends on both pictures to be in
                        the same format. DoPictureMethodA() tries to
                        convert either of the involved pictures to the
                        other's format. (see annotations below)

                SEE ALSO
                        render.library texture-mapping documentation


        PICMTHD_TINTALPHA       rgb, tags
        
                tint the picture with the given 0x00rrggbb. the mixing
                ratio is defined throughout the picture's alpha-channel.
                
                TAGS
                        GGFX_DestX (ULONG)
                                destination left edge where to apply
                                the operation [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination left edge where to apply
                                the operation [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width of an area for the operation to be
                                applied to [pixels].
                                Default: the picture's width.

                        GGFX_DestHeight (ULONG)
                                height of an area for the operation to be
                                applied to [rows].
                                Default: the picture's height.

                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_TINT, PICMTHD_MIXALPHA


        PICMTHD_TINT     rgb, tags
        
                tint the picture with the given 0x00rrggbb value, and
                optionally with a specific ratio.
                
                TAGS
                        GGFX_Ratio (ULONG)
                                mix ratio (0...255). Default: 128

                        GGFX_DestX (ULONG)
                                destination left edge where to apply
                                the operation [pixels]. Default: 0

                        GGFX_DestY (ULONG)
                                destination left edge where to apply
                                the operation [rows]. Default: 0

                        GGFX_DestWidth (ULONG)
                                width of an area for the operation to be
                                applied to [pixels].
                                Default: the picture's width.

                        GGFX_DestHeight (ULONG)
                                height of an area for the operation to be
                                applied to [rows].
                                Default: the picture's height.

                RESULTS
                        success (boolean)

                NOTES
                        this method requires conversion to PIXFMT_0RGB_32
                        (see annotations below)

                SEE ALSO
                        PICMTHD_TINTALPHA, PICMTHD_MIXALPHA


@{b}    RESULTS@{ub}
        result     - return value (specific for the applied method)

@{b}    NOTES@{ub}
        Methods that require conversion to PIXFMT_0RGB_32 will fail in
        a static buffer, i.e. when the picture was created with
        @{"MakePictureA()" Link "MakePictureA()"} in the format PIXFMT_CHUNKY_CLUT, and without
        a buffer overhang or GGFX_Independent. See @{"MakePictureA()" Link "MakePictureA()"} for
        further details.
        
@{b}    SEE ALSO@{ub}
        @{"MakePictureA()" Link "MakePictureA()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}, @{"DrawPictureA()" Link "DrawPictureA()"}


@EndNode

@Node "DrawPictureA()" "guigfx.library/DrawPictureA"

@{b}    NAME@{ub}
        DrawPictureA - draw a picture to a drawhandle.
        DrawPicture  - varargs stub for DrawPictureA.

@{b}    SYNOPSIS@{ub}
        success = DrawPictureA(drawhandle,picture,x, y, tags)
        d0                     a0         a1      d0 d1 a2

        BOOL DrawPictureA(APTR,APTR,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        BOOL DrawPicture(APTR,APTR,UWORD,UWORD,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function draws a picture to the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} associated with
        a drawhandle. Optionally, the picture will be scaled to the
        specified dimensions. A clip area inside the picture may be
        specified as well.

@{b}    INPUTS@{ub}
        drawhandle  - pointer to a drawhandle from @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}
        picture     - pointer to a picture
        x           - left edge inside the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} [pixels]
        y           - top edge inside the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} [rows]
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_SourceX (ULONG)
                left edge inside the picture where to fetch the pixels
                from [pixels]. Default: 0.

        GGFX_SourceY (ULONG)
                top edge inside the picture where to fetch the pixels
                from [rows]. Default: 0.

        GGFX_SourceWidth (ULONG)
                width of an area inside the picture [pixels].
                Default: The picture's width.

        GGFX_SourceHeight (ULONG)
                height of an area inside the picture [rows].
                Default: The picture's height.

        GGFX_DestWidth (ULONG)
                destination width for the picture to be drawn [pixels].
                Default: the picture's width.

        GGFX_DestHeight (ULONG)
                destination height for the picture to be drawn [rows].
                Default: the picture's height.

        GGFX_CallBackHook (struct @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} *)
                pointer to a callback @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} structure. The associated
                callback function will be called from time to time
                while the picture is being drawn.
                The callback has to return TRUE for continuation or FALSE
                for abortion. It will be submitted a pointer to the
                picture for the object, and a message of the following
                type:

                        ULONG GGFX_MSGTYPE_LINEDRAWN
                        ULONG line_number
                
                Also refer to the example below.
                Default: NULL.

        GGFX_DitherMode (ULONG) - dither mode. Currently available are:

                DITHERMODE_NONE
                        no dithering at all
                
                DITHERMODE_FS
                        Floyd-Steinberg dithering
                        
                DITHERMODE_RANDOM
                        Random dithering. This mode is significantly
                        slower than Floyd-Steinberg dithering.

                DITHERMODE_EDD
                        EDD dithering. This mode is faster than
                        Floyd-Steinberg dithering.
                        
                Default: The drawhandle's dithermode.

        GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
                Currently, this value is of any use only for
                DITHERMODE_RANDOM. Default: The drawhandle's dither amount.

@{b}    RESULTS@{ub}
        success     - TRUE if the picture could be drawn, FALSE
                      if there was not enough memory available.
                      Another reason for this function to fail is that
                      the optional callback hook returned FALSE.

@{b}    NOTES@{ub}
        There is almost no overhead for scaling. Scaling is extremely
        fast and may be considered 'gratis'.

@{b}    EXAMPLE@{ub}
        The callback hook allows to interrupt DrawPictureA() at any time. A
        simple callback function might look like this:

        ULONG __saveds __asm abortdrawfunc(register __a0 struct @{"Hook" Link "TEXT_INCLUDE:utility/hooks.h/Main" 27} *hook)
        {
            ULONG abortsignal = 1 << *((BYTE *) (hook->h_Data));
            if (SetSignal(0, 0) & abortsignal)
            {
                return FALSE;
            }
            else
            {
                return TRUE;
            }
        }
        
        In this example, an abortion signal was allocated and made available
        to the function via h_Data. If the signal arrives, the callback
        function returns FALSE to DrawPictureA(), and drawing will be
        interrupted.
        
        Note: Not all internal drawing-routines actually execute the hook
        function more than once. This mainly depends on the typical speed
        for a particular drawing routine or certain graphics.library or
        cybergraphics.library implementations. At least it is supported
        when scaling and rendering is involved to the drawing process.

@{b}    SEE ALSO@{ub}
        @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}, @{"CreatePictureBitMapA()" Link "CreatePictureBitMapA()"}


@EndNode

@Node "GetPictureAttrsA()" "guigfx.library/GetPictureAttrsA"

@{b}    NAME@{ub}
        GetPictureAttrsA - get picture attributes.
        GetPictureAttrs  - varargs stub for GetPictureAttrsA.

@{b}    SYNOPSIS@{ub}
        count = GetPictureAttrsA(picture,tags)
        d0                       a0      a1

        ULONG GetPictureAttrsA(APTR,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        ULONG GetPictureAttrs(APTR,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function obtains a list of picture attributes. It
        returns the number of attributes that have been retrieved
        actually.

@{b}    INPUTS@{ub}
        picture     - pointer to a picture
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        PICATTR_Width (ULONG *)
                The picture's width [pixels]

        PICATTR_Height (ULONG *)
                The picture's height [rows]

        PICATTR_PixelFormat (ULONG *)
                The picture's internal pixel format. Currently this
                can be PIXFMT_CHUNKY_CLUT, PIXFMT_0RGB_32, or
                PIXFMT_RGB_24.

        PICATTR_RawData (APTR *)
                Pointer to the picture's raw data. Operate on the raw
                pixel array only with knowledge of the actual pixel
                format. Warning: The internal representation of a picture
                may change with every call to @{"DoPictureMethodA()" Link "DoPictureMethodA()"} or
                drawing functions.

        PICATTR_AspectX (ULONG *)
                Horizontal pixel aspect.

        PICATTR_AspectY (ULONG *)
                Vertical pixel aspect.

@{b}    RESULTS@{ub}
        count  - the number of attributes that could be retrieved.


@EndNode

@Node "IsPictureA()" "guigfx.library/IsPictureA"

@{b}    NAME@{ub}
        IsPictureA - determine whether a file is a picture or not. (v4)
        IsPicture  - varargs stub for IsPictureA.

@{b}    SYNOPSIS@{ub}
        ispicture = IsPictureA(filename,tags)
        d0                     a0       a1

        BOOL IsPictureA(char *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        BOOL IsPicture(char *,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function checks if the specified file could be loaded
        as a picture with @{"LoadPictureA()" Link "LoadPictureA()"}.

@{b}    INPUTS@{ub}
        filename    - name of the file to be checked
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_License  - specify this tag if your application is
                        in accordance to the "Tower JPEG Codec Class"
                        license agreements. Default: FALSE

@{b}    RESULTS@{ub}
        ispicture   - TRUE if the specified file is recognized
                      as a picture that could be loaded with
                      @{"LoadPictureA()" Link "LoadPictureA()"}.

@{b}    NOTES@{ub}
        With the tag GGFX_License specified, this function may make use
        of the "Tower JPEG Codec Class" for JPEG support. See separate
        licence if you decide to release applications which make use of
        this function.
        
@{b}    SEE ALSO@{ub}
        @{"LoadPictureA()" Link "LoadPictureA()"}


@EndNode

@Node "LoadPictureA()" "guigfx.library/LoadPictureA"

@{b}    NAME@{ub}
        LoadPictureA - load a picture file.
        LoadPicture  - varargs stub for LoadPictureA.

@{b}    SYNOPSIS@{ub}
        picture = LoadPictureA(filename,tags)
        d0                     a0       a1

        APTR LoadPictureA(char *,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        APTR LoadPicture(char *,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function loads a picture. Currently, this is implemented
        via picture.class datatypes.

@{b}    INPUTS@{ub}
        filename    - name of the file to be loaded
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_ErrorCode (LONG *)
                Pointer to a variable that will receive a standard DOS
                error code. This will be NULL if loading was successful.
                Default: NULL

        GGFX_HSType (ULONG) - picture's internal histogram type, according
                to the histogram types defined in @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}.
                Better you never touch this tag, unless you know exactly
                what you are doing. Consider reading the 'memory' text
                file supplied with the render.library distribution.
                If you specify GGFX_HSType for @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, any
                pictures added to it via @{"AddPictureA()" Link "AddPictureA()"} are automatically
                set to the pen-sharemap's histogram type.
                You do not need this tag under normal circumstances.
                Default: not defined (will be set to the pen-sharemap's
                histogram type, or to the default type when needed)

        GGFX_License  - specify this tag if your application is
                        in accordance to the "Tower JPEG Codec Class"
                        license agreements. Default: FALSE

@{b}    RESULTS@{ub}
        picture  - pointer to a picture or NULL if something went wrong.
                   The exact reason for failure can be obtained via the
                   GGFX_ErrorCode tag.
                   
@{b}    NOTES@{ub}
        With the tag GGFX_License specified, this function may make use
        of the "Tower JPEG Codec Class" for JPEG support. See separate
        licence if you decide to release applications which make use of
        this function.

@{b}    SEE ALSO@{ub}
        @{"IsPictureA()" Link "IsPictureA()"}, @{"MakePictureA()" Link "MakePictureA()"}, @{"ReadPictureA()" Link "ReadPictureA()"}


@EndNode

@Node "LockPictureA()" "guigfx.library/LockPictureA"

@{b}    NAME@{ub}
        LockPictureA - lock picture attributes. (v3)
        LockPicture  - varargs stub for LockPictureA.
        
        *** obsolete ***

@{b}    SYNOPSIS@{ub}
        success = LockPictureA(picture,flags,arguments)
        d0                     a0      d0    a1

        BOOL LockPictureA(APTR,ULONG,ULONG *)
        
        BOOL LockPicture(APTR,ULONG,argument,...)

@{b}    FUNCTION@{ub}
        This function locks certain picture attributes and
        prevents the picture from internal conversions that
        affect the specified flags.

@{b}    INPUTS@{ub}
        picture     - pointer to a picture
        flags       - locking flags
        arguments   - flag-specific arguments

@{b}    FLAGS@{ub}
        LOCKMODE_DRAWHANDLE drawhandle
        
                lock the picture to the specified drawhandle.
                this leads to optimized drawing without the
                need to render. combine with LOCKMODE_FORCE
                if you want to lock the image even if color
                information would be lost.

@{b}    RESULTS@{ub}
        success  - TRUE if locking was successful, FALSE if
                   locking is not possible, or if locking
                   required a conversion with loss of
                   color information.

@{b}    NOTES@{ub}
        This function is currently (v4) not working, and it
        will always return FALSE. If you need optimized drawing,
        use the method PICMTHD_MAPDRAWHANDLE instead.

@{b}    SEE ALSO@{ub}
        @{"UnLockPicture()" Link "UnLockPicture()"}, @{"DoPictureMethodA()" Link "DoPictureMethodA()"}


@EndNode

@Node "MakePictureA()" "guigfx.library/MakePictureA"

@{b}    NAME@{ub}
        MakePictureA - make a picture from raw data.
        MakePicture  - varargs stub for MakePictureA.

@{b}    SYNOPSIS@{ub}
        picture = MakePictureA(data,width,height,tags)
        d0                     a0   d0    d1     a1

        APTR MakePictureA(APTR,UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        APTR MakePicture(APTR,UWORD,UWORD,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function makes a picture from an array of raw
        data, or from a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure. Optionally, memory
        is allocated for a 'blank' picture.

        Unless you specify GGFX_Independent, the raw pixels
        will not be copied to a separate buffer - instead they
        are fetched from their original location. This does not
        apply to @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structures. BitMaps are always converted
        to a separate buffer that is internally maintained with
        the resulting picture.

        If GGFX_Independent is not specified and your picture
        is taken from its original location in memory, you may
        additionally specify a buffer 'overhang' with the tag
        GGFX_BufferSize. This allows internal conversions which
        require the image to grow at its original location in
        memory. You must be the owner of that memory, of course.

@{b}    INPUTS@{ub}
        data    - pointer to
                  - an array of truecolor data,
                  - an array of chunky pixels,
                  - a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure
                  or NULL.
        width   - width [pixels]
        height  - height [rows]
        tags    - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_PixelFormat (ULONG) - pixel format. Currently defined are

                PIXFMT_CHUNKY_CLUT
                        chunky bytes, directly acting as indices
                        to a color-lookup-table.
                
                PIXFMT_0RGB_32
                        truecolor pixels (ULONG 0xaarrggbb).

                PIXFMT_BITMAP_CLUT
                        a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure with normal palette lookup.
                        You must also specify the GGFX_Palette and
                        GGFX_NumColors tags.

                PIXFMT_BITMAP_HAM8
                        a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure with HAM8 color lookup.
                        You must also specify the GGFX_Palette and
                        GGFX_NumColors tags.

                PIXFMT_BITMAP_HAM6
                        a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure with HAM6 color lookup.
                        You must also specify the GGFX_Palette and
                        GGFX_NumColors tags.

                Default: PIXFMT_CHUNKY_CLUT               


        GGFX_Palette (APTR) - pointer to a color table. If this
                tag is not specified with PIXFMT_CHUNKY_CLUT, a
                palette of 256 grey tones will be generated.
                Default: NULL

        GGFX_NumColors (ULONG) - number of colors in the color table.
                Currently, this tag is mandatory when GGFX_Palette
                is specified (see above).
                Default: not defined
                
        GGFX_PaletteFormat (ULONG) - format of the palette. Currently
                defined are:
                      
                PALFMT_RGB8
                        ULONG 0x00rrggbb

                PALFMT_RGB32
                        ULONG red,green,blue. This is the @{"LoadRGB32()" Link "graphics/LoadRGB32()"}
                        format without trailing longword.

                Default: PALFMT_RGB8

        GGFX_BufferSize (ULONG) - total size of the specified buffer
                in bytes. This defines an 'oversized' buffer for the
                array of pixels. It informs the picture to what size
                it may grow for internal conversions. MakePictureA()
                will return NULL if GGFX_BufferSize is smaller than
                required for the array's current dimensions.
                This tag is ignored if you supply a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45} structure,
                or when GGFX_Independent is specified.
                
                Default: Required size in bytes
                for width * height * bytes_per_pixel.

        GGFX_AspectX (ULONG) - picture's horizontal aspect.
                Default: 1

        GGFX_AspectY (ULONG) - picture's vertical aspect.
                Default: 1

        GGFX_AlphaPresent (BOOL) - flag to indicate that the array
                contains alpha-channel information. This tag is only
                considered with PIXFMT_0RGB_32. Default: FALSE

        GGFX_Independent (BOOL) - If set to TRUE, the pixel array will
                always be copied to a seperate buffer that is maintained
                with the picture internally. This tag is ignored when
                the input data is a @{"BitMap" Link "TEXT_INCLUDE:graphics/gfx.h/Main" 45}. Default: FALSE

        GGFX_HSType (ULONG) - picture's internal histogram type, according
                to the histogram types defined in @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}.
                Better you never touch this tag, unless you know exactly
                what you are doing. Consider reading the 'memory' text
                file supplied with the render.library distribution.
                If you specify GGFX_HSType for @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, any
                pictures added to it via @{"AddPictureA()" Link "AddPictureA()"} are automatically
                set to the pen-sharemap's histogram type.
                You do not need this tag under normal circumstances.
                Default: not defined (will be set to the pen-sharemap's
                histogram type, or to the default type when needed)

@{b}    RESULTS@{ub}
        picture  - pointer to a picture or NULL if something went wrong.

@{b}    SEE ALSO@{ub}
        @{"DeletePicture()" Link "DeletePicture()"}, @{"LoadPictureA()" Link "LoadPictureA()"}, @{"ReadPictureA()" Link "ReadPictureA()"}


@EndNode

@Node "ObtainDrawHandleA()" "guigfx.library/ObtainDrawHandleA"

@{b}    NAME@{ub}
        ObtainDrawHandleA - obtain a handle for drawing.
        ObtainDrawHandle  - varargs stub for ObtainDrawHandleA.

@{b}    SYNOPSIS@{ub}
        drawhandle = ObtainDrawHandleA(pensharemap,rastport,colormap,tags)
        d0                             a0          a1       a2       a3

        APTR ObtainDrawHandleA(APTR,struct @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} *,struct @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} *,
                               struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        APTR ObtainDrawHandle(APTR,struct @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} *,struct @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} *,
                              tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function obtains a drawhandle for drawing to a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}.
        Depending on the RastPort's environment, pens may be allocated
        from the @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142}.

        Before a pen-sharemap is passed to this function, it has to
        be loaded with colors via @{"AddPictureA()" Link "AddPictureA()"}, @{"AddPaletteA()" Link "AddPaletteA()"}, and/or
        @{"AddPixelArrayA()" Link "AddPixelArrayA()"}. Otherwise ObtainDrawHandleA() returns NULL.
        
        Optionally, you may specify NULL for the pen-sharemap argument,
        in which case a drawhandle for a static palette will be
        generated.

@{b}    INPUTS@{ub}
        pensharemap - pointer to a pen-sharemap created with
                      @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, or NULL.
        rastport    - pointer to a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}
        colormap    - pointer to a @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142}. Usually, this is
                      screen->ViewPort.ColorMap of the rastport's screen.
        tags        - pointer to an array of TagItems

@{b}    TAGS@{ub}
        OBP_Precision (ULONG) - precision for pen allocations,
                according to the definitions in @{"graphics/view.h" Link "TEXT_INCLUDE:graphics/view.h/Main" 0}.
                See also @{"graphics.library/ObtainBestPenA()" Link "graphics/ObtainBestPenA()"}.
                Default: PRECISION_IMAGE.
                
                Note: The default precision suffices for almost every
                application. ObtainDrawHandleA() obtains pens in an
                extremely effective way. You get excellent results
                even with lower precisions. Commodore's idea with
                @{"ObtainBestPenA()" Link "graphics/ObtainBestPenA()"} was to create a fair and effective
                pen-sharing mechanism, and ObtainDrawHandleA() behaves
                in perfect accordance to this intention. Never use
                insane patches for @{"ObtainBestPenA()" Link "graphics/ObtainBestPenA()"}.
                
        GGFX_DitherMode (ULONG) - dither mode. Currently available are:

                DITHERMODE_NONE
                        no dithering at all
                
                DITHERMODE_FS
                        Floyd-Steinberg dithering
                        
                DITHERMODE_RANDOM
                        Random dithering. This mode is significantly
                        slower than Floyd-Steinberg dithering.

                DITHERMODE_EDD
                        EDD dithering. This mode is faster than
                        Floyd-Steinberg dithering.
                
                Default: DITHERMODE_FS.

        GGFX_DitherAmount (ULONG) - dither amount. Valid range: 0...255.
                Currently this value is of any use only for
                DITHERMODE_RANDOM. Default: 40

        GGFX_AutoDither (BOOL) - automatic dither activation.
                If set to TRUE, dithering is automatically activated for
                drawing a particular picture to a particular environment,
                when the loss of color information would exceed a certain
                threshold (see below). Default: TRUE

        GGFX_DitherThreshold (ULONG) - threshold for automatic dithering.
                The lower, the earlier automatic dithering is activated.
                Useful thresholds range between 10 and 10000. Refer to
                @{"render.library/RGBArrayDiversityA()" Link "render/RGBArrayDiversityA()"} for further details.
                Default: 250

        GGFX_MaxAllocPens (ULONG) - limit for the number of pens to be
                allocated from the @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142}. Do not use this feature
                unless you have a good reason to. Valid range: 0...256.
                Default: not defined

        GGFX_ModeID (ULONG) - screen's modeID. Currently, this is required
                for guigfx.library to detect HAM modes. The full HAM
                color range can be achieved only with this tag specified.
                Default: INVALID_ID (no HAM detection takes place)

@{b}    RESULTS@{ub}
        drawhandle - pointer to a handle for drawing to rastports.
                     NULL if something went wrong.

@{b}    SEE ALSO@{ub}
        @{"ReleaseDrawHandle()" Link "ReleaseDrawHandle()"}, @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, @{"DrawPictureA()" Link "DrawPictureA()"},
        @{"graphics.library/ObtainBestPenA()" Link "graphics/ObtainBestPenA()"},
        @{"render.library/RGBArrayDiversityA()" Link "render/RGBArrayDiversityA()"}


@EndNode

@Node "ReadPictureA()" "guigfx.library/ReadPictureA"

@{b}    NAME@{ub}
        ReadPictureA - read a picture from a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53}.
        ReadPicture  - varargs stub for ReadPictureA.

@{b}    SYNOPSIS@{ub}
        picture = ReadPictureA(rastport,colormap,x, y, width,height,tags)
        d0                     a0       a1       d0 d1 d2    d3     a2

        APTR ReadPictureA(struct @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} *,struct @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} *,UWORD,UWORD,
                          UWORD,UWORD,struct @{"TagItem" Link "TEXT_INCLUDE:utility/tagitem.h/Main" 31} *)

        APTR ReadPicture(struct @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} *,struct @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} *,UWORD,UWORD,
                         UWORD,UWORD,tag,...,TAG_DONE)

@{b}    FUNCTION@{ub}
        This function reads a picture from a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} and a @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142}.

@{b}    INPUTS@{ub}
        rastport - pointer to a @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} where to fetch the pixels from
        colormap - pointer to a @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142} where to fetch color information
                   from. Usually this is screen->ViewPort.ColorMap of the
                   specified RastPort's @{"Screen" Link "TEXT_INCLUDE:intuition/screens.h/Main" 132}.
        x        - left edge in the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} [pixels]
        y        - top edge in the @{"RastPort" Link "TEXT_INCLUDE:graphics/rastport.h/Main" 53} [rows]
        width    - width of the area to be read [pixels]
        height   - height of the area to be read [rows]
        tags     - pointer to an array of TagItems

@{b}    TAGS@{ub}
        GGFX_HSType (ULONG) - picture's internal histogram type, according
                to the histogram types defined in @{"render/render.h" Link "TEXT_INCLUDE:render/render.h/Main" 0}.
                Better you never touch this tag, unless you know exactly
                what you are doing. Consider reading the 'memory' text
                file supplied with the render.library documentation.
                If you specify GGFX_HSType for @{"CreatePenShareMapA()" Link "CreatePenShareMapA()"}, any
                pictures added to it via @{"AddPictureA()" Link "AddPictureA()"} are automatically
                set to the pen-sharemap's histogram type.
                You do not need this tag under normal circumstances.
                Default: not defined (will be set to the pen-sharemap's
                histogram type, or to the default type when needed)

@{b}    RESULTS@{ub}
        picture  - pointer to a picture or NULL if not enough memory.

@{b}    SEE ALSO@{ub}
        @{"LoadPictureA()" Link "LoadPictureA()"}, @{"MakePictureA()" Link "MakePictureA()"}


@EndNode

@Node "ReleaseDrawHandle()" "guigfx.library/ReleaseDrawHandle"

@{b}    NAME@{ub}
        ReleaseDrawHandle - free a drawhandle.

@{b}    SYNOPSIS@{ub}
        ReleaseDrawHandle(drawhandle)
                          a0

        void ReleaseDrawHandle(APTR)

@{b}    FUNCTION@{ub}
        This function discards a drawhandle, frees associated memory, and
        returns allocated pens (if any) to the related @{"ColorMap" Link "TEXT_INCLUDE:graphics/view.h/Main" 142}.

@{b}    INPUTS@{ub}
        drawhandle    - drawhandle obtained via @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}
        
@{b}    SEE ALSO@{ub}
        @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}


@EndNode

@Node "RemColorHandle()" "guigfx.library/RemColorHandle"

@{b}    NAME@{ub}
        RemColorHandle - manually remove a colorhandle.

@{b}    SYNOPSIS@{ub}
        RemColorHandle(colorhandle)
                       a0

        void RemColorHandle(APTR)

@{b}    FUNCTION@{ub}
        This function removes particular color information from
        a pen-sharemap. Further calls to @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"} may
        lead to different pen allocations then.

@{b}    INPUTS@{ub}
        colorhandle    - pointer to a colorhandle from
                         @{"AddPictureA()" Link "AddPictureA()"}, @{"AddPaletteA()" Link "AddPaletteA()"},
                         or @{"AddPixelArrayA()" Link "AddPixelArrayA()"}

@{b}    NOTE@{ub}
        @{"DeletePenShareMap()" Link "DeletePenShareMap()"} arbitrarily frees all its
        colorhandles. There is no need to manually remove
        them. This function is only required if you wish to
        modify a pen-sharemap and then call @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}
        again.
        
        Calling RemColorHandle() for colorhandles that have
        been removed with @{"DeletePenShareMap()" Link "DeletePenShareMap()"} will be fatal.

@{b}    SEE ALSO@{ub}
        @{"AddPictureA()" Link "AddPictureA()"}, @{"AddPaletteA()" Link "AddPaletteA()"}, @{"AddPixelArrayA()" Link "AddPixelArrayA()"},
        @{"DeletePenShareMap()" Link "DeletePenShareMap()"}, @{"ObtainDrawHandleA()" Link "ObtainDrawHandleA()"}


@EndNode

@Node "UnLockPicture()" "guigfx.library/UnLockPicture"

@{b}    NAME@{ub}
        UnLockPicture - unlock picture attributes (v3)

        *** obsolete ***

@{b}    SYNOPSIS@{ub}
        UnLockPicture(picture,flags)
                      a0      d0

        UnLockPicture(APTR,ULONG)

@{b}    FUNCTION@{ub}
        This function frees picture attributes that have been
        locked with @{"LockPictureA()" Link "LockPictureA()"}.

@{b}    INPUTS@{ub}
        picture     - pointer to a picture
        flags       - flags to unlock

@{b}    RESULTS@{ub}
        none

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

@{b}    NOTES@{ub}
        This function will currently (v4) do nothing. @{"Read" Link "dos/Read()"}
        the annotations in @{"LockPictureA()" Link "LockPictureA()"}.
@EndNode

