next up previous contents index
Next: Color Char Images Up: Char Images Previous: Related file (external) types   Contents   Index


Functions Summary

The following is a description of all the functions related to the Cimage type. The list is in alphabetical order.

$ \bigcirc$Name


mw_alloc_cimage - Allocate the gray plane




$ \bigcirc$Summary


Cimage mw_alloc_cimage(image,nrow,ncol)

Cimage image;

int nrow, ncol;




$ \bigcirc$Description


This function allocates the gray plane of a Cimage structure previously created using mw_new_cimage. The size of the image is given by nrow (number of rows or maximum range of y plus one) and ncol (number of columns or maximum range of x plus one). Pixels can be addressed after this call, if the allocation successed. There is no default value for the pixels.

Do not use this function if image has already an allocated plane: use the function mw_change_cimage instead.

The function mw_alloc_cimage returns NULL if not enough memory is available to allocate the gray plane. Your code should check this return value to send an error message in the NULL case, and do appropriate statement.




$ \bigcirc$Example

Cimage image=NULL; /* Internal use: no Input neither Output of module */

if  ( ((image = mw_new_cimage()) == NULL) ||
      (mw_alloc_cimage(image,256,256) == NULL) )
    mwerror(FATAL,1,"Not enough memory.\n");

/* Set pixel (0,1) to white */
image->gray[256] = 255;

$ \bigcirc$Name


mw_change_cimage - Change the size of the gray plane




$ \bigcirc$Summary


Cimage mw_change_cimage(image, nrow, ncol)

Cimage image;

int nrow, ncol;




$ \bigcirc$Description


This function changes the memory allocation of the gray plane of a Cimage structure, even if no previously memory allocation was done. The new size of the image is given by nrow (number of rows or maximum range of y plus one) and ncol (number of columns or maximum range of x plus one).

It can also create the structure if the input image = NULL. Therefore, this function can replace both mw_new_cimage and mw_alloc_cimage. It is the recommended function to set image dimension of input/output modules. Since the function can set the address of image, the variable must be set to the return value of the function (See example below).

The function mw_change_cimage returns NULL if not enough memory is available to allocate the gray plane. Your code should check this return value to send an error message in the NULL case, and do appropriate statement.




$ \bigcirc$Example

Cimage Output; /* Output of module */

Output = mw_change_cimage(Output, 256, 256);
if (Output == NULL) mwerror(FATAL,1,"Not enough memory.\n");

$ \bigcirc$Name


mw_clear_cimage - Clear the gray plane




$ \bigcirc$Summary


void mw_clear_cimage(image, v)

Cimage image;

unsigned char v;




$ \bigcirc$Description


This function fills the cimage image with the gray value given by v: all pixels will have the gray level v.

The speed of this function depends to the C library implementation, but it is usually very fast (trying to do faster is a waste of time).




$ \bigcirc$Example

Cimage image; /* Output of module */

image = mw_change_cimage(image, 100, 100);
if (image == NULL) mwerror(FATAL,1,"Not enough memory.\n");
/* Set all pixels to white */
mw_clear_cimage(image,255);

$ \bigcirc$Name


mw_copy_cimage - Copy the pixel values of an image into another one




$ \bigcirc$Summary


void mw_copy_cimage(in, out)

Cimage in,out;




$ \bigcirc$Description


This function copies the content of the gray plane of the image in into the gray plane of the image out. The size of the two gray planes must be the same.

The speed of this function depends to the C library implementation, but it is usually very fast (trying to do faster is a waste of time).




$ \bigcirc$Example

Cimage G; /* Needed Input */
Cimage F; /* Optional Output */

  if (F) {
    printf("F option is active: copy G in F\n");
    if ((F = mw_change_cimage(F, G->nrow, G->ncol)) == NULL)
	mwerror(FATAL,1,"Not enough memory.\n");
    else mw_copy_cimage(G, F);
   }
  else  printf("F option is not active\n");

$ \bigcirc$Name


mw_delete_cimage - Deallocate the gray plane




$ \bigcirc$Summary


void mw_delete_cimage(image)

Cimage image;




$ \bigcirc$Description


This function deallocates the gray plane of a Cimage structure previously allocated using mw_alloc_cimage or mw_change_cimage, and the structure itself.

You should set image = NULL after this call since the address pointed by image is no longer valid.




$ \bigcirc$Example

Cimage image=NULL; /* Internal use: no Input neither Output of module */

if  ( ((image = mw_new_cimage()) == NULL) ||
      (mw_alloc_cimage(image,256,256) == NULL) )
    mwerror(FATAL,1,"Not enough memory.\n");
.
.
.
mw_delete_cimage(image);
image = NULL;

$ \bigcirc$Name


mw_draw_cimage - Draw a line




$ \bigcirc$Summary


void mw_draw_cimage(image, a0, b0, a1, b1, c)

Cimage image;

int a0,b0,a1,b1; unsigned char c;




$ \bigcirc$Description


This function draws in image a connected line of gray level c between the pixel (a0, b0) and the pixel (a1, b1).




$ \bigcirc$Example

Cimage image; /* Output of module */

image = mw_change_cimage(image, 100, 100);
if (image == NULL) mwerror(FATAL,1,"Not enough memory.\n");
/* Set all pixels to white */
mw_clear_cimage(image,255);
/* Draw a black diagonal line */
mw_draw_cimage(image,0,0,99,99,0);

$ \bigcirc$Name


mw_getdot_cimage - Return the gray level value




$ \bigcirc$Summary


unsigned char mw_getdot_cimage(image, x, y)

Cimage image;

int x,y;




$ \bigcirc$Description


This function returns the gray level value (a number between 0 - black - and 255 - white -) of the given image for the pixel (x, y) (column #x and row #y).

Notice that a call to this function is a slow (but easy and secure) way to read a pixel value. See section 2 page [*] for how to read pixels fast.




$ \bigcirc$Example

Cimage image; /* Needed Input of module */
int x,y;      /* Needed Inputs of module */

if ((x < image->ncol) && (y < image->nrow))
	printf("image(%d,%d) = %d\n",x,y,mw_getdot_cimage(image,x,y));
else mwerror(ERROR,1,"Out of bounds !\n");

$ \bigcirc$Name


mw_isitbinary_cimage - Check if the image is binary




$ \bigcirc$Summary


unsigned char mw_isitbinary_cimage(image)

Cimage image;




$ \bigcirc$Description


This function returns 0 if image is not a binary image, a value > 0 if it is one. In that case, the returned value corresponds to the maxima value that is, to the only one value $ \neq$ 0. Image with two gray levels only but with the minimal value > 0 is not considered by this function as binary.




$ \bigcirc$Example

Cimage image; /* Needed Input of module */
unsigned char white;

if ((white=mw_isitbinary_cimage(image)) > 0)
 printf("Binary image with white set to %d\n",(int) white);
else 	
 printf("Not a binary image\n");

$ \bigcirc$Name


mw_new_cimage - Create a new Cimage




$ \bigcirc$Summary


Cimage mw_new_cimage();




$ \bigcirc$Description


This function creates a new Cimage structure with an empty gray plane. No pixels can be addressed at this time. The gray plane may be allocated using the function mw_alloc_cimage or mw_change_cimage.

Do not use this function for input/output of modules, since the MegaWave2 Compiler already created the structure for you if you need it (See Volume one: ``MegaWave2 User's Guide''). Use instead the function mw_change_cimage. Do not forget to deallocate the internal structures before the end of the module, except if they are part of an input or output movie.

The function mw_new_cimage returns NULL if not enough memory is available to create the structure. Your code should check this value to send an error message in the NULL case, and do appropriate statement.




$ \bigcirc$Example

Cimage image=NULL; /* Internal use: no Input neither Output of module */

if  ( ((image = mw_new_cimage()) == NULL) ||
      (mw_alloc_cimage(image,256,256) == NULL) )
    mwerror(FATAL,1,"Not enough memory.\n");

$ \bigcirc$Name


mw_newtab_gray_cimage - Create a bi-dimensional tab for the pixels of a Cimage




$ \bigcirc$Summary


unsigned char ** mw_newtab_gray_cimage(image)

Cimage image;




$ \bigcirc$Description


This function creates a new bi-dimensional tab which allows an easy and fast access to the pixels' gray level. This tab is actually an one-dimensional tab of pointers, so that each pointer points to the beginning of a line in the gray plane of the given image.

This function must be called after the gray plane has been allocated, using for example one of the functions mw_new_cimage, mw_alloc_cimage or mw_change_cimage. After that, if the gray plane allocation is changed (by e.g. mw_change_cimage or mw_delete_cimage), the tab is no longer valid and must be deleted using free(tab).

Ones the tab has been correctly created, is it possible to read or to write the value of the pixel (x, y) (x being an index for column and y for row) using tab[y][x].




$ \bigcirc$Example

Cimage image; /* Needed Input of module (gray plane already allocated and filled) */
int x,y;      /* Needed Input of module */
unsigned char **tab;

tab =  mw_newtab_gray_cimage(image);
if (tab==NULL) mwerror(FATAL,1,"Not enough memory\n");

/* Put white color in the pixel (x,y) */
if ((x < image->ncol) && (y < image->nrow)) tab[y][x] = 255;
else mwerror(ERROR,1,"Out of bounds !\n");

free(tab);

$ \bigcirc$Name


mw_plot_cimage - Set the gray level value




$ \bigcirc$Summary


void mw_plot_cimage(image, x, y, v)

Cimage image;

int x,y;

unsigned char v;




$ \bigcirc$Description


This function set the gray level value of the given image for the pixel (x, y) (column #x and row #y) to be v (a number between 0 - black - and 255 - white -).

Notice that a call to this function is a slow (but easy and secure) way to write a pixel value. See section 2 page [*] for how to write pixels fast.




$ \bigcirc$Example

Cimage image; /* Needed Input of module */
int x,y;      /* Needed Inputs of module */

/* Put white color in the pixel (x,y) */
if ((x < image->ncol) && (y < image->nrow))
        mw_plot_cimage(image,x,y,255));
else mwerror(ERROR,1,"Out of bounds !\n");


next up previous contents index
Next: Color Char Images Up: Char Images Previous: Related file (external) types   Contents   Index
mw 2004-05-05