Locking and Unlocking Buffers

[ LiB ]

Locking and Unlocking Buffers

This chapter is going to exhaust all the possibilities of what we can do with buffers. We've pretty much gotten it all, except for locking and unlocking buffers. Locking a buffer refers to a function that makes the buffer unavailable for use to other parts of a program. It may seem bad to restrict access to a buffer, but locking has a big benefitit allows you to use the following special functions:

? ReadPixel()
? WritePixel
ReadPixelFast()
WritePixelFast
CopyPixelFast
CopyPixel

Using these functions, you can edit and copy any pixels in your buffers. So, let's get started.

Lock/Unlock

Lock and Unlock are declared like this:

LockBuffer buffer
UnlockBuffer buffer

Table 6.6. describes their parameter.

Table 6.6. Lock/Unlock's Parameter

Parameter	Description
`buffer`	The name of the buffer you wish to lock or unlock to perform high-speed pixel operations

Well, using these functions makes the buffers unavailable for most uses. The operations it opens up, though, are high-speed pixel operations that allow copying and editing of pixels throughout your buffers. Using LockBuffer and UnlockBuffer often looks like this.

;Time to Lock buffer
LockBuffer BackBuffer()


;Perform Pixel operations


UnlockBuffer BackBuffer()

Okay, that's pretty much it on how to lock and unlock buffers. Let's move on to the actual commands.

NOTE

Did you notice that I used BackBuffer() for the locked buffer? You may wonder why I chose to lock the back buffer instead of the front buffer. If I were to choose the front buffer, there would be a huge slowdown while producing the pixel effects (not that there were any in the previous example). Also, actually including BackBuffer() is not really necessary. If the buffer variable is omitted, the locked buffer is set to be the default buffer, designated by the SetBuffer command (not shown, but assumed to be SetBuffer BackBuffer() ).

ReadPixel()/ReadPixelFast()

ReadPixel () and ReadPixelFast () are the first functions that you need to know to work with pixel editing. These functions read in the values for each individual pixel. Usually, you will use an array to keep track of these values.

NOTE

Refresher : Arrays

Remember arrays? Arrays allow you to hold massive amounts of similar data in only one variable. Single-dimensional arrays can be declared like this:

Dim sdarray(100) ;Create an array with 100 values

Or, multidimensional arrays can be declared like this:

Dim mdarray(100,3) ;Create an array with 100 rows, 3 columns

See Figures 6.15 and 6.16 to see the difference between the two. One other pointwhile in a For Next loop, you can easily loop through a multidimensional array like this:

A single-dimensional array.

A multidimensional array.

For columns = 0 To 3
For rows = 0 To 100
mdarray(rows, columns) = 314 ;set it to whatever you want
Next
Next

When you take a look at Figure 6.15 and Figure 6.16, notice how the array index has nothing to do with the value of the array. The index on Figure 6.15 is on the right of the array and is the row and column value put together (in such a way that row 2 column 3 is index (2,3) ). The value inside the array is x, which literally means that it can be ANY value, any number, or even a string.

NOTE

Yeah, these two functions sound very similar, don't they? Well, there is a small and subtle difference between them. For one, the ReadPixelFast() function is faster than the ReadPixel() function. Why? Because "fast" is appended to it? That may be a reason, but another is that ReadPixel() doesn't truly require the buffers to be locked to perform actions; however, ReadPixelFast() does.This allows it to be more tuned toward locked buffers, and therefore, a bit faster. In other words, it is usually a good idea to lock your buffer and use ReadPixelFast() rather than leave it unlocked and use ReadPixel .This goes for all the other Pixel and PixelFast functions also.

ReadPixel() and ReadPixelFast() are defined like this:

ReadPixel (x,y,[buffer])
ReadPixelFast (x,y,[buffer])

NOTE

CAUTION

Watch out! If you decide to use one of the PixelWrite functions without locking the buffer, you are making a huge mistake. This command will only work on a locked buffer. If the buffer is not locked, your computer may crash while running this pro gram. Also, watch for the coordi nates of the read-in pixels. If they are located off-screen , you will only get garbage values.

NOTE

CAUTION

Make sure you include the parentheses when you use this command. If you remember correctly, when you set a variable to the return value of a function, you must include parentheses around the parameters.

See Table 6.7 for an explanation of the parameters.

Table 6.7. ReadPixel() and ReadPixelFast()'s Parameters

Parameter	Description
`x`	The x coordinate of the read-in pixel
`y`	The y coordinate of the read-in pixel
`[buffer]`	The buffer you want to read in from ( `BackBuffer()` ,
`FrontBuffer()` ,	or `ImageBuffer()` )

Well, we really can't do anything so far, so I'll show you quickly how to use it. This code sample assumes that you are reading the pixels from a bitmap in the top-left corner.

Dim pixelarray(GraphicsWidth(),GraphicsHeight()) 


LockBuffer BackBuffer() ;Buffer MUST BE LOCKED
For cols = 0 To GraphicsHeight()
        For rows= 0 To GraphicsWidth()
            pixelarray(rows,cols) = ReadPixelFast (rows,cols)
        Next
Next

NOTE

GraphicsWidth() and GraphicsHeight()

Did you notice the two new functions GraphicsHeight() and GraphicsWidth() ? These two functions are very useful and pretty simple: they return the height and width of the screen. So, for example, if you initialize the graphics at the beginning of your program like this:

Graphics 800,600

then

x = GraphicsWidth()

will set x to 800 and

x = GraphicsHeight()

will set x to 600. You might wonder why you should use GraphicsHeight() and GraphicsWidth() instead of plugging in the numbers 800 and 600. The reason for this is that you might change the resolution while you're testing your program with different resolutions . If you change the resolution without changing the 800 and 600, your program will become corrupt and could easily crash your computer! Just remember, it's better to make your computer as general and portable as possible.

Pretty cool, huh? This code saves the pixels of the entire screen into pixelarray . The for loops work so that each pixel of one column is read before the next line is read. Figure 6.17 shows a visual example of this. Well, using only ReadPixel ()/ ReadPixelFast (), we can't really do much with it yet, so let's go on to WritePixel / WritePixelFast !

Figure 6.17. The reading process of the for loops.

WritePixel/WritePixelFast

WritePixel and WritePixelFast are just the opposite of ReadPixel() / ReadPixelFast() . Both of these functions are usually used together to copy and paste pixels from the screen.

NOTE

You will notice that you never retrieve the return value of the WritePixel functions, unlike the ReadPixel() functions, which do have variables that retain those values. For this reason, parentheses are not necessary around the parameters of WritePixel/ WritePixelFast when it is called, although they are allowed.

WritePixel and WritePixelFast are defined like this:

WritePixel x,y,rgb,[buffer]
WritePixelFast x,y,rgb,[buffer]

See Table 6.8 for a description of each parameter. The only parameter I want to examine is rgb . As you know, when using ReadPixel() / ReadPixelFast() , we stored all of the pixels in an array. The array index of the individual pixel you want to draw should be input for this parameter. In other words, use the pixelarray array for the rgb parameter.

Table 6.8. WritePixel/WritePixelFast's Parameters

Parameter	Description
`x`	The x coordinate of the plotted pixel
`y`	The y coordinate of the plotted pixel
`rgb`	The color of the plotted pixel (often stored in an array)
`[buffer]`	The optional buffer you want to plot to

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

Using WritePixel / WritePixelFast is very simple. You just include the parameters! Here is an example:

WritePixelFast 0,0,pixelarray(0,0)

This line will draw, at the top-left corner of the screen, the pixel that was stored at (0,0) when ReadPixel() / ReadPixelFast() was called.

Okay, now let's get into an actual sample program. This program is fully commented on the CD as demo06-07.bb.

; demo06-07.bb - A ReadPixelFast/WritePixelFast Example
 

Graphics 800,600
 

Print "Press any key to use ReadPixel"
;wait for user to do something
WaitKey
 

;load rectangle image
image =LoadImage("rectangle.bmp")
 

;Draw the intro screen
DrawImage image,0,0
DrawImage image,100,100
 

;Hold up  a second
Delay (1000)
 

;Create a pixel array that will hold the entire screen
Dim pixelarray(GraphicsWidth(),GraphicsHeight())

 
;lock the buffer REQUIRED
LockBuffer 


;Copy all of the pixels of the screen to the array
For rows=0 To GraphicsWidth()


      For cols=0 To GraphicsHeight()
            ;Copy the current pixel
            pixelarray(rows,cols)=ReadPixelFast(rows,cols)
      Next
Next


;Unlock the buffer
UnlockBuffer


Cls
Locate 0,0
Print "Press another key to copy pixels backwards"


;Wait for key press
WaitKey


;Lock the buffer to allow WritePixelFast
LockBuffer


; Use WritePixel to redraw the screen using the color information we got earlier
For rows=0 To GraphicsWidth()
      For cols=0 To GraphicsHeight()
            ;Draw the current pixels
            WritePixelFast rows,cols,pixelarray(GraphicsWidth()-rows,cols)
      Next
Next


; Unlock buffer after using WritePixelFast
UnlockBuffer


Print "Press a key to exit"
WaitKey

Figure 6.18 shows a screenshot taken from the program.

Figure 6.18. The demo06-07.bb program.

This program is probably pretty tough to understand, so let's go over it. The program begins by initializing the graphics and loading the images. After it loads the images, it delays the program so that the user can see what will be copied . After this, LockBuffer is called and ReadPixel() / ReadPixelFast() is used, like this:

LockBuffer
For rows=0 To GraphicsWidth()
      For cols=0 To GraphicsHeight()
            pixelarray(rows,cols)=ReadPixelFast(rows,cols)
      Next
Next
UnlockBuffer

Remember, LockBuffer MUST BE CALLED before using ReadPixelFast() . Just like all of the other pixel plotting functions, ReadPixelFast() requires a locked buffer; otherwise , the program will not act correctly and may crash. ReadPixelFast() works in the same way as the example a few sections ago: it copies all of the pixels in a row before moving on to the next row. Each of these pixel values is stored in an array. Now, because we are finished with ReadPixelFast() , we must call UnlockBuffer so that we can use other functions.

Now we clear the screen, and we call a new function named Locate . Locate is defined like this:

Locate x,y

Locate positions future text to any position on the screen. I wanted to keep the Print calls coming from the top-left corner of the screen, and Locate was necessary to keep the calls from moving down. Now we are finally to the WritePixelFast section.

LockBuffer
For rows=0 To GraphicsWidth()
      For cols=0 To GraphicsHeight()
            WritePixelFast rows,cols,pixelarray(GraphicsWidth()-rows,cols)
      Next
Next
UnlockBuffer

This snippet of code works just like ReadPixelFast() . It first locks the buffer, and then it begins a couple of for loops that count from each column in a row before moving to the next one. The WritePixelFast command is where the cool part of the program is, though.

WritePixelFast rows,cols,pixelarray(GraphicsWidth()-rows,cols)

I did something very wrong in this function call. Can you guess what it is? The problem is, I used the rows and cols variable in the x and y coordinate parameters. This is a bad idea, but I wanted to make a point. In this case, it works, but this is a rare case. Usually, you won't be copying the entire screen, but only a small part of it. You need to use another for loop to get the x and y values correct, or you can increment the x and y values inside the existing for loops.

The first few parameters of this function are simple: it draws the pixel at the given x,y position. (The x,y position is held in rows , cols and is determined by the For Next loop.) The parameters in the array are not as simple, however. This program draws the pixels in the array backwards on the left side, so we use the array value

pixelarray(GraphicsWidth()-rows,cols)

to draw each pixel backwards, flipped from the left to the right, but still the same from top to bottom. If you wanted to make the image flip horizontally, you would call WritePixelFast with this pixelarray :

pixelarray(rows, GraphicsHeight()-cols)

Pretty cool, huh! Well, we are now done with the Pixel / PixelFast functions, although there is another if you would like to research it. It is called CopyPixel / CopyPixelFast and is defined like this:

CopyPixel src_x,src_y,src_buffer,dest_x,dest_y,[dest_buffer]
CopyPixelFast src_x,src_y,src_buffer,dest_x,dest_y,[dest_buffer]

If you want to use this function, try to use this definition and make a few sample programs!

[ LiB ]

Flylib.com

Category list

Similar pages

Locking and Unlocking Buffers