gen_image3_externGenImage3ExternGenImage3Externgen_image3_externgen_image3_extern🔗

Short description🔗

gen_image3_externGenImage3ExternGenImage3Externgen_image3_externgen_image3_extern — Create a three-channel image from three pointers on the pixels with storage management.

Signature🔗

gen_image3_extern( out image Image, string Type, extent.x Width, extent.y Height, pointer PointerRed, pointer PointerGreen, pointer PointerBlue, pointer ClearProc )

Description🔗

The operator gen_image3_externGenImage3Extern creates a three-channel image of the size Widthwidthwidth * Heightheightheight. The pixels in PointerRedpointerRedpointer_red, PointerGreenpointerGreenpointer_green, and PointerBluepointerBluepointer_blue are stored line-sequentially. The type of the given pixels must correspond to Typetypetype (see gen_image_constGenImageConst for a more detailed description of the image types). Note that how to pass a pointer value depends on the used operator signature and programming environment. Make sure to pass the actual memory address where the image data is stored, not the address of a pointer variable. Care must be taken not to truncate 64-bit pointers on 64-bit architectures.

The memory for the new image is not newly allocated by HALCON, contrary to gen_image3GenImage3, and thus is not copied either. This means that the memory space that PointerRedpointerRedpointer_red, PointerGreenpointerGreenpointer_green, and PointerBluepointerBluepointer_blue point to must be released by deleting the object Imageimageimage. This is done by the procedure ClearProcclearProcclear_proc provided by the caller. This procedure must have the following signature

      void ClearProc(void* ptr);

and will be called using __cdecl calling convention when deleting Imageimageimage. If the memory shall not be released (in the case of frame grabbers or static memory) a procedure “without trunk” or the NULL-Pointer can be passed. Analogous to the parameters PointerRedpointerRedpointer_red, PointerGreenpointerGreenpointer_green, and PointerBluepointerBluepointer_blue the pointer has to be passed to the procedure depending on the used operator signature and programming environment.

Attention🔗

gen_image3_externGenImage3Extern does not check if enough memory for an image of Widthwidthwidth * Heightheightheight is allocated in PointerRedpointerRedpointer_red, PointerGreenpointerGreenpointer_green, and PointerBluepointerBluepointer_blue.

Also, gen_image3_externGenImage3Extern does not check whether the pixels in PointerRedpointerRedpointer_red, PointerGreenpointerGreenpointer_green, and PointerBluepointerBluepointer_blue are valid or not. Thus, it must be ensured by the user that they are valid. Otherwise, the program may crash!

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters🔗

Imageimageimage (output_object) image → object (byte / direction / cyclic / int1 / int2 / uint2 / int4 / real)

Created HALCON image.

Typetypetype (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Pixel type.

Default: 'byte'"byte"
List of values: 'byte', 'cyclic', 'direction', 'int1', 'int2', 'int4', 'real', 'uint2'

Widthwidthwidth (input_control) extent.x → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Width of image.

Default: 512512
Suggested values: 128, 256, 512, 1024128, 256, 512, 1024
Value range: 1 ≤ Width (lin)
Minimum increment: 1
Recommended increment: 10

Heightheightheight (input_control) extent.y → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Height of image.

Default: 512512
Suggested values: 128, 256, 512, 1024128, 256, 512, 1024
Value range: 1 ≤ Height (lin)
Minimum increment: 1
Recommended increment: 10

PointerRedpointerRedpointer_red (input_control) pointer → (integer)HTuple (Hlong)HTuple (IntPtr)intHtuple (Hlong)

Pointer to the first gray value of the first channel.

PointerGreenpointerGreenpointer_green (input_control) pointer → (integer)HTuple (Hlong)HTuple (IntPtr)intHtuple (Hlong)

Pointer to the first gray value of the second channel.

PointerBluepointerBluepointer_blue (input_control) pointer → (integer)HTuple (Hlong)HTuple (IntPtr)intHtuple (Hlong)

Pointer to the first gray value of the third channel.

ClearProcclearProcclear_proc (input_control) pointer → (integer)HTuple (Hlong)HTuple (IntPtr)intHtuple (Hlong)

Pointer to the procedure re-releasing the memory of the image when deleting the object.

Default: 00

Example🔗

(C)

void NewImage(Hobject *new)
{
  unsigned char  *image_red\;
  unsigned char  *image_green\;
  unsigned char  *image_blue\;
  int            r,c\;
  image_red = malloc(640*480)\;
  image_green = malloc(640*480)\;
  image_blue = malloc(640*480)\;
  for (r=0\; r<480\; r++)
    for (c=0\; c<640\; c++)
    {
      image_red[r*640+c] = c % 255\;
      image_green[r*640+c] = (c+64) % 255\;
      image_blue[r*640+c] = (c+128) % 255\;
    }
  gen_image3_extern(new,"byte",640,480,(Hlong)image_red,\
(Hlong)image_green,(Hlong)image_blue,(Hlong)free)\;
}

Result🔗

The operator gen_image3_externGenImage3Extern returns the value 2 (H_MSG_TRUE) if the parameter values are correct. Otherwise an exception is raised.

Combinations with other operators🔗

Combinations

Alternatives

gen_image3GenImage3, gen_image_constGenImageConst, get_image_pointer3GetImagePointer3, gen_image1_externGenImage1Extern

Module🔗

Foundation