NAME

get_target_byte_image - Gets target Byte image for "building block" routines

SYNOPSIS

#include "i/i_byte.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int get_target_byte_image
(
	Byte_image **target_ipp,
	int num_rows,
	int num_cols
);

DESCRIPTION

This routine implements the image creation/over-writing symantics used in the KJB library in the case of Byte images. If *ipp is NULL, then this routine creates the images. If it is not null, and it is the right size, then this routine does nothing. If it is the wrong size, then it is resized. If an actual resize is needed, then a new image of the required size is first created. If the creation is successful, then the old image is free'd. The reason is that if the new allocation fails, a calling application should have use of the old image. The alternate is to free the old image first. This is more memory efficient. A more sophisticated alternative is to free the old image if it can be deterimined that the subsequent allocation will succeed. For example, on systems where it can be guaranteed that free'd memory is not released to the system, this can be done based on image size. More sophisticated methods may also be available. However, any such approach will be system dependent. Although such approaches have merit, it is expected that resizing will occur infrequently enought that it is not worth implementing them. Thus the simplest method with good semantics under most conditions has been used. The sizes (num_rows and num_cols) must both be nonnegative. Conventionally, num_rows and num_cols are both positive; however, it is also acceptable to have num_rows and num_cols both zero. Anything else (such as a mix of positive and zero sizes) is regarded as a bug in the calling program -- set_bug(3) is called and (if it returns) ERROR is returned.

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER

Kobus Barnard

SEE ALSO

create_byte_image , free_byte_image