HALCON Extension Package Programmer's Manual

42 CHAPTER 3. STYLE GUIDE FOR PROGRAMMING3.2.2 Permanent DataThe HALCON Extension Package Interface also provides routines for permanently allocating/deallocatingmemory (see Fig. 3.3 and 3.4). They work similar to the standard -proceduresÑÐÐÓ and Ö, but use a caching mechanism for small data blocks and provide additionaldebugging information.Note, that in contrast to ÀÐÐÓÄÓÐ memory allocated by ÀÐÐÓ is not deallocated automaticallyafter the execution of a HALCON operator. Thus, this routine should be used toallocate permanent data. For example, all the iconic objects stored in the HALCON data baseare allocated with this routine (see chapter 5 and 6).ÀÆÛÁÑ allocates raw image data inside 1 the data structure ÀÑ (see section 4.1) basedon ÀÐÐÓ. Furthermore, Ñ is initialized and the timestamp is set to the current time. Theimage matrix itself is initialized with ¼ if ³ÒØ ÒÛ Ñ³ has been set to ³ØÖÙ³ using theHALCON operator ×Ø ×Ý×ØÑ. This flag can be read inside HALCON using the ExtensionPackage Interface callÀÊδÔÖÓÒи ÀÁÒØÆÛÁѸ ²ÒØÒÛѵwith ÒØ ÒÛ Ñ of type ÀÇÇÄ and setÀÏÖØδÔÖÓÒи ÀÁÒØÆÛÁѸ ßÌÊ͸ÄËеThus, it is possible to buffer the global setting of this flag, set the flag to ÄË prior toÀÆÛÁÑ, and restore the old value afterwards, if you would like to prevent an initializationin any case.ÀÆÛÁÑÈØÖ does not allocate memory for the image data, but inserts the pointer Ø inthe ÀÑ structure Ñ instead. For this routine the initialization of the image data iscontrolled via the parameter ÒØÁÑ. Note, that you will encounter program crashes duringdeallocation of image objects, if you insert a memory block that has not been allocated viaÀÐÐÓ in the underlying ÀÑ structure (see e.g., ÀÈÙØÁÑ in section 5.4). However, inspecific situations (for example while doing a frame grabber integration) it might be desirableto use existing buffers allocated by some other procedures. In that case you have to provideyour own deallocation routine Í×ÖÐÖÈÖÓÙÖ using ËØÐÖÁÑ for the imagedata when creating a HALCON image object in a supply procedure:ÀÈÙØÁÑ´ÔÖÓÒиѸÄ˸²ÑݵÀÈ´ËØÐÖÁÑ´ ÔÖÓÒиÑݸ´ÖÁÑÈÖÓµÍ×ÖÐÖÈÖÓÙÖµµwhere ÖÁÑÈÖÓ is defined asØÝÔ ÚÓ ´ÖÁÑÈÖÓµ´ÚÓ Ñѵthat means, the deallocation routine has got one parameter of type ÚÓ and no return value. Ifyou pass a ÆÍÄÄ pointer instead of Í×ÖÐÖÈÖÓÙÖ the image data will not be deallocated1 So ÀÆÛÁÑ does not allocate memory for the ÀÑ structure itself.HALCON Extension Package Interface / 2000-11-16