Reference for unit 'CYBERGRAPHICS'

CyberGraphics System compatbible interface for MorphOS (cybergraphics.library)

Overview

CyberGraphics System compatbible interface for MorphOS (cybergraphics.library) Texts mainly from the official Autodocs http://aminet.net/package/dev/misc/CGraphX-DevKit.lha and MorphOS SDK.

Purpose

cybergraphics.library started as a videoboard extension for the native C= graphics.library. Because C= never completed/released a RTG compliant library (up to and including OS3.1 there was no way to add custom extension boards to the display database in a system friendly way), CyberGraphX patched some of the original graphics functions in order to add custom graphics board support in the system.

It also featured some new functions which were not available in the original graphics.library implementation. Due to the patch approach this new functions had to be moved into a new library base, namely cybergraphics.library. Both OS3.0 graphics.library v39 and OS 3.1 v40 were supported with this patch.

For the first time, CyberGraphX offered the possibility to open non CLUT screens with more than 256 colours which offered complete intuition level legacy compatibility. Nearly every function could be used on such views except some special blits which relied on planar bitmap graphics targets. This screens featured 8bit backwards compatibility which means that nearly every legacy, standard 8bit application even not aware of truecolour abilities worked on this improved screens. The pen allocation system, formerly used to lock certain colour indexes for shared/exclusive application access, had been fully mapped to this new display targets to allow maximum legacy compatibility.

The additional truecolour features could only be used with CyberGraphX aware applications, though. Since there was no similar approach which allowed easy adaption of existing applications, CyberGraphX was widely adopted as the standard interface for truecolour applications at that time.

There were attempts to imitate this efforts but those never caught up with the widely accepted CyberGraphX API.

MorphOS builds upon the above approach and still uses both graphics and cybergraphics library as it's graphics API layer. Additional functions have been added, especially in regard to alpha blending support and other additional eyecandy which is commonly used within MorphOS. Many of this functions are either GPU or AltiVec accelerated starting with Version 2 of MorphOS, dynamically enabled based on the underlying hardware which MorphOS has been started on.

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). LockBitmapTagList()/UnLockBitmap() has been added for this purpose. You have to supply a taglist with LockBitmapTagList() 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.