gen_image1_externgen_image1_externGenImage1ExternGenImage1Externgen_image1_extern (Operator)
Name
gen_image1_externgen_image1_externGenImage1ExternGenImage1Externgen_image1_extern — Create an image from a pointer on the pixels with storage management.
Signature
Herror gen_image1_extern(Hobject* Image, const char* Type, const Hlong Width, const Hlong Height, const Hlong PixelPointer, const Hlong ClearProc)
Herror T_gen_image1_extern(Hobject* Image, const Htuple Type, const Htuple Width, const Htuple Height, const Htuple PixelPointer, const Htuple ClearProc)
void GenImage1Extern(HObject* Image, const HTuple& Type, const HTuple& Width, const HTuple& Height, const HTuple& PixelPointer, const HTuple& ClearProc)
void HImage::GenImage1Extern(const HString& Type, Hlong Width, Hlong Height, void* PixelPointer, void* ClearProc)
void HImage::GenImage1Extern(const char* Type, Hlong Width, Hlong Height, void* PixelPointer, void* ClearProc)
void HImage::GenImage1Extern(const wchar_t* Type, Hlong Width, Hlong Height, void* PixelPointer, void* ClearProc)
(
Windows only)
Description
The operator gen_image1_externgen_image1_externGenImage1ExternGenImage1ExternGenImage1Externgen_image1_extern creates an image of the size
WidthWidthWidthWidthwidthwidth * HeightHeightHeightHeightheightheight.
The pixels in PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer are stored line-sequentially.
The type of the given pixels
(PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer) must correspond to TypeTypeTypeTypetypetype
(see gen_image_constgen_image_constGenImageConstGenImageConstGenImageConstgen_image_const 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_image1gen_image1GenImage1GenImage1GenImage1gen_image1, and thus is not copied either.
This means that the memory space that PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer points
to must be released by deleting the object ImageImageImageImageimageimage.
This is done by the procedure ClearProcClearProcClearProcClearProcclearProcclear_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 ImageImageImageImageimageimage.
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 parameter PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer the
pointer has to be passed to the procedure depending
on the used operator signature and programming environment.
Attention
gen_image1_externgen_image1_externGenImage1ExternGenImage1ExternGenImage1Externgen_image1_extern does not check if enough memory for an image of
WidthWidthWidthWidthwidthwidth * HeightHeightHeightHeightheightheight is allocated in
PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer.
Also, gen_image1_externgen_image1_externGenImage1ExternGenImage1ExternGenImage1Externgen_image1_extern does not check whether the
PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer is valid or not.
Thus, it must be ensured by the user that it is valid.
Otherwise, the program may crash!
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
ImageImageImageImageimageimage (output_object) image → objectHImageHObjectHImageHobject * (byte / direction / cyclic / int1 / int2 / uint2 / int4 / real)
Created HALCON image.
TypeTypeTypeTypetypetype (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Pixel type.
Default:
'byte'
"byte"
"byte"
"byte"
"byte"
"byte"
List of values:
'byte'"byte""byte""byte""byte""byte", 'cyclic'"cyclic""cyclic""cyclic""cyclic""cyclic", 'direction'"direction""direction""direction""direction""direction", 'int1'"int1""int1""int1""int1""int1", 'int2'"int2""int2""int2""int2""int2", 'int4'"int4""int4""int4""int4""int4", 'real'"real""real""real""real""real", 'uint2'"uint2""uint2""uint2""uint2""uint2"
WidthWidthWidthWidthwidthwidth (input_control) extent.x → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Width of image.
Default:
512
Suggested values:
128, 256, 512, 1024
Value range:
1
≤
Width
Width
Width
Width
width
width
(lin)
Minimum increment:
1
Recommended increment:
10
HeightHeightHeightHeightheightheight (input_control) extent.y → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Height of image.
Default:
512
Suggested values:
128, 256, 512, 1024
Value range:
1
≤
Height
Height
Height
Height
height
height
(lin)
Minimum increment:
1
Recommended increment:
10
PixelPointerPixelPointerPixelPointerPixelPointerpixelPointerpixel_pointer (input_control) pointer → HTupleintHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)
Pointer to the first gray value.
ClearProcClearProcClearProcClearProcclearProcclear_proc (input_control) pointer → HTupleintHTupleHtuple (integer) (IntPtr) (Hlong) (Hlong)
Pointer to the procedure re-releasing the memory
of the image when deleting the object.
Default:
0
Example (C)
void NewImage(Hobject *new)
{
unsigned char *image;
int r,c;
image = malloc(640*480);
for (r=0; r<480; r++)
for (c=0; c<640; c++)
image[r*640+c] = c % 255;
gen_image1_extern(new,"byte",640,480,(Hlong)image,(Hlong)free);
}
Result
The operator gen_image1_externgen_image1_externGenImage1ExternGenImage1ExternGenImage1Externgen_image1_extern returns the value 2 (
H_MSG_TRUE)
if the parameter values are correct.
Otherwise an exception is raised.
Alternatives
gen_image1gen_image1GenImage1GenImage1GenImage1gen_image1,
gen_image_constgen_image_constGenImageConstGenImageConstGenImageConstgen_image_const,
get_image_pointer1get_image_pointer1GetImagePointer1GetImagePointer1GetImagePointer1get_image_pointer1,
gen_image3_externgen_image3_externGenImage3ExternGenImage3ExternGenImage3Externgen_image3_extern
See also
reduce_domainreduce_domainReduceDomainReduceDomainReduceDomainreduce_domain,
paint_graypaint_grayPaintGrayPaintGrayPaintGraypaint_gray,
paint_regionpaint_regionPaintRegionPaintRegionPaintRegionpaint_region,
set_grayvalset_grayvalSetGrayvalSetGrayvalSetGrayvalset_grayval
Module
Foundation