home *** CD-ROM | disk | FTP | other *** search
/ Enigma Amiga Life 109 / EnigmaAmiga109CD.iso / software / sviluppo / chunkyppc / chunkyppc.docs < prev    next >
Text File  |  2000-02-05  |  14KB  |  417 lines

  1. The ChunkyPPC Library
  2. =====================
  3.  
  4. --- snip ---
  5.  
  6. Newsflash:
  7.  
  8. This is a major new version of chunkyppc.library.
  9.  
  10. Note: The new functions are ONLY supported if you use chunkyppc.library
  11. as library, using it with linkchunkyppc.lib does not support the new
  12. functions !!! I included the old version of the linkchunkyppc.lib though,
  13. it just does not cover the new functions of V3+. If you need V3+, use
  14. it as Shared Library.
  15.  
  16. Mainly i included some new functions on request from *Hyperion Software* !!!
  17.  
  18. Hyperion wanted a OpenScreen/CloseScreen interface which can handle:
  19.  
  20. - Open on a Screen
  21. - Open on a WB Window
  22. - Open on a PIP Window
  23. - Open on a Pubscreen
  24. - use ASL Requester, not rtgmaster
  25. - rtgmaster requester optionally
  26. - change screenmodes of a running program "on the fly" (without having
  27.   to quit the program)
  28. - automatically handle Chunky-Format Conversions
  29. - Support for all 16 Bit Formats, RGB15 and LUT8 needed
  30. - For AGA 8 Bit and HAM8 needed
  31. - LoadRGB32 Feature with included Color-Adaption for WB-Window
  32. - Doublebuffering (both AllocScreenBuffer and ScrollVPort) and
  33.   Triple Buffering Support
  34. - Support for Custom Hooks both on 68k and WarpUP
  35. - has to work on both 68k and PowerPC (WarpUP)
  36.  
  37. Note: AGA Mode claims to be 15 Bit, but is really 16 Bit :) Just always
  38. use PIXFMT_RGB15 for AGA in ChunkyInit :)
  39.  
  40. Note: Executables compiled for chunkyppc.library V3-V9 (which were internal
  41. releases anyways) don't work anymore on V10. This is V10. If you have a
  42. Beta V3-V9, don't give it to anyone, to avoid confusion. Only versions
  43. which should be given to other people are V10 or the old V2 ones. But
  44. nothing "in-between".
  45.  
  46. Note: Due to the special implementation of EGCS-WarpUP the ms.algo cannot
  47. be called directly with it. Use The CallChunkyCopy #define in the
  48. include instead. For other compilers you can just
  49.  
  50. #define CallChunkyCopy ms.algo
  51.  
  52. Since V3.0 chunkyppc.library supports these features.
  53.  
  54. There are the following new functions:
  55.  
  56. OpenGraphics
  57. ------------
  58.  
  59. a0 : Title (of the program)
  60. a1 : Mode_Screen structure
  61. d0 : override flag
  62.  
  63. This function opens a screenmode-requester and after this a screen/window.
  64. It uses the following env-variables:
  65.  
  66. <Title>/modeid:
  67.  
  68. if the override flag is *not* set, use this modeid, if the ENV Variable
  69. is set (and if not, open a screenmode requester). If the flag is set, always
  70. open a screenmode requester. So default a Screenmode can be used, once the
  71. user saved one, but the screenmode can in-game still be changed.
  72.  
  73. Since V5 there is (on request of Hyperion Software) a override mode == 2.
  74. If this is set, inside env:<Title> (and envarc:<Title>) there will be a
  75. small Screenmode Database. OpenGraphics() then checks, if a modeid file
  76. is already found in the directory, if this modeid file has the correct
  77. resolution. This way it is possible to maintain several different resolutions
  78. in one database, without the screenmode-requester popping up on every
  79. screen-width/height/depth change (the names of the files are modeid,
  80. modeid1, modeid2, ...). Up to 21 entries (modeid, modeid1, ..., modeid20)
  81. are supported, if more are entered, modeid20 is changed always).
  82.  
  83. <Title>/dbuf:
  84.  
  85. Use Doublebuffering
  86.  
  87. <Title>/oldstyle
  88.  
  89. If this is set, ScrollVPort will be used, else Triple Buffering using
  90. ScreenBuffers.
  91.  
  92. <Title>/wb
  93.  
  94. If this is set, a Workbench Window will be used, not a screen
  95.  
  96. <Title>/pip
  97.  
  98. If this is set, a Picture in Picture will be used using the Picasso96API.library.
  99. Note: Not all Graphics Boards Support this. Currently only P96 PIP is supported,
  100. not CGX. Maybe in the future...
  101.  
  102. <Title>/ham
  103.  
  104. Use HAM8 mode for AGA. If this is not set, 8 Bit mode is used for AGA.
  105.  
  106. <Title>/pipnoclear
  107.  
  108. If this is set to 1, the PIP won't be cleared when opened.
  109.  
  110. <Title>/rtgmaster
  111.  
  112. Use rtgmaster Screenmode Requester instead of ASL one. rtgmaster.library
  113. will only be opened when this option is set, so that rtgmaster.library
  114. does not need to be installed to be able to use chunkyppc.library.
  115.  
  116. <Title>/resize
  117.  
  118. Set Resizing Factor of PIP (from 1.0 to whatever... does not need to be
  119. an integer number...)
  120.  
  121. <Title>/likecgx
  122.  
  123. If you want CGX-like WB Window Support for P96 (Faster, but Window Borders
  124. disappear). For CGX it is automatically set, as it is the only possible
  125. method for CGX to reach (at least for 16 Bit) WB Window Support, for P96
  126. it is optional.
  127.  
  128. Hyperion Software will support a GUI to set these ENV-Variables for their
  129. products, as they told me.
  130.  
  131. The Mode_Screen structure is a special structure containing information
  132. on the screen, like the Screen-Structure of Intuition or the RtgScreen
  133. structure of rtgmaster. It does not matter if you got it by OpenGraphics
  134. or constructed it yourselves. The Mode_Screen structure also gets the
  135. minimum/maximum Width/Height/Depth, so you should init these values before you
  136. call OpenGraphics.
  137.  
  138. If the video_screen element of Mode_Screen is !=0 this screen will be closed,
  139. and a new one will be opened ("on-the-fly-screen-change").
  140.  
  141. The important elements of Mode_Screen (like defined in clib/chunkyppc_protos.h):
  142.  
  143. video_screen: An Intuition Screen
  144. video_window: An Intuition Window
  145. bpr: Bytes Per Row
  146. mode: The ModeID
  147. SCREENWIDTH: Minimal Width/Actual Width
  148. SCREENHEIGHT: Minimal Height/Actual Height
  149. MAXWIDTH: Maximum Width
  150. MAXHEIGHT: Maximum Height
  151. MINDEPTH: Minimum Depth
  152. MAXDEPTH: Maximum Depth
  153. format: Video Format (using Cybergraphics constants)
  154. video_depth: BitsPerPixel
  155. screen: Buffer 0 Video RAM / Address BitPlane 0
  156. screenb: Buffer 1 Video RAM / Address Bitplane 1
  157. screenc: Buffer 2 Video RAM / Address Bitplane 2
  158. bufnum: Active Buffer number
  159. bitmapa-bitmapc: the Bitmaps
  160. thebitmap: Active Bitmap
  161. numbuffers: Number of Buffers (ScrollVPort only 2, no DBuffering only 1)
  162. algo: Function-pointer to Chunky-Copy Algorithm
  163.  
  164. CloseGraphics
  165. -------------
  166.  
  167. a0: Mode_Screen structure
  168. d0: shutdownlibs Flag
  169.  
  170. This closes the Screen/Window again (and all other stuff... :) )
  171.  
  172. If shutdownlibs is set, the libraries used will also be closed.
  173. If not they will not be closed.
  174.  
  175. LoadColors
  176. ----------
  177.  
  178. This is basically the same like LoadRGB32 of graphics.library or
  179. LoadRGBRtg of rtgmaster. Set the colors of a 8 Bit Screen. Does nothing
  180. for a 15/16 Bit Screen.
  181.  
  182. a0: Mode_Screen structure
  183. a1: Color-array like for LoadRGB32/LoadRGBRtg
  184.  
  185. DoubleBuffer
  186. ------------
  187.  
  188. a0: Mode_Screen structure
  189.  
  190. Causes Double/Triplebuffering (depending on value of env:<Title>/oldstyle
  191. and env:<Title>/dbuf). Note WB Window and PIP Modes are single buffered.
  192. For Single-Buffered this does not do anything. For Triplebuffering it
  193. switches buffers in the sequence (when the screen is just opened buffer
  194. 0 is always active !!!) <0 is active at startup>-1-2-0-1-2-0 or
  195. <0 is active at startup>-1-0-1-0...
  196.  
  197. ChunkyInit
  198. ----------
  199.  
  200. r4: Mode_Screen structure
  201. r5: srcformat
  202.  
  203. This initializes ms->algo with a PowerPC ChunkyCopy/c2p including Colorformat
  204. Conversion according to src and destination format (ms->format...).
  205.  
  206. ChunkyInit68k
  207. -------------
  208.  
  209. a0: Mode_Screen structure
  210. d0: srcformat
  211.  
  212. This time a 68k function, and initializes ms->algo with a 68k algorithm.
  213.  
  214. If ChunkyInit/ChunkyInit68k returns 0, this means the source and the
  215. destination formats are incompatible !!!
  216.  
  217. The following formats are compatible currently:
  218.  
  219. - for PowerPC all 8 Bit and 16 Bit formats, and RGB15 15 Bit Format
  220. - on 68k 8 Bit and all 15 Bit and 16 Bit formats, but 15/16 Bit only
  221.   if source and destination have identical formats (68k currently
  222.   does not support format conversion)
  223. - For AGA: On Workbench Window only 8 Bit, naturally
  224. - For AGA: HAM8 mode only on PowerPC
  225. - On Workbench Window: 15/16 Bit formats only supported for Picasso 96,
  226.   as WritePixelArray of CyberGraphX does not support a 15/16 Bit
  227.   Input Format. On a Screen it is supported also for CGX though.
  228.   If you want this on CGX too -> write the CGX authors about it.
  229.  
  230. The Chunky Algorithms
  231. ---------------------
  232.  
  233. 68k:
  234.  
  235. a0: Mode_Screen structure
  236. a1: dest
  237. a2: src
  238. d0: srcformat
  239. d1: hook68k
  240. d2: data
  241.  
  242. PPC:
  243.  
  244. r4: Mode_Screen structure
  245. r5: dest
  246. r6: src
  247. r7: srcformat
  248. r8: hook68k
  249. r9: data
  250.  
  251. This performs a fullscreen copy of "src" to "dest" performing all
  252. needed format conversion. srcformat is in CyberGraphics Synax
  253. (PIXFMT_RGB16 or such). src is a Video RAM Pointer for GFX Board (you
  254. have to take care yourselves, if that of buffer 0,1 or 2 has to be
  255. provided). For AGA it is a pointer to the correct Bitmap instead !!!
  256.  
  257. After the Copy has been done, the hook68k will be performed using
  258. a Contextswitch (or for 68k as function call), if hook68k is != 0.
  259. If hook68k is 0 this will not be done. data is the parameter (void *)
  260. of hook68k, and the function returns the return value of the hook
  261. (or 0, if no Hook was provided).
  262.  
  263. Why this ?
  264.  
  265. There are some things which can't be run on the PPC:
  266.  
  267. - lowlevel.library
  268. - Keyboard Code
  269. - Sound Code
  270. - Doublebuffering
  271. - LoadColors
  272.  
  273. Most program authors perform one contextswitch for each of those.
  274. Every contextswitch takes away 0.5-0.6 ms. Now it is possible
  275. to put several of them together to one 68k function, and call this
  276. function right after the Chunky-Copy, to reduce the number of
  277. Contextswitches per loop to *1*. This is optional code, you still
  278. can set the Hook-Parameter to 0.
  279.  
  280. Yes, i said before that Hooks are not possible for PPC. They
  281. are possible, but only with a MixedBinary like chunkyppc.library.
  282. To generate the 68k functions for the Hook you can do:
  283.  
  284. - Create a 68k Shared Library containing the 68k function
  285. - or using a MixedBinary
  286.  
  287. I don't know which one Hyperion will be using. But generally i advice
  288. people to use a library to avoid MixedBinaries.
  289.  
  290. There is an example about the MixedBinary feature consisting of the
  291. two files test_new.c and test_new_68k.c. I fear, though, that it will
  292. only compile with StormC, as it uses the "Automatic Contextswitch"
  293. feature of StormC. You could also create the "myhook" function inside
  294. a Custom 68k Shared library of course.
  295.  
  296. --- snap ---
  297.  
  298. Well, why another Chunky-Library ? We have rtgmaster, after all...
  299.  
  300. Well, rtgmaster has one BIG BIG function for chunky-copy. Sometimes if
  301. you know a certain special-case exists, you can specifically optimize
  302. for this special-case and get some extra speed out of it. The disadvantage
  303. is of course that you now have TONS of different chunky-copy-functions,
  304. and get confused about which of them is which :)
  305.  
  306. Well, anyways: the chunkyppc.library works with rtgmaster (Just use
  307.  
  308. GetBufAdr(RtgScreen,0)
  309.  
  310. as Screenaddress
  311.  
  312. ), it works with CGX, it works with Picasso96. It works with AGA. It works
  313. with ECS.
  314.  
  315. It also contains all my experience in the field of GFX Board Coding.
  316.  
  317. chunkyppc.library exists in two forms:
  318.  
  319. chunkyppc.library is a PPC Shared Library for WarpUP (for newer versions of
  320. StormC and for vbcc-WarpUP the linker-lib chunkyppc.lib is provided, for
  321. older versions of StormC and for EGCS-WarpUP Includes are provided, which
  322. serve the same thing).
  323.  
  324. linkchunkyppc.lib is a Linker Lib without Shared Library which serves the same
  325. purpose, and supports the same functions. It cannot be used with EGCS WarpUP,
  326. though, as EGCS WarpUP does not support vbcc-WarpUP-Style linkerlibs, like the
  327. other two compilers... for EGCS WarpUP you have to use the PPC Shared Library.
  328.  
  329. The functions:
  330.  
  331. ChunkyNoffFast
  332. ChunkyNoffFastest
  333. ChunkyNoffNormal
  334.  
  335. Chunky-Copy with no destination offset and no source offset. Useful for
  336. Fullscreen-Copy. Fastest assumes the width divisible by 64, Fast divisible
  337. by 8, and Normal does not assume anything. Of course the more limited the faster...
  338.  
  339. ChunkyFast
  340. ChunkyFastest
  341. ChunkyNormal
  342.  
  343. The same like above, only now with Destination Offset Added.
  344.  
  345. ChunkyFastFull
  346. ChunkyFastestFull
  347. ChunkyNormalFull
  348.  
  349. Now both sorts of Offset (Source+Destination) are supported. Note, that because
  350. some compilers - EGCS WarpUP in special - don't like many parameters for PPC
  351. Shared Libs, i stuffed some parameters together into a
  352.  
  353. struct Soff
  354. {
  355.  int x,y;
  356. };
  357.  
  358. for this ... some of the future functions use this too... should be easy to
  359. understand :)
  360.  
  361. All Chunky-Copy functions are 100% highly optimized PPC ASM. I *really* spent
  362. time to optimize them best. Some of the c2p are only C (c2p_1 and c2p_2 are
  363. PPC ASM). I guess c2p_1 is the fastest, then c2p_2, then c2p_3, then c2p_4,
  364. but never really tested it...
  365.  
  366. Names in the fd-file:
  367.  
  368. address = Destination Address
  369. data    = Source Address
  370. w       = Width of the Blit
  371. h       = Height of the Blit
  372. bpr     = Destination BytesPerRow
  373. x       = Destination X Offset
  374. y       = Destination Y Offset
  375. soff    = Source Offset (struct Soff *)
  376. sbpr    = Source BytesPerRow
  377. buffer  = Destination Address
  378. width   = Width of the Blit
  379. height  = Height of the Blit
  380. bm      = struct BitMap * of the Screen
  381. dest    = Destination Offset (struct Soff *)
  382. size    = Width/Height of the Blit (struct Soff *)
  383. plane0  = bm->Planes[0]
  384. bitplanes = bm->Planes[0]
  385. chunkyx  = Width of the Blit
  386. chunkyy  = Height of the Blit
  387. bitplanesize = (width*height)/8
  388. depth    = 6 or 8
  389. helpbfr  = width*height sized FastRAM Buffer
  390. temp     = width*height sized FastRAM Buffer
  391. screensize = Size of the Screen (struct Soff *)
  392.  
  393. In the future there will be 15-24 Bit support, even with Byteswapping,
  394. HAM8 Support and Masking Support.
  395.  
  396. There won't be a 68k Version. It would be too much work for my lazy self
  397. to transform all that PPC ASM Code to 68k :)
  398.  
  399. Note: In the meanwhile there are also functions for:
  400.  
  401. 16 BIT
  402. 16 BIT with Byteswapper
  403. 16 Bit with RGB<->BGR change
  404. 24 Bit
  405. 32 Bit
  406.  
  407. 16 Bit with Swapper AND rotater still has to be done, as quite a lot of
  408. possible 24/32 Bit changers. Also 16-24 Bit are currently only available
  409. in the "normal" versions. ROT(RGB<->BGR) is completely untested.
  410. For 15 Bit the 16 Bit functions can be used.
  411.  
  412. Who does write me docs ? :)
  413.  
  414. Look at the includes for the new functions for 16-24 Bit :)
  415.  
  416. Steffen Haeuser
  417.