Added the rgb_15_from_24() and rgb_15_from_f() helper functions

docs/vwf/manual/index.xhtml

@@ -227,6 +227,8 @@
 
 								<details><summary><a href="#helper-functions-colors">Colors</a></summary><ul>
 									<li><a href="#helper-functions-rgb_15"><code>rgb_15()</code></a></li>
+									<li><a href="#helper-functions-rgb_15_from_24"><code>rgb_15_from_24()</code></a></li>
+									<li><a href="#helper-functions-rgb_15_from_f"><code>rgb_15_from_f()</code></a></li>
 									<li><a href="#helper-functions-vwf_get_color_index_2bpp"><code>vwf_get_color_index_2bpp()</code></a></li>
 								</ul></details>
 
@@ -2049,6 +2051,44 @@ ExitToOwMode = VWF_ExitToOwMode</code></pre></td>
 					Defines a 16-bit color value in RGB15 format by separately specifying the values for the <code>red</code>, <code>green</code> and <code>blue</code> color channels.
 				</p></dd>
 
+				<dt id="helper-functions-rgb_15_from_24"><code>rgb_15_from_24()</code></dt>
+				<dd><p>
+					<table class="api-documentation">
+						<tr>
+							<th>Usage</th>
+							<td><pre><code class="65c816_asar">rgb_15_from_24(r, g, b)</code></pre></td>
+						</tr>
+						<tr>
+							<th>Parameters</th>
+							<td><ul class="parameter-list">
+								<li><code>r: number:</code> The value of the <code>red</code> color channel. (min: <code>0</code>, max: <code>255</code>)</li>
+								<li><code>g: number:</code> The value of the <code>green</code> color channel. (min: <code>0</code>, max: <code>255</code>)</li>
+								<li><code>b: number:</code> The value of the <code>blue</code> color channel. (min: <code>0</code>, max: <code>255</code>)</li>
+							</ul></td>
+						</tr>
+					</table>
+					Defines a 16-bit color value in RGB15 format by separately specifying the values for the <code>red</code>, <code>green</code> and <code>blue</code> color channels as 8-bit values. This is useful since RGB24 (which uses 8-bit color channels) is the most common color format around today, so you can easily take color values from existing apps (like Microsoft Paint) and copy them directly into the patch. Note that not all RGB24 color values are expressible in RGB15, so in a lot of cases, the function will pick the closest matching color.
+				</p></dd>
+
+				<dt id="helper-functions-rgb_15_from_f"><code>rgb_15_from_f()</code></dt>
+				<dd><p>
+					<table class="api-documentation">
+						<tr>
+							<th>Usage</th>
+							<td><pre><code class="65c816_asar">rgb_15_from_f(r, g, b)</code></pre></td>
+						</tr>
+						<tr>
+							<th>Parameters</th>
+							<td><ul class="parameter-list">
+								<li><code>r: number:</code> The value of the <code>red</code> color channel. (min: <code>0.0</code>, max: <code>1.0</code>)</li>
+								<li><code>g: number:</code> The value of the <code>green</code> color channel. (min: <code>0.0</code>, max: <code>1.0</code>)</li>
+								<li><code>b: number:</code> The value of the <code>blue</code> color channel. (min: <code>0.0</code>, max: <code>1.0</code>)</li>
+							</ul></td>
+						</tr>
+					</table>
+					Defines a 16-bit color value in RGB15 format by separately specifying the values for the <code>red</code>, <code>green</code> and <code>blue</code> color channels as decimal values. This is useful in cases where you want to express color channels as a percentage. The function will pick the closest matching color expressible in RGB15 for the given color channel values.
+				</p></dd>
+
 				<dt id="helper-functions-vwf_get_color_index_2bpp"><code>vwf_get_color_index_2bpp()</code></dt>
 				<dd><p>
 					<table class="api-documentation">
@@ -2611,6 +2651,7 @@ endif</code></pre>
 						<li>The maximum value for the <code>VWF_AutoWait.WaitFrames</code> auto-wait mode has been extended from <code>254</code> to <code>255</code>.</li>
 						<li>Simplified many multiplications in the patch. For most of them, this slightly boosts performance. More importantly, this removes any dependency on the mode 7 registers for multiplication, which avoids a potential rare bug that could be caused by HDMA.</li>
 						<li>Text box properties (background pattern, background color and frame) can now be overridden by message headers. This functionality is available via the <a href="#header-settings-vwf_text_box_bg_pattern"><code>vwf_text_box_bg_pattern()</code></a>, <a href="#header-settings-vwf_text_box_bg_color"><code>vwf_text_box_bg_color()</code></a> and <a href="#header-settings-vwf_text_box_frame"><code>vwf_text_box_frame()</code></a> header settings.</li>
+						<li>Added the <a href="#helper-functions-rgb_15_from_24"><code>rgb_15_from_24()</code></a> and <a href="#helper-functions-rgb_15_from_f"><code>rgb_15_from_f()</code></a> helper functions.</li>
 					</ul>
 				</p></dd>
 

patches/shared/shared.asm

@@ -580,7 +580,37 @@ endmacro
 
 ; Misc color functions
 
+; Private section
+
+{
+	; Converts an 8-bit color channel to a 5-bit color channel.
+	; Requires math rounding mode to be off.
+
+	function rs_8_bit_to_5_bit_color(channel_value) = round((channel_value/255)*31, 0)&%11111
+	
+	
+	; Converts a float color channel to a 5-bit color channel.
+	; Requires math rounding mode to be off.
+
+	function rs_f_to_5_bit_color(channel_value) = round(channel_value*31, 0)&%11111
+}
+
+
+
+; Public section
 
 ; Creates an RGB15 16-bit value from the three different colors channels. Each channel value can be in the range of 0 to 31.
 
 function rgb_15(red, green, blue) = (red&%11111)|((green&%11111)<<5)|((blue&%11111)<<10)
+
+
+; Creates an RGB15 16-bit value from the three different color channels comprising an RGB24 24-bit color value.
+; Each channel value can be in the range of 0 to 255. For color values not representable as RGB15, the closest match is used.
+
+function rgb_15_from_24(red, green, blue) = rs_8_bit_to_5_bit_color(red)|(rs_8_bit_to_5_bit_color(green)<<5)|(rs_8_bit_to_5_bit_color(blue)<<10)
+
+
+; Creates an RGB15 16-bit value from the three different color channels expressed as decimal percentages.
+; Each channel value can be in the range of 0.0 to 1.0. For color values not representable as RGB15, the closest match is used.
+
+function rgb_15_from_f(red, green, blue) = rs_f_to_5_bit_color(red)|(rs_f_to_5_bit_color(green)<<5)|(rs_f_to_5_bit_color(blue)<<10)

patches/vwf_dialogues/data/testing/data/vwfmessages.asm

@@ -2084,7 +2084,7 @@ BufferOverflowTest:
 
 %vwf_message_start(0063)	; Message 10D-2
 
-	%vwf_header(text_box_bg_color(rgb_15(15, 0, 0)))
+	%vwf_header(text_box_bg_color(rgb_15_from_24(128, 0, 0)))
 
 	!str("This text box overrides the text box color.") : !press_button
 	!display_message(0064)
@@ -2106,7 +2106,7 @@ BufferOverflowTest:
 
 %vwf_message_start(0065)	; Message 10E-2
 
-	%vwf_header(text_box_bg_pattern($05), text_box_bg_color(rgb_15(0, 15, 0)), text_box_frame($02))
+	%vwf_header(text_box_bg_pattern($05), text_box_bg_color(rgb_15_from_f(0.0, 0.5, 0.0)), text_box_frame($02))
 
 	!str("This text box overrides all three text box properties.") : !press_button
 	!display_message(0050)