VCLinux Library Documentation  3.11.2

Guidepost

Guidepost

Compiler setup and camera access is covered by a separate handbook.
Image processing functions are documented at their own library documentation.

A quick summary of the basic environment is given by the following modules:

  1. Main Data Types
  2. briefcodeforimagerecording
  3. Service Applications

Version changes are listed at the Changelog.

This documentation can also be found at the debian package named libvclinux-doc: the version of that package defines the documented library version installed at /usr/share/doc/libvclinux-doc/.

Common Design Principles

Hardware Access

  • The connection between the hardware pins/sockets and GPIO numbers can be found at the camera hardware documentation.
  • Configuration of the purpose of persistent hardware pin/socket assignment is done based on their GPIO by the program vcio.
  • This libvclinux library provides access to the camera hardware (e.g. for image acquisition).

API Nomenclature and Shape

  • The only purpose of a VC⋯Init structure is to initialize the related VC⋯Cfg structure.
  • A VC⋯Cfg structure is used to carry modifyable settings and only in rare cases acquired data.
  • Contained at a VC⋯Cfg structure may be a VC⋯Desc structure, which provides useful information, but its contents must not be modified.
  • Opposed to the mainly constant information at the VC⋯Desc structures, volatile information, like the capture id of a recorded image, can be found as a VC⋯Volatile substructure.
  • Additional settings and results for special cameras, like the VC Nano3d Z, are accessible by a VC⋯Custom and VC⋯CustomInit structure.
  • Due to the hybrid nature of the capture image's structure containing configuration but also result data, the capture image is directly accessed and configured at the VCSenCfg structure.
  • Other processing results are usually provided by a VC⋯Result structure, e.g. at such type of structure the custom VC Nano3d Z structure provides laser positions.
  • Data or functions named external used for further processing of result data, like the transformation of pixel to world coordinates of a VC Nano3d Z laser line.
  • For each enum a string can be formed by prepending a str_ in front of the enum name. Enum values should begin with the enum name without the VC prefix in upper case.
  • Each structure should have a nullifier named by prepending a NULL_ in front of the structure name.
  • Some structures provide default values named by postpending a _Default after the structure name, whilst some functions allow to pass a NULL instead of an initialisation structure pointer, and it is most likely, that the default values are applied for the NULLed initialisation structures.

API Process Flow

  • Common is the partition in four parts:
    1. Setup phase: Declared variables (including structures) have random values at the programming language C. So it is important to initialize the declarations with defined values, especially at VC⋯Init structures. To do so, we provide defaulter (postpend a _Default after the structure name) for VC⋯Init structures and nullifier (prepending a NULL_ in front of the structure name) for other kind. The default values at a VC⋯Init structure may be changed and fit to your needs then during this phase.
    2. Initialisation phase: By calling the appropriate ⋯_init() function, settings of the VC⋯Init structure will be used to make the provided VC⋯Cfg structure ready for use. The VC⋯Init structure should only be needed for initialisation.
    3. Processing phase: Settings at the VC⋯Cfg structure can be altered and configure function behaviour, for example, the image acquisition. This phase is where the program stays most of its time.
    4. Deinitialisation phase: When the initialised structures are not needed anymore, the appropriate ⋯_deinit() function will free memory and deinitialize properly.
general_structures.png
Process Flow Principle