docs for video

[sdlgit/SDL-Site.git] / pages / SDL-Video.html-inc

diff --git a/pages/SDL-Video.html-inc b/pages/SDL-Video.html-inc
index 24a3f59..56f9900 100644 (file)
--- a/pages/SDL-Video.html-inc
+++ b/pages/SDL-Video.html-inc
@@ -58,7 +58,7 @@
 </ul>
 </li>
 </ul><hr />
-<!-- INDEX END -->
+<!-- INDEX END --><a href="assets/Video.png" target="_blank"><img src="assets/Video.png" style="height: 160px" alt="Video.png"/></a><hr />
 
 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
 <div id="NAME_CONTENT">
@@ -558,24 +558,91 @@ SDL::get_gamma_ramp returns -1 on error.</p>
 </div>
 <h2 id="set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</h2>
 <div id="set_gamma_ramp_rt_gt_bt_CONTENT">
-<p>Sets the gamma lookup tables for the display for each color component. Each table is an array of 256 Uint16 values, representing a 
+<pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
+
+</pre>
+<p>Sets the gamma lookup tables for the display for each color component. Each table is an array ref of 256 Uint16 values, representing a 
 mapping between the input and output for that channel.
 The input is the index into the array, and the output is the 16-bit gamma value at that index, scaled to the output color precision. 
 You may pass NULL to any of the channels to leave them unchanged.</p>
 <p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a &quot;gamma function&quot; parameter 
-with SDL::set_gamma.</p>
+with <code>SDL::Video::set_gamma</code>.</p>
 <p>Not all display hardware is able to change gamma. 
-SDL::set_gamma_ramp returns -1 on error.</p>
+<code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my (@red, @green, @blue);
+
+ my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
+
+ $red[127] = 0xFF00;
+
+    $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
+
+    $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
+
+ if( -1 == $ret )
+ {
+     print( &quot;an error occoured&quot; );
+ }
+ else
+ {
+     printf( &quot;for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[255], $green[255], $blue[255] );
+     printf( &quot;for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[127], $green[127], $blue[127] );
+     printf( &quot;for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[0],   $green[0],   $blue[0]   );
+ }
+
+ SDL::quit();
+
+</pre>
 
 </div>
 <h2 id="map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</h2>
 <div id="map_RGB_pixel_format_r_g_b_CONTENT">
-<p>Maps the RGB color value to the specified SDL::pixel_format and returns the pixel value as a 32-bit int.
+<pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
+
+</pre>
+<p>Maps the RGB color value to the specified <a href="/SDL-PixelFormat.html">SDL::PixelFormat</a> and returns the pixel value as a 32-bit int.
 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
 If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
-<p>SDL::map_RGP returns a pixel value best approximating the given RGB color value for a given pixel format.
-If the SDL::pixel_format's  bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored 
+<p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
+If the <a href="/SDL-PixelFormat.html">SDL::PixelFormat</a>'s  bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored 
 (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::PixelFormat;
+ use SDL::Surface;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
+ #                                                          ^-- 16 bits per pixel
+
+ $r = 0x9C;
+ $g = 0xDC;
+ $b = 0x67;
+
+ printf( &quot;for 24bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b);
+
+ my $_16bit = SDL::Video::map_RGB( $screen_surface-&gt;format, $r, $g, $b );
+
+ # 16bpp is 5 bits red, 6 bits green and 5 bits blue
+ # we will obtain the values for each color and calculating them back to 24bit color system
+ $r = (($_16bit &amp; 0b1111100000000000) &gt;&gt; 11) / 0b11111  * 0b11111111;
+ $g = (($_16bit &amp; 0b0000011111100000) &gt;&gt;  5) / 0b111111 * 0b11111111;
+ $b =  ($_16bit &amp; 0b0000000000011111)        / 0b11111  * 0b11111111;
+
+ printf( &quot;for 16bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b );
+
+ # so color #9CDC67 becomes #9CDE62
+
+ SDL::quit();
+
+</pre>
 
 </div>
 <h2 id="map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</h2>