SliceO_Class Buffer

With each class is associate a number of "buffers". This is where you are asked to store any data you may create that are related to the classes. For example, if you need to create a work copy of the image, you create a buffer for it and store it in that buffer.

There is a mechanism to insure that the buffer you create will not be confused with buffers from other DLLs. You assign an your own ID to the buffer. Since these are 32 bit values, hopefully yours will be unique.

One of the advantage of these buffers is that the memory used in the buffers will be under the supervision of the Memory Manager.

Here's how to create and use a "user" buffer.

Create the buffer

First, you create the buffer. Buffers are instances of the SliceO_Buffer class.

You must assign a priority to this buffer (from 0x01 to 0x0F). When the memory manager need to do a memory cleanup, it will remove memory starting with the higher priority values and going down until it has freed enough memory.

SliceO_Buffer *buf_local = new SliceO_Buffer( YOUR_PRIORITY ) ;

Assign name and memory to the buffer

Then assign a name to the buffer.

buf_local->Name_Set( "your_buffer" ) ;

and the desired memory to your buffer.

here you have 2 choices:

·A simple memory block

buf_local->Data_New( dim ) ;

·A 2D matrix

buf_local->Matrix_New( x, y, dim ) ;

Note: You can also have an array of memory buffers inside a memory buffer using the "m_child_nb" and "m_child_pt" variables. But when the memory manager does a cleanup, he only look at the priority of the first buffer before deciding to delete.

Assign buffer to "user" structure

And finally you assign this buffer to the "user" structure in your class using the "User_Set" method. The "ID" you provide must be unique.

Note:

TomoVision reserve ID 0 through 100. The range of available ID are 100 to 2³²-1 (=4,294,967,295).

class_pointer->User_Set( YOUR_ID, buf_local ) ;

Accessing the "user" buffers

You can retrieve a pointer to the buffer with the method "User_Get" (make sure you test the validity of the returned pointer since the memory manager may have deleted the buffer):

SliceO_Buffer *buf_local = class_pointer->User_Get( YOUR_ID ) ;

if ( ! buf_local )

...

Once you do have a pointer to the buffer, you can lock it to prevent having it destroyed while you are working with it:

buf_local->Lock() ;

You can get a pointer to the memory associated with the buffer:

·Simple memory block:

void *data = buf_local->Data_Get() ;

·2D matrix:

unsigned short matrix_x = buf_local->Matrix_Get_X() ;

unsigned short matrix_y = buf_local->Matrix_Get_Y() ;

unsigned short matrix_dim = buf_local->Matrix_Get_Dim() ;

void **matrix_data = buf_local->Matrix_Get() ;

Deleting the "user" buffers

When you do not need it anymore, you can delete your buffer (and free all associated memory) withthe "User_Delete" method:

class_pointer->User_Delete( YOUR_ID ) ;

The Memory Manager and the "User" buffers

The Memory Manager keep a watch on the available RAM memory. If you are running low on memory, the manager will start to delete memory buffers. For this it use the priority values that have been assigned to the buffers. It will delete the lowest priority buffers (those having the higher priority number) until enough memory has been recuperated. This is why when you use the "User_Get" method, you have to make sure the pointer you received is valid. If the buffer has been recycled, you will get a NULL pointer.

The buffer shortcuts

Some of the "SliceO_Frame" class buffers are used often enough to justify having a shortcut to them in the SliceO_Frame class. If the shortcut is not "NULL" you can use it, otherwise you have to use the "User_Get" method to get access to the buffer.

Buf_Erase

This buffer keep a copy of the TAG data that is used for the "erase" operations.

Buf_Disp_TAG

These buffer contain an RGB copy of the TAG and GLI data. These are the pixel data as it is displayed on the screen. The GLI data is adjusted for the contrast and brightness, transforming the original 16 bit data in 8 bit RGB. The TAG data is converted from TAG value to RGB colors using the colors of the TAGS.

Buf_Disp_GLI

Buf_Work_TAG

These buffers contain "Work" copy of the TAG and GLI data. they are expressed in their original format (16 bits for the GLI, 8 bits for the TAG) but are kept locally in the frame.

Buf_Work_GLI

Buf_Mask

This buffer contain a 1 byte unsigned char matrix of flags. One byte for each pixels of the frame. This flag signal if a filter and a gradient value exist for the pixel.

Buf_Filter

This buffer contain a filtered version of the frame. The filtered pixel are stored in an unsigned short matrix.

Buf_Gradient

This buffer contain the gradient information for each pixel of the frame. The gradient is stored in a 32 bit integer. The higher 16 bits contain the amplitude of the gradient, the lower 16 bits its direction encode as 2 angles (theta: 0x0000FF80, and Phi: 0x000007F)

SliceO_Class elements

The variables and methods relating to the "User" buffers in the SliceO_Class class are:

Private:

m_user_nb (int)

A variable containing the number of user structures.

m_user_id (unsigned int *)

An array of user structures ID.

m_user_pt (SliceO_Buffer **)

An array of pointers to the user structures.

Public:

User_Get

Get a pointer to a specific user structure.