home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1996 / ARCHIVE_96.iso / discs / mag_discs / volume_8 / issue_06 / risc_os / ColourTran < prev    next >
Text File  |  1988-10-03  |  6KB  |  175 lines
  1. The ColourTrans Module
  2. ======================
  3.  
  4. This module is not part of the ROM, but is in !system.modules.colours
  5. in the Welcome Suite. It provides generally useful functionality,
  6. and so it is documented as part of RISC OS.
  7.  
  8. Throughout, a mode of -1 means the current mode, and a palette pointer of
  9. 0 means the default palette (i.e. the palette set by the MOS on entry to
  10. the specified mode).
  11. -1 as a palette pointer refers to the current palette; this is generally only
  12. sensible if -1 is specified for the mode.
  13.  
  14. "Palette pointer" (from here on just "palette") means a pointer to a list of
  15. words, containing BBGGRRxx. In 256 colour modes only the first 16 of these
  16. are be referenced, real colours being built from there.
  17.  
  18. When the destination is a 256 colour mode, "GCOL" means a byte with the
  19. real GCOL in bits 2-7, and the tint in bits 0 & 1.
  20.  
  21. "Colour number" is used to refer to the byte that's placed into screen memory;
  22. identical to the GCOL except for 256 colour modes.
  23.  
  24. "Most different" means "maximises the distance function"; "closest" means
  25. "minimises the distance function". The distance function is a weighted
  26. least squares, i.e.
  27.    where colours are (Rs, Gs, Bs) and (Rd, Gd, Bd)
  28.  
  29.     distance =   redweight*(Rs-Rd)^2 +
  30.                greenweight*(Gs-Gd)^2 +
  31.                 blueweight*(Bs-Bd)^2.
  32.  
  33. Currently, blueweight = 1, redweight = 2, greenweight = 3; this seems to give
  34. acceptable results on the limited problem we are tackling.
  35.  
  36. SWIs:
  37. =====
  38.  
  39. ColourTrans_SelectTable (&40740)
  40. --------------------------------
  41.  
  42. Given a source mode & palette, and destination mode & palette, and a buffer,
  43. set up a translation table in the buffer. ("Translation table" means a set
  44. of colour numbers as used by the scaled sprite plotting).
  45.  
  46. and ColourTrans_SelectGCOLTable (&40741)
  47.     ------------------------------------
  48.  
  49. Given a source mode & palette, and destination mode & palette, and a buffer,
  50. set up a list of GCOLs in the buffer.
  51.  
  52. For both the above:
  53. Input:  r0 = source mode
  54.         r1 = source palette
  55.         r2 = destination mode
  56.         r3 = destination palette
  57.         r4 = buffer (assumed to be long enough,
  58.                      i.e. no_of_colours(source mode) bytes long)
  59.  
  60.  
  61.  
  62. ColourTrans_ReturnGCOL (&40742)
  63. -------------------------------
  64.  
  65. Given a palette entry (BBGGRRxx), return the closest GCOL in the current mode
  66. and palette.
  67.  
  68. Input:  r0 = palette entry
  69. Output: r0 = GCOL
  70.  
  71. ColourTrans_SetGCOL (&40743)
  72. ----------------------------
  73.  
  74. Given a palette entry, return the closest GCOL in the current mode and palette,
  75. and also set the GCOL.
  76.  
  77. Input:  r0 = palette entry
  78.         r3 = 0 or 128 for fore/background
  79.         r4 = GCOL action
  80.              Both r3 and r4 should have the top three bytes clear, to allow
  81.              for future expansion.
  82. Output: r0 = GCOL
  83.  
  84.  
  85. ColourTrans_ReturnColourNumber (&40744)
  86. ---------------------------------------
  87.  
  88. Given a palette entry (BBGGRRxx), return the closest colour number in the
  89. current mode and palette.
  90.  
  91. Input:  r0 = palette entry
  92. Output: r0 = colour number
  93.  
  94. ColourTrans_ReturnGCOLForMode (&40745)
  95. --------------------------------------
  96.  
  97. Given a palette entry, a destination mode and palette, return the closest GCOL.
  98.  
  99. Input:  r0 = palette entry
  100.         r1 = destination mode
  101.         r2 = destination palette
  102. Output: r0 = GCOL
  103.  
  104. ColourTrans_ReturnColourNumberForMode (&40746)
  105. ----------------------------------------------
  106.  
  107. Given a palette entry, a destination mode and palette, return the closest
  108. colour number.
  109.  
  110. Input:  r0 = palette entry
  111.         r1 = destination mode
  112.         r2 = destination palette
  113. Output: r0 = colour number
  114.  
  115.  
  116. ColourTrans_ReturnOppGCOL (&40747)
  117. ----------------------------------
  118. ColourTrans_SetOppGCOL (&40748)
  119. -------------------------------
  120. ColourTrans_ReturnOppColourNumber (&40749)
  121. ------------------------------------------
  122. ColourTrans_ReturnOppGCOLForMode (&4074A)
  123. -----------------------------------------
  124. ColourTrans_ReturnOppColourNumberForMode (&4074B)
  125. -------------------------------------------------
  126.  
  127. Parameters are exactly the same as 40742-40746; action is very similar,
  128. but the furthest rather than closest colour is returned.
  129.  
  130.  
  131. ColourTrans_GCOLToColourNumber (&4074C)
  132. ---------------------------------------
  133.  
  134. Translate a GCOL to a colour number (assuming a 256 colour mode is meant).
  135. Input:  r0 = GCOL
  136. Output: r0 = colour number
  137.  
  138. ColourTrans_ColourNumberToGCOL (&4074D)
  139. ---------------------------------------
  140.  
  141. Translate a colour number to a GCOL (assuming a 256 colour mode is meant).
  142. Input:  r0 = colour number
  143. Output: r0 = GCOL
  144.  
  145.  
  146. ColourTrans_ReturnFontColours (&4074E)
  147. -------------------------------------
  148. ColourTrans_SetFontColours (&4074F)
  149. ----------------------------------
  150.  
  151. Input:  r0 = font handle
  152.         r1 = background palette entry
  153.         r2 = foreground palette entry
  154.         r3 = max offset
  155.  
  156. Output: r0-r3 as passed to Font_SetFontColour
  157.  
  158. This returns font colours to match the given colours; the closest
  159. approximation to the foreground and background will be set, and as many
  160. intermediate colours (up to the specified maximum) as can be done.
  161.  
  162. ColourTrans_SetFontColours also calls Font_SetFontColours.
  163.  
  164. Note: in 256 colour modes, only 16 font colours can be set up before
  165. previously returned information becomes invalid. Therefore, if using
  166. ReturnFontColours to obtain information to insert in a string to pass to the
  167. font painter, do not allow more than 16 distinct colours in the string.
  168.  
  169. ColourTrans_InvalidateCache (&40750)
  170. ------------------------------------
  171.  
  172. This call must be issued whenever the palette has changed since ColourTrans
  173. was last called. Note that palette changes due to mode change are detected
  174. by the module.
  175.