home *** CD-ROM | disk | FTP | other *** search
/ The AGA Experience 2 / agavol2.iso / software / utilities / wb_tools / picturedt-v43 / autodocs / pct_datatype.doc next >
Text File  |  1996-01-21  |  19KB  |  540 lines
  1. TABLE OF CONTENTS
  2.  
  3. picture.datatype/--background--
  4. picture.datatype/picture.datatype
  5. picture.datatype/--background--             picture.datatype/--background--
  6.  
  7.     PURPOSE
  8.         The new picture.datatype V43 provides new functionality and
  9.         a new api to the application programs and other sub datatypes.
  10.  
  11.     OVERVIEW
  12.  
  13.         o 24 Bit data interface for input and output
  14.  
  15.         o support for chunky 8bit pixels
  16.  
  17.         o support for 24bit iff write into file and clipboard
  18.  
  19.         o support for pixmap directories that allow multi bitmap
  20.           objects.
  21.  
  22.         o optimized OM_RENDER/OM_LAYOUT interface for CyberGfx
  23.           gfxcards.
  24.  
  25.         o needs CyberGraphX
  26.  
  27.     FUNCTION
  28.  
  29.         The picture.datatype knows 2 modes;for the application
  30.         interface and for the sub datatype interface.
  31.         Because of the limitations of the old picture.datatype API
  32.         the new V43 picture.datatype has to be switched into different
  33.         modes before you can use the new features.
  34.         Though for each rule there`s an exception.
  35.         
  36.  
  37.         Application API changes:
  38.  
  39.          The tag PDTA_DestMode changes the picture.datatype between
  40.          MODE_V42, the old picture.datatype mode, and MODE_V43, the
  41.          new mode.
  42.          In MODE_V43 the picture.datatype returns a VOID* Bitmap
  43.          pointer when you ask for a bitmap by PDTA_BitMap or
  44.          PDTA_DestBitMap, so you aren't allowed to assume anything
  45.          about the format of the bitmap by peeking directly.
  46.  
  47.          You can get informations about the bitmap by
  48.  
  49.            o graphics.library/GetBitMapAttr
  50.  
  51.            o graphics.library/ReadPixelArray8
  52.              for GetBitMapAttr(BitMap,BMA_DEPTH) <= 8
  53.  
  54.            o cybergraphics.library/GetCyberMapAttr
  55.  
  56.            o cybergraphics.library/ReadPixelArray
  57.              for BitMap.Depth GetBitMapAttr(BitMap,BMA_DEPTH) >8
  58.  
  59.          Blitting is a bit more difficult.
  60.  
  61.            o If PDTA_BitMap is used you can only blit the bitmap
  62.              into a screen this way.
  63.              This Bitmap contains the raw bitmap data that wasn't
  64.              manipulated to fit into the destination bitmap.
  65.              (no dithering or pen remapping)
  66.  
  67.              Source BitMap   |   Dest BitMap
  68.              ----------------------------------------------------------------
  69.              CLUT(depth<=8)  |   CLUT, Direct Mapped(TrueColour...)
  70.  
  71.              Direct Mapped   |   Direct Mapping. For CLUT destination Bitmaps
  72.                              |   you have to do your own dithering because
  73.                              |   CyberGfx doesn't support dithering yet.
  74.  
  75.              If you only want to buffer the bitmap into your own bitmap to
  76.              be able to delete the picture.datatype object you have to
  77.              create a bitmap with a friend bitmap of the original bitmap.
  78.  
  79.              MyBitMap = AllocBitMap((ULONG) GetBitMapAttr(SourceBitMap,BMA_WIDTH),
  80.                                     (ULONG) GetBitMapAttr(SourceBitMap,BMA_HEIGHT),
  81.                                     (ULONG) GetBitMapAttr(SourceBitMap,BMA_DEPTH),
  82.                                     BMF_MINPLANES,
  83.                                     SourceBitMap);
  84.  
  85.              BltBitMap(SourceBitMap,
  86.                        0,
  87.                        0,
  88.                        MyBitMap,
  89.                        0,
  90.                        0,
  91.                        GetBitMapAttr(SourceBitMap,BMA_WIDTH),
  92.                        GetBitMapAttr(SourceBitMap,BMA_HEIGHT),
  93.                        0xc0,
  94.                        0xff,
  95.                        NULL);
  96.  
  97.            o If PDTA_DestBitMap is used the bitmap is dithered
  98.              or pen remapped to the screen bitmap.
  99.              When you blit this bitmap into a target bitmap the target
  100.              bitmap must be a friend of the screen bitmap that was used
  101.              in the layout.
  102.  
  103.  
  104.          Now to the exception of the MODE43 rules. When the picture.datatype
  105.          is used as a gadget OM_LAYOUT is used automaticly and OM_RENDER will
  106.          blit the optimal bitmap, so there are no changes needed to get nice
  107.          24bit gadgets in your applications !!
  108.  
  109.  
  110.  
  111.         Sub Datatype API changes:
  112.  
  113.          The tag PDTA_SourceMode changes the picture.datatype between
  114.          MODE_V42, the old picture.datatype mode, and MODE_V43, the
  115.          new mode. In the old MODE_V42 the source bitmap is installed by
  116.          passing a pointer to the full bitmap. This method was far too
  117.          unflexible because it doesn't allow to move data line by line
  118.          or block by block and the bitmap type had to be planar and
  119.          therefore this method was slow.
  120.          Furthermore no true colour bitmaps were possible.
  121.          Because there were no method to pass truecolour data there
  122.          were also no dithering implemented therefore sub datatypes
  123.          had to dither the gfx data themselves.
  124.          The new API fixes all these problems.
  125.          When you switch the sub datatype interface into V43 mode
  126.          the picture.datatype allocates the bitmap itself and the
  127.          sub datatype isn't allowed to touch it because it's from
  128.          type VOID.
  129.          You move the gfx pixels into the picture.datatype object
  130.          by the method DTM_WRITEPIXELARRAY. This method is flexible
  131.          to allow the sub datatype to pass data by lines,blocks or
  132.          a full bitmap.
  133.          When you use PDTA_BitMap in V43 mode the bitmap is copied
  134.          into the internal bitmap and you have to free the passed
  135.          bitmap yourself !
  136.          DTM_WRITEPIXELARRAY understands the array formats CybergraphX
  137.          supports:
  138.  
  139.           o RECTFMT_RGB
  140.           o RECTFMT_RGBA
  141.           o RECTFMT_ARGB
  142.           o RECTFMT_LUT8
  143.           o RECTFMT_GREY8
  144.           o perhaps more in the future, like
  145.             o RECTFMT_CHANNELR(not implemented yet)
  146.             o RECTFMT_CHANNELG(not implemented yet)
  147.             o RECTFMT_CHANNELB(not implemented yet)
  148.             o RECTFMT_CHANNELALPHA(not implemented yet)
  149.  
  150.  
  151.     MUST KNOW
  152.  
  153.          OM_RENDER with transparent bitmaps isn't as easy as it seems on
  154.          first look. For a transparent or alpha bitmap the picture.datatype
  155.          generates a mask plane for pixels that should be copied and
  156.          which not. Now let's assume the multiview window can't show the
  157.          whole transparent bitmap and you want to scroll in it.
  158.          The effect is that old bitmap pixels aren't overwritten because
  159.          of the mask and then it looks as if you have a smear effect.
  160.          Well..the current "solution" is that i first blit the bitmap
  161.          with the mask and when OM_RENDER is called a second time and with
  162.          a different offsets i blit without a mask...this way the image may
  163.          look different each time you scroll it in multiview but you can
  164.          still see what it means.
  165.  
  166.     EXAMPLE
  167.  
  168.  
  169.         Application API side:
  170.  
  171.          o Creating a V43 Datatype Object
  172.  
  173.            dto = (Object *) NewDTObjectA(APTR name,
  174.                                          PDTA_DestMode,MODE_V43,
  175.                                          ...)
  176.  
  177.  
  178.          o Obtaining Environment Information for a DataType
  179.  
  180.            GetDTAttrs(dto,
  181.                       PDTA_ModeID,&modeid,    /* Is only the original ModeID when HAM,HAM6 or Halfbright are used*/
  182.                       PDTA_BitMapHeader,&bmhd,
  183.                       TAG_DONE);
  184.  
  185.            if (bmhd.bmh_Depth<=8)
  186.            {
  187.               GetDTAttrs(dto,
  188.                          PDTA_CRegs, &cregs,
  189.                          PDTA_NumColors, &numcolors,
  190.                          TAG_DONE);
  191.            }
  192.            else 
  193.            {
  194.              /* HiColour/TrueColour Bitmap..perhaps with Alpha ? */
  195.            }
  196.  
  197.  
  198.  
  199.          o What you're NOT allowed to do!!!!
  200.  
  201.            Never use the PDTA_BitMap or PDTA_DestBitMap as a custom
  202.            screen bitmap by SA_BitMap in V43 mode!!!
  203.  
  204.  
  205.  
  206.         Datatype API side:
  207.  
  208.          o Check for V43 picture.datatype
  209.  
  210.            /* Get the supported Method Array Ptr from the picture.datatype */
  211.            getdtattrs(cb, o,
  212.                       DTA_Methods, &MethodArray,
  213.                       TAG_DONE);
  214.  
  215.            /* Now we search for the new DTM_BLITPIXELARRAY method to determine
  216.               if it's the new V43 picture.datatype */
  217.  
  218.            MethodArrayPtr=MethodArray;
  219.            while (*MethodArrayPtr!=0xffffffff)
  220.            {
  221.              if (*MethodArrayPtr == DTM_BLITPIXELARRAY)
  222.                 break;
  223.              MethodArrayPtr++;
  224.            }
  225.  
  226.            if (*MethodArrayPtr == DTM_BLITPIXELARRAY)
  227.            {
  228.              /* Do your V43 stuff */
  229.            }
  230.            else
  231.            {
  232.              /* Do your V42 stuff..if you want to stay compatible */
  233.            }
  234.  
  235.          o Set API into V43 mode
  236.  
  237.            if ((getdtattrs (cb,
  238.                             o,
  239.                             DTA_Handle,
  240.                             &fh,
  241.                             PDTA_BitMapHeader,
  242.                             &bmhd,
  243.                             TAG_DONE) == 2) && fh)
  244.            {
  245.              /* Scan file..and fill out bmhd->bmh_Width,bmh_Height,bmh_Depth,... */
  246.  
  247.              setdtattrs(cb, o,
  248.                         DTA_ObjName,title,
  249.                         DTA_NominalHoriz,bmhd->bmh_Width,
  250.                         DTA_NominalVert,bmhd->bmh_Height,
  251.  
  252.              /* Set the V43 picture.datatype sub-datatype input interface into
  253.              V43 mode */
  254.                         PDTA_SourceMode,MODE_V43,
  255.  
  256.              /* The modeid isn't that important...well only in the sense to
  257.                 decide if it's a normal mode or something special like ham
  258.                 or extra-halfbrite */
  259.                         PDTA_ModeID,modeid,
  260.  
  261.              /* These fields tell the subdatatype if the operation failed and
  262.                 why. Level contains the Dos levels (RETURN_??) and Number
  263.                 contains the Dos error numbers(ERROR_??) */
  264.  
  265.                         DTA_ErrorLevel,&ErrorLevel,
  266.                         DTA_ErrorNumber,&ErrorNumber,
  267.                         TAG_DONE);
  268.  
  269.          o Transfer Pixel data into the object
  270.  
  271.            /* Pass the buffer data to the picture.datatype.
  272.               The data if type RECTFMT_RGB(defined in the cybergfx includes).
  273.               You can even pass the data in rectangles to the picture.datatype
  274.               instead of several lines used in this datatype */
  275.  
  276.            DoSuperMethod(cl, o,
  277.                          DTM_WRITEPIXELARRAY,
  278.                          (ULONG) PixelBuffer,
  279.                          RECTFMT_RGB,            /* Pixel format */
  280.                          bmhd->bmh_Width*3,        /* Modula to the next pixel line */
  281.                          0,                /* X=0 */
  282.                          TopEdge,            /* Y=Loop counter */
  283.                          bmhd->bmh_Width,        /* Line Width in Pixels */
  284.                          Lines);            /* Lines you want to transfer each time*/
  285.  
  286.  
  287.          o What you're NOT allowed to do!!!!
  288.  
  289.            The pixel format you use mustn't be incompatible with the bmh_Depth
  290.            you specify.
  291.            For example when your pixel format is a direct mapped colour format
  292.            you mustn't specify a CLUT bmh_depth <=8.
  293.  
  294.  
  295. picture.datatype/picture.datatype           picture.datatype/picture.datatype
  296.  
  297.     NAME
  298.     picture.datatype -- root data type for pictures.
  299.  
  300.     FUNCTION
  301.     The picture.datatype is the super-class for any picture related
  302.     classes.
  303.  
  304.     METHODS
  305.     OM_NEW -- Create a new picture object.
  306.  
  307.     OM_GET -- Obtain the value of an attribute.
  308.  
  309.     OM_SET -- Set the values of multiple attributes.
  310.  
  311.     OM_UPDATE -- Update the values of multiple attributes.
  312.  
  313.     OM_DISPOSE -- Dispose of a picture object.
  314.  
  315.     GM_LAYOUT -- Layout the object and notify the application of the
  316.         title and size.
  317.  
  318.     GM_HITTEST -- Determine if the object has been hit with the
  319.         mouse.
  320.  
  321.     GM_GOACTIVE -- Tell the object to go active.
  322.  
  323.     GM_HANDLEINPUT -- Handle input.
  324.  
  325.     GM_RENDER -- Cause the graphic to render.
  326.  
  327.     DTM_PROCLAYOUT -- Layout (remap) the picture on the application's
  328.         process.
  329.  
  330.     DTM_FRAMEBOX -- Obtain the display environment that the picture
  331.         requires.
  332.  
  333.     DTM_SELECT -- Select an area in the picture.
  334.  
  335.     DTM_CLEARSELECTED -- Deselect the selected area of the picture.
  336.  
  337.     DTM_COPY -- Copy the selected area of the picture to the clipboard
  338.         as an ILBM.  If no area is selected, then the entire picture
  339.         is copied.
  340.  
  341.     DTM_PRINT -- Print the selected area of the picture.  If no area
  342.         is selected, then the entire picture is printed.
  343.  
  344.     DTM_WRITE -- Write the selected area of the picture to a file as an
  345.         ILBM.  If no area is selected, then the entire picture is
  346.         saved.
  347.  
  348.         DTM_WRITEPIXELARRAY -- V43
  349.             This method is used to transfer pixel data to the
  350.             picture.datatype object in the specified format.
  351.             The cybergraphics pixel array formats are supported.
  352.             (struct gpBlitPixelArray) is the msg format for this Method that
  353.             can be found in pictureclassext.h.
  354.             The picture.datatype source mode has to be switched to V43 before.
  355.  
  356.         DTM_READPIXELARRAY -- V43
  357.             This method is used to transfer pixel data from the
  358.             picture.datatype object in the specified format.
  359.             (struct gpBlitPixelArray) is the msg format for this Method that
  360.             can be found in pictureclassext.h.
  361.             The picture.datatype source mode has to be switched to V43 before.
  362.  
  363.         DTM_CREATEPIXMAPDIR -- V43
  364.             This method is used to create a new pixmap directory for multi
  365.             volume bitmap data. Afterwards the current pixmap is the new
  366.             created one.
  367.  
  368.         DTM_FIRSTPIXMAPDIR -- V43
  369.             This method is used to set the current pixmap to the first one
  370.             in the list.
  371.  
  372.         DTM_NEXTPIXMAPDIR -- V43
  373.             This method is used to set the current pixmap to the next one
  374.             in the list.
  375.  
  376.         DTM_PREVPIXMAPDIR -- V43
  377.             This method is used to set the current pixmap to the previous
  378.             one in the list.
  379.  
  380.         DTM_BESTPIXMAPDIR -- V43
  381.             This method sets the PixMap directory to the best one fitted
  382.             for the screen. For example multi-volume tiffs used by NextStep
  383.             have s&w and color pixel informations included for the
  384.             different display modes.
  385.  
  386.  
  387.     TAGS
  388.     OBP_Precision (ULONG) -- Precision to use when obtaining colors.
  389.         See the PRECISION_ defines in <graphics/view.h>.
  390.  
  391.         Applicability is (I).
  392.  
  393.     PDTA_ModeID (ULONG) -- Set and get the graphic mode id of the
  394.         picture.
  395.  
  396.         Applicability is (ISG).
  397.  
  398.     PDTA_BitMapHeader (struct BitMapHeader *) -- Set and get the
  399.         base information for the picture.  BitMapHeader is defined in
  400.         <datatypes/pictureclass.h>
  401.  
  402.         Applicability is (G).
  403.  
  404.     PDTA_BitMap (struct BitMap *) -- Pointer to a class-allocated
  405.         bitmap, that will end up being freed by the picture class in the
  406.         OM_DISPOSE method.
  407.  
  408.         Applicability is (ISG).
  409.  
  410.     PDTA_ColorRegisters (struct ColorRegister *) -- Color table.
  411.  
  412.         Applicability is (G).
  413.  
  414.     PDTA_CRegs (ULONG *) -- Color table to use with SetRGB32CM().
  415.  
  416.         Applicability is (G).
  417.  
  418.     PDTA_GRegs (ULONG *) -- Color table.
  419.  
  420.         Applicability is (G).
  421.  
  422.     PDTA_ColorTable (ULONG *) -- Shared pen table.
  423.  
  424.         Applicability is (G).
  425.  
  426.     PDTA_ColorTable2 (ULONG *) -- Shared pen table.
  427.  
  428.         Applicability is (G).
  429.  
  430.     PDTA_Allocated (ULONG) --  Number of shared colors allocated.
  431.  
  432.         Applicability is (G).
  433.  
  434.     PDTA_NumColors (WORD) -- Number of colors used by the picture.
  435.  
  436.         Applicability is (ISG).
  437.  
  438.     PDTA_NumAlloc (WORD) -- Number of colors allocated by the picture.
  439.  
  440.         Applicability is (G).
  441.  
  442.     PDTA_Remap (BOOL) -- Indicate whether the picture should be
  443.         remapped or not.
  444.  
  445.         Applicability is (I).
  446.  
  447.     PDTA_Screen (struct Screen *) -- Pointer to the screen to remap
  448.         the picture to.  Only used if the object is not going to be
  449.         added to a window.
  450.  
  451.         Applicability is (IS).
  452.  
  453.     PDTA_FreeSourceBitMap (BOOL) -- Indicate whether the source
  454.         bitmap should be freed immediately by the picture.datatype
  455.         after the GM_LAYOUT method is called.
  456.  
  457.         Applicability is (IS).
  458.  
  459.     PDTA_Grab (Point *) -- Pointer to a Point structure, that
  460.         defines the grab point of the picture.
  461.  
  462.         Applicability is (ISG).
  463.  
  464.     PDTA_DestBitMap (struct BitMap *) -- Pointer to the remapped
  465.         bitmap.
  466.  
  467.         Applicability is (G).
  468.  
  469.     PDTA_ClassBitMap (struct BitMap *) --
  470.  
  471.         Applicability is (ISG).
  472.  
  473.     PDTA_NumSparse (UWORD) -- Number of entries in the sparse color
  474.         table.
  475.  
  476.         Applicability is (I).
  477.  
  478.     PDTA_SparseTable (UBYTE *) -- Pointer to a table of pen numbers
  479.         indicating which colors should be used when remapping the
  480.         picture.  This array must contain as many entries as indicated
  481.         by the PDTA_NumSparse tag.
  482.  
  483.         Applicability is (I).
  484.  
  485.     PDTA_SourceMode (ULONG) -- V43
  486.             Switches between the old and new pixel data source mode.
  487.             In detail...this mode is set by subclasses of the
  488.             picture.datatype to switch between the old and new data
  489.             interface.
  490.             Check out the Method DTM_WRITEPIXELARRAY.
  491.  
  492.         Applicability is (S).
  493.  
  494.     PDTA_DestMode (ULONG) -- V43
  495.             Switch between the old and new pixel data destination mode.
  496.             In detail...this mode is set by applications when they want
  497.             to use the picture.datatype's bitmap. In the old mode
  498.             you always get a 8bit standard bitmap even for 24bit pixel
  499.             informations.
  500.             In the new V43 mode you get the real picture.datatype bitmap
  501.             that can be a CyberGfx bitmap with planar or truecolour format
  502.             so you're not allowed to assume anything about the bitmap format.
  503.             Use GetBitMapAttr(), ReadPixelArray8(GfxBase) and
  504.             ReadPixelArray(CyberGfxBase) to handle the data.
  505.  
  506.         Applicability is (I).
  507.  
  508.         PDTA_NumPixMapDirs (ULONG) -- V43
  509.             Number of PixMap directories for the object.
  510.  
  511.         Applicability is (G).
  512.  
  513.         PDTA_UseFriendBitMap (BOOL) -- V43
  514.             Tells the picture.datatype to return a friend bitmap of the
  515.             screen to optimize multiple render operations.
  516.  
  517.         Applicability is (SG).
  518.  
  519.         PDTA_AlphaChannel (BOOL) -- V43
  520.             Tells the picture.datatype not to ignore alpha channel data
  521.             from a DTM_WritePixelArray method.
  522.             This method is OBSOLETE...please use the flag in BMHD.
  523.  
  524.         Applicability is (SG).
  525.  
  526.         PDTA_MultiRemap (BOOL) -- V43
  527.             Tells the picture.datatype not to free a layouted bitmap and
  528.             pens. These are now controlled by the application.
  529.            
  530.         Applicability is (SG).
  531.  
  532.     PDTA_MaskPlane (ULONG) -- V43
  533.             If a transparent,mask,alpha flags are set in
  534.             BitMapHeader.bmh_Masking you can get or set the
  535.             mask plane by this tag.
  536.             The maskplane can be used at for BltBitMapRastPort().
  537.  
  538.  
  539.  
  540.