From bf84dde8f6903e93bf76a95fbd9f1fd9521ba87d Mon Sep 17 00:00:00 2001 From: PipStuart Date: Mon, 28 Mar 2011 16:06:09 -0500 Subject: [PATCH] B3SFu8Q: Fixed all instances of R*B*G to R*G*B; tidied up language, alignment, and formatting for entire document. --- src/02-drawing.pod | 211 +++++++++++++++++++++++---------------------- 1 file changed, 108 insertions(+), 103 deletions(-) diff --git a/src/02-drawing.pod b/src/02-drawing.pod index 4029b6a..cc327c7 100644 --- a/src/02-drawing.pod +++ b/src/02-drawing.pod @@ -3,28 +3,31 @@ =head1 Preview -SDL provides several ways to draw graphical elements on the screen; these methods can be broken down into three general categories: Primitives, Images and Text. -Methods in each of the three categories draw a single object on the Surface. The Surface is represented by C. Even our -C is a C. This means that we can draw directly on the C, however there are -several advantages to drawing on multiple surfaces. In this chapter we will explore these methods of drawing, and -make a pretty picture. +SDL provides several ways to draw graphical elements on the screen; these +methods can be broken down into three general categories: Primitives, Images, +and Text. +Methods in each of the three categories draw a single object on the Surface. +The Surface is represented by C. Even our C is an +C. This means that we can draw directly on the C, +however there are several advantages to drawing on multiple surfaces. In this +chapter we will explore these methods of drawing, and make a pretty picture. =head1 Coordinates -SDL surfaces coordinate system has x=0, y=0 in the upper left corner and work downward and to the right. The API always lists coordinates in x,y order. +SDL's surface coordinate system has x=0,y=0 in the upper left corner and the +dimensions span to the right and downward. The API always lists coordinates in +x,y order. More discussion of these details can be found in the SDL library documentation: U -=head1 Objective - -Using SDL we will try to construct the following image. - -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/flower.png} - \caption{A field of flowers} - \label{fig:flowers} +=head1 Objective +Using SDL we will try to construct the following image. +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/flower.png} + \caption{A field of flowers} + \label{fig:flowers} =head1 Drawing the Flower @@ -32,30 +35,37 @@ To begin actually drawing the flower, we need to cover some theory. =head2 Syntax Overview -Drawing in SDL are done on Surfaces. The C object provides access to methods in the form of: +Drawing in SDL is done on Surfaces. The C object provides +access to methods in the form of: $surface->draw_{something}( .... ); -Parameters are usually provided as array references, to define areas and colors. +Parameters are usually provided as array references, to define areas and +colors. =head3 Rectangular Parameters -Some parameters are just a quick definition of the positions and dimensions. For a rectangle that will be placed at C<(20, 20)> pixel units on the screen, and a dimension of C<40x40> pixel units the following would suffice. +Some parameters are just a quick definition of the positions and dimensions. +For a rectangle that will be placed at C<(20, 20)> pixel units on the screen, +which has dimensions of C<40x40> pixel units, the following would suffice. my $rect = [20, 20, 40, 40]; =head3 Color -X in SDL is described by 4 numbers. The first three numbers define the Red, Blue, Green intensity of the color. The final number defines the transparency of the Color. +X in SDL is described by 4 numbers. The first three numbers define the +Red, Green, and Blue intensity of the Color. The final number defines the +transparency of the Color. my $color = [255, 255, 255, 255]; - + Color can also be defined as hexadecimal values: my $color = 0xFFFFFFFF; The values of the numbers range from 0-255 for 32 bit depth in RGBA format. -Alternately color can be described as a 4 byte hexadecimal value, each two digit byte encoding the same RGBA vaues as above: +Alternately color can be described as a 4 byte hexadecimal value, each two +digit byte encoding the same RGBA values as above: my $goldenrod = 0xDAA520FF; @@ -63,86 +73,90 @@ Alternately color can be described as a 4 byte hexadecimal value, each two digit =head4 NOTE: Depth of Surface -The bits of the surface are set when the C or C is made. +The bits of the surface are set when the C or C is +made. - my $app = SDLx::App->new( depth => 32 ); + my $app = SDLx::App->new( depth => 32 ); -Other options are 24,16 and 8. 32 is the default bit depth. +Other options are 24, 16, and 8. 32 is the default bit depth. =end sidebar -=head2 Pixels +=head2 Pixels -All Cs are made of pixels that can be read and written to via a tied array interface. +All Cs are made of pixels that can be read and written to via +a tied array interface. $app->[$x][$y] = $color; -The C<$color> is defined as an unsigned integer value which is construct in the following format, C<0xRRBBGGAA>. -This is a hexadecimal number. Here are some examples: +The C<$color> is defined as an unsigned integer value which is constructed in +the following hexadecimal format, C<0xRRGGBBAA>. +Here are some examples: $white = 0xFFFFFFFF; $black = 0x000000FF; $red = 0xFF0000FF; - $blue = 0x00FF00FF; - $green = 0x0000FFFF; + $green = 0x00FF00FF; + $blue = 0x0000FFFF; -Pixels can also be defined as anonymous arrays as before C<[$red, $blue, $green, $alpha]>. +Pixels can also be defined as anonymous arrays as before with +C<[$red, $green, $blue, $alpha]>. =head2 Primitives -Drawing X are usually simples shapes that can be used for creating graphics dynamically. +Drawing X are usually simple shapes that can be used for creating +graphics dynamically. -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/draw-1.png} - \caption{Drawing a line} - \label{fig:draw_line} +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/draw-1.png} + \caption{Drawing a line} + \label{fig:draw_line} =head3 Lines $app->draw_line( [200,20], [20,200], [255, 255, 0, 255] ); -This will draw a yellow line from positions C< (200,20) > to C< (20,200) >. +This will draw a yellow line from positions C<(200,20)> to C<(20,200)>. -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/draw-2.png} - \caption{Drawing a Rectangle} - \label{fig:draw_rect} +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/draw-2.png} + \caption{Drawing a Rectangle} + \label{fig:draw_rect} =head3 Rectangles -Rectangles are a common building blocks for games. In SDL, rectangles are the most cost effective of the primitives to draw. +Rectangles are a common building block for games. In SDL, rectangles are the most cost effective of the primitives to draw. $app->draw_rect( [10,20, 40, 40 ], [255, 255, 255,255] ); -The above will add a white square of size C<40x40> onto the screen at the position C<(10,20)>. +The above will add a white square of size C<40x40> onto the screen at the position C<(10,20)>. -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/draw-3.png} - \caption{Drawing a Circle} +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/draw-3.png} + \caption{Drawing a Circle} \label{fig:draw_circle} -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/draw-4.png} - \caption{Drawing a filled Circle} +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/draw-4.png} + \caption{Drawing a filled Circle} \label{fig:draw_filled_circle} - =head3 Circles Circles are drawn similarly either filled or unfilled. - $app->draw_circle( [100,100], 20, [255,0,0,255] ); + $app->draw_circle( [100,100], 20, [255,0,0,255] ); $app->draw_circle_filled( [100,100], 19, [0,0,255,255] ); -Now we will have a filled circle, colored blue and unfilled circle, colored as red. +Now we will have an unfilled circle colored red and a filled circle colored blue. =head3 More Primitives -For more complex drawing functions have a look at C. +For more complex drawing functions have a look at C. =head2 Application: Primitives -Using our knowledge of Primitives in SDL, lets draw our field, sky and a simple flower. +Using our knowledge of Primitives in SDL, let's draw our field, sky, and a simple flower. =begin programlisting @@ -159,23 +173,23 @@ Using our knowledge of Primitives in SDL, lets draw our field, sky and a simple ); #Adding the blue skies - $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); + $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); #Draw our green field - $app->draw_rect( [ 0, 400, 500, 100 ], [ 50, 170, 20, 100 ] ); + $app->draw_rect( [ 0, 400, 500, 100 ], [ 50, 170, 20, 100 ] ); # Make a surface 50x100 pixels my $flower = SDLx::Surface->new( width => 50, height => 100 ); # Lets make the background black - $flower->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); + $flower->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); # Now for a pretty green stem - $flower->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); + $flower->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); # And the simple flower bud $flower->draw_circle_filled( [ 25, 25 ], 10, [ 150, 0, 0, 255 ] ); - $flower->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); + $flower->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); # Draw flower on $app surface $flower->blit( $app, [ 0, 0, 50, 100 ] ); @@ -186,55 +200,53 @@ Using our knowledge of Primitives in SDL, lets draw our field, sky and a simple =end programlisting -=for figure - \includegraphics[width=0.5\textwidth]{../src/images/flower-1.png} - \caption{Looks so lonely there all alone} +=for figure + \includegraphics[width=0.5\textwidth]{../src/images/flower-1.png} + \caption{Looks so lonely there all alone} \label{fig:draw_flower_lone} - - =head1 Drawing a Field of Flowers =head2 Multiple Surfaces -So far we have been drawing only on one surface, the display. In SDL it is possible to write on -several surfaces that are in memory. These surfaces can later on be added on to the display to -show them. The Surface is defined as a C type in SDL Perl. +So far we have been drawing only on one surface, the display. In SDL it is possible to write on +several surfaces that are in memory. These surfaces can later on be added on to the display to +show them. The Surface is defined as an C type in SDL Perl. =head3 Creating Surfaces -There are several ways to create C for use. +There are several ways to create an C for use. =head3 Raw Surfaces -For the purposes of preparing surfaces using only draw functions ( as mentioned above ) +For the purposes of preparing surfaces using only draw functions (as mentioned above) we can create a surface using the C's constructor. $surface = SDLx::Surface->new( width => $width, height => $height ); =head3 Images in SDL -Using C and C we can load images as surfaces too. +Using C and C we can load images as surfaces too. C provides support for all types of images, however it requires -C library support to be compiled with the right library. +C library support to be compiled with the right library. $surface = SDL::Image::load( 'picture.png' ); -In case the C library is unavailable we can use the build in support -for the C<.bmp> format. +In the event that the desired C library is unavailable, we can +fall-back on the built-in support for the C<.bmp> format. $surface = SDL::Video::load_BMP( 'picture.bmp' ); -Generally however the C module is used. +Generally, however, the C module is used. =head1 Lots of Flowers but One Seed =head2 Sprites -You might have noticed that putting another C on the C<$app> requires the usage -of a C function, which may not clarify as to what is going on there. Fortunately a C -can be used to make our flower. Besides making drawing simpler, C adds several other features -that we need for game images that move a lot. For now lets use C for our flowers. +You might have noticed that putting another C on the C<$app> requires the usage +of a C function, which may not clarify as to what is going on there. Fortunately an C +can be used to make our flower. Besides making drawing simpler, C adds several other features +that we need for game images that move a lot. For now let's use C for our flowers. =begin programlisting @@ -252,7 +264,7 @@ that we need for game images that move a lot. For now lets use C f ); #Adding the blue skies - $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); + $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); #Draw our green field $app->draw_rect( [ 0, 400, 500, 100 ], [ 50, 170, 20, 100 ] ); @@ -262,14 +274,14 @@ that we need for game images that move a lot. For now lets use C f # To access the SDLx::Surface to write to, we use the ->surface() method # Let's make the background black - $flower->surface->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); + $flower->surface->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); # Now for a pretty green stem - $flower->surface->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); + $flower->surface->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); # And the simple flower bud $flower->surface->draw_circle_filled( [ 25, 25 ], 10, [ 150, 0, 0, 255 ] ); - $flower->surface->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); + $flower->surface->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); $flower->draw_xy( $app, 0, 0 ); @@ -279,24 +291,23 @@ that we need for game images that move a lot. For now lets use C f =end programlisting -Obviously at this point we don't want our single flower floating in the sky, so we will draw several of them -on the ground. Delete everything from line 34 including and after +Obviously at this point we don't want our single flower floating in the sky, so we will draw several of them +on the ground. Delete everything from line 34 including and after - $flower->draw_xy($app, 0,0) + $flower->draw_xy( $app, 0, 0 ); -and insert the below code to get a field of flowers. +and insert the code below to get a field of flowers. =begin programlisting - foreach( 0..500 ) - { - my $y = 425 - rand( 50 ); - $flower->draw_xy( $app, rand(500)-20, $y ); + for(0..500){ + my $y = 425 - rand( 50); + $flower->draw_xy( $app, rand(500)-20, $y ); } $app->update(); - sleep(1); + sleep(1); =end programlisting @@ -318,25 +329,21 @@ The final program looks like this: ); # Draw Code Starts here - my $flower = SDLx::Sprite->new( width => 50, height => 100 ); - $flower->surface->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); - - $flower->surface->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); + $flower->surface->draw_rect( [ 0, 0, 50, 100 ], [ 0, 0, 0, 0 ] ); + $flower->surface->draw_rect( [ 23, 30, 4, 100 ], [ 0, 255, 0, 255 ] ); $flower->surface->draw_circle_filled( [ 25, 25 ], 10, [ 150, 0, 0, 255 ] ); - $flower->surface->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); + $flower->surface->draw_circle( [ 25, 25 ], 10, [ 255, 0, 0, 255 ] ); $flower->alpha_key(0); - $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); - - $app->draw_rect( [ 0, 400, 500, 100 ], [ 50, 170, 20, 100 ] ); + $app->draw_rect( [ 0, 0, 500, 500 ], [ 20, 50, 170, 255 ] ); + $app->draw_rect( [ 0, 400, 500, 100 ], [ 50, 170, 20, 100 ] ); - foreach ( 0 .. 500 ) { - my $y = 425 - rand(50); + for(0..500){ + my $y = 425 - rand( 50); $flower->draw_xy( $app, rand(500) - 20, $y ); } - #Draw Code Ends Here $app->update(); @@ -345,6 +352,4 @@ The final program looks like this: =end programlisting - - =for vim: spell