Reference for unit 'cybergraphics'

RTG Amiga graphic functions of the CyberGraphics System by phase5 (cybergraphics.library)

Overview

RTG Amiga graphic functions of the CyberGraphics System by phase5 (cybergraphics.library) Texts mainly from the official Autodocs http://aminet.net/package/dev/misc/CGraphX-DevKit.lha

Purpose

cybergraphics.library is meant to be a gfx board extension for the native graphics.library. Because C= never developed a rtg compliant graphics.library (up to OS3.1 there are no possibilities to add custom boards into the display database in a system friendly fashion), it patches some of the original graphics functions in order to integrate custom graphics boards into the system.

It also features some new functions which are not available in the standard graphics.library. Currently graphics.library v39 and v40 is supported.

Additionally it is possible to open screens deeper than 256 colours which are completely intuition compatible. Nearly every function may be used on such screen except some special blits which rely on planar bitmap graphics. Also, this screens are 8bit backwards compatible. Nearly every standard 8bit application will work on this 15/16/24 bit screen. But it only can use the additional features, if it knows of CyberGraphX, of course.

Maybe in a future release of graphics, CyberGraphX will be obsolete. But until then, cybergraphics.library is the only way to add truecolour features to your application under an intuition environment with minimum effort.

So, CyberGraphX is not meant to be a replacement for the original graphics/intuition system (just like EGS is for example), e.g. there is no ECS/AGA native chipset CyberGraphX driver, because all the functionality of the original chipset is already given in the original graphics.library.

Overview

This part only describes how to use the extended features of CyberGraphX. Anything else about programming graphics can be found in the original graphics.library documentation. Most graphics.library functions are extended to work on CyberGraphX's 15/16/24 bit rastports.

Bitmaps and CyberGraphX

Before OS 3.x there was no standard method to create bitmaps. It was up to the application programmer to allocate memory for the bitmap structure and to get the plane pointers by subsequent calls to AllocRaster()/gfx. A InitBitMap() call was available to initialize various elements in the bitmap structure.

Unfortunately some people didn't even use AllocRaster() and InitBitMap() to setup their bitmaps but used ExecAllocMem() and initialized the bitmap structure on their own.

Because there was only one certain bitplane format description, it was no problem to directly poke into the allocated planes. It even was no problem to alter the contents of the bitmap structure because the application had total control over the location and the contents of this structure and related plane pointers.

Starting with OS 3.x two new graphics calls were added to support bitmap creation and removal: AllocBitmap()/gfx and FreeBitmap()/gfx. With this calls the first step was made to allow custom bitmap formats. Before it was no problem at all to directly render into the planes or to make assumptions about the structure of the bitmap data. To get more information about the bitmap data an information retrieval call was added: GetBitmapAttr()/gfx. With this one you could get information on the width, height, depth and certain flags of the bitmap. This was the first step into the RTG direction. As soon as GetBitmapAttr(bm, BMA_FLAGS) didn't return BMF_STANDARD, the bitmap was not direct accessable anymore and could only be accessed by attachment to a rastport and subsequent rendering calls or by using blit calls with a standard amiga bitmap as destination.

Unfortunately many programs didn't follow these guide lines and didn't check for the BMF_STANDARD flag with OS3.0 and above. Up to now many programs still use the methods described at the beginning of this chapter. That's one reason why graphics extensions like CyberGraphX still have to fiddle around with planar to chunky conversions, even if the underlying hardware doesn't support planar graphics anymore. This often leads to dramatic speed losses with certain applications which often could be redundant if standard rendering calls were used.

So please use AllocBitmap()/FreeBitmap() whereever possible when running 3.x. It really gives you a major performance improvement in most cases when used on 3rd party display adapters. Don't forget to add a friend bitmap pointer whereever possible to allocate compatible bitmap structures.

With CyberGraphX you also have to add BMF_MINPLANES in the flags field of AllocBitmap()/gfx. This is due to bug in the standard picture.datatype which doesn't check for BMF_STANDARD and directly pokes into the bitplanes even if the returned bitmap is non planar ...... Using BMF_MINPLANES in a non CyberGraphX environment remains still compatible and should not lead to any problems, with CyberGraphX a chunky bitmap is returned, if a chunky friendbitmap is supplied. How to access the bitmap data will be discussed later on. Don't make assumptions on the bitmap contents before you have called the required CyberGraphX library calls!!

Besides the AllocBitmap() friend bitmap method, AllocBitmap() has been extended to allow for allocation of certain pixel format bitmaps when using CyberGraphX. With CyberGraphX, bitmaps aren't limited to planar image maps or 8 bit chunky data (which wasn't even available with the standard chipset/ graphics.library) anymore. It is also possible now to allocate device dependant pixel format bitmaps and standard 15/16/24/32 bit depth image maps. Therefore new bits in the 32bit flags field parameter of AllocBitmap() have been added. If you specify the BMB_SPECIALFMT bit (see includes), the upper 8 bits of the flags longword contain information on the pixel format of the requested bitmap. The following pixel formats are available:

PIXFMT_LUT8, PIXFMT_RGB15, PIXFMT_BGR15, PIXFMT_RGB15PC, PIXFMT_BGR15PC, PIXFMT_RGB16, PIXFMT_BGR16, PIXFMT_RGB16PC, PIXFMT_BGR16PC, PIXFMT_RGB24, PIXFMT_BGR24, PIXFMT_ARGB32, PIXFMT_BGRA32, PIXFMT_RGBA32

Many of this pixel formats are device specific and should not be used, recommended formats are PIXFMT_LUT8, PIXFMT_RGB16, PIXFMT_RGB24 and PIXFMT_ARGB32.

Once allocated, you can attach the returned bitmap to a rastport and do rendering calls. It is not possible to attach this bitmap to a screen by supplying it as custom bitmap with OpenScreenTagList()!!

You are not allowed to directly poke into the bitmap image data as long as the bitmap isn't locked! The location and contents of the image data is subject to change and is only valid when it's locked by using the available locking calls (see autodocs). LockBitmapTags()/UnLockBitmap() has been added for this purpose. You have to supply a taglist with LockBitmapTags() which contains pointers to longwords which are filled with valid data if the call returns with a non-zero value. Only if a non-zero value is returned you are able to access the bitmap directly! Check the address you get back with the LBMI_BASEADDRESS tag. This is the base address you can do your rendering to. Get the value of the LBMI_PIXFMT ULONG field to get information on the colormodel you have to use for image rendering. All models have to be supported! The other fields give you information on the layout of the bitmap data. It should be no problem, to directly render into the bitmap anymore. Keep in mind that all this values are only valid until a subsequent call to UnLockBitmap(). Afterwards you have to lock the bitmap again. Don't hold this lock for longer than one frame! You may use the standard graphics.library bitmap blitting calls to copy the bitmap contents to another bitmap. Copying truecolour bitmaps into indexed colour chunky bitmaps is not supported by now.