14.5 Video processing part 3: memory management  (Page 3/4)

Memory streams

Memory streams are structures used to facilitate the transfer of data between internal and external memory. But why do we need a structure? Can’t we just do it manually?

You could, but you’d spend two months to do the same work as a single stream, which only takes a few minutes (hopefully). So to cut a long story short, streams are your friends. They help remove much of the complexity associated with internal/external memory transfers.

First, please make sure you’ve read the manual sections mentioned on page 1. There are two basic types of streams : input and output. Input is a transfer from external to internal. Output is the opposite. Think of bringing in and putting out.

For each type we need to specify various parameters, such source and destination addresses, increments, size of transfer chunks and so forth. This specification is done once for each transfer session (say, once for each image transfer), using the dstr_open command. We then use dstr_get and dstr_put commands to tell the stream to bring in or put out data one chunk at a time.

Creating and destroying streams

Streams are dstr_t objects. You can create a dstr_t object and then initialize it using the dstr_open() command. Basically, start with, dstr_t o_dstr; Then use the dstr_open (…); The dstr_open () specification is given in the manual. Some clarifications are made here. As an example we will consider the output stream o_dstr in color_convert(). This stream is an output stream. This stream is used to transfer data from internal memory to the screen output data buffer. (we captured the buffer's memory location in the previous section using togglebufs(), it's memory address is stored in the pointer out_image->img_data)

Arguments (note : out_rows = 480, out_cols = 640):

• dstr_t *dstr needs a pointer to the data stream object we wish to use. In our case this would be o_dstr.
• void *x_data takes a pointer to the location in external memory which we are using. In our program this is specified in out_image->img_data. And since we are using an output stream, this argument specifies the Destination of the stream. (This argument is the Source for an input stream)
• int x_size takes in the size of the external data buffer to which we are writing to. This specifies the actual number of bytes of external memory we will be traversing. So this is NOT necessarily the full size of the output buffer (i.e. NOT always 640 X 480 X 2) For our example we are writing to the full screen hence we use (2 * out_rows * out_cols) which results in 640 X 480 X 2 bytes of data.An example of the exception is when we write to only, say, the first 10 rows of the screen. In this case we would only traverse: 10 X 640 X 2 bytes. One more thing to note is that if you need to only write to the first 40 columns of the first 10 rows, you would still need to traverse the same amount of space and you would use 10 X 640 X 2 bytes again for this argument. In this case however, you will be skipping some of the data, as shown later.
• void *i_data takes a pointer to the location in internal memory we are using. In our program this is specified as out_data. And since we are using an output stream, this argument specifies the Source of our stream. (This argument is the Destination for an input stream).
• unsigned short i_size is used to specify the total size of the internal memory we will be using. In our case we will be writing one line of the output screen - (4 * out_cols) This is the amount we allocated earlier.This evaluates to 640 * 2 * 2 bytes. The extra ‘2’ is needed for double-buffering, which is a system used by the IDK for transferring data into internal memory. Basically, the IDM (image data manger) needs twice the amount of internal memory as data transferred. i.e. one line is worth only 640 * 2 bytes, but because of double buffering we allocate twice that for the IDM’s use. Remember this when allocating memory space for internal memory.
• unsigned short quantum specifies the amount of data transferred in a single dstr_get or dstr_put statement. In our case it would be (2 * out_cols). This evaluates to 640 * 2 bytes – one line of the output screen each time we use dstr_put Now, if we were transferring only part of a line, let’s take the first 40 columns of the first 10 rows example. With each dstr_put, we will output only the first forty columns of each row. Thus we are transferring 40 * 2 bytes in each call. But this can be extended further. By use of the ‘dstr_get_2D’ we can transfer multiple lines of data. So we can, say, transfer two full rows of the output screen (4 * cols) or in our mini-example this would mean 2 * 40 * 2 bytes.Transferring of multiple lines is very useful, especially when using filters which work on 2-D ‘regions’ of data.
• unsigned short multiple specifies the number of lines we are transferring with each call. Now this is not the conceptual number of lines. It is the physical multiple of argument 6 that we are transferring. It is best to leave this at one and modify argument 6 above.
• unsigned short stride needs the amount by which to move the external memory pointer. This gives us control over how the lines are extracted. In our case, it being the simplest, we move one line at a time : 2*out_cols The stride pointer is especially useful when creating input streams. For example you can pull in overlapping lines of input. So you can pull in lines 1 and 2 in the first dstr_get(). The next dstr_get() can pull in lines 2 and 3 or you can setup it up to pull lines 3 and 4 or 4 and 5 or ….. depending on the stride.In particular, this is useful in Sobel (edge-detect) filtering, where you need data above and below a pixel to evaluate the output.
• unsigned short w_size is the window size. For transferring a single line at a time we would use '1' here, and the system will recognize this is as one line double-buffered. But if we needed to transfer two lines we would merely submit '2' as the argument.
• dstr_t dir specifies the type of stream. Use DSTR_OUTPUT for output stream and DSTR_INPUT for input stream.