Teledyne Princeton Instruments PICam 5.x, Programmer'S Manual

Page: 18 / 357

18 PICam™ 5.x Programmer’s Manual Issue 11
2.5 Naming Conventions
The following naming conventions are used in PICam:
• All primitive types have a typedef with a
pi
prefix (e.g.,
piint
,
pi64s
.)
• All functions defined by PICam are prefixed with
Picam_
and return an error
code of
PicamError
(e.g.,
Picam_GetParameterIntegerValue
,
Picam_CloseCamera
.)
• All functions that allocate memory to store the results of a function call return a
pointer to a constant allocation of the appropriate type. For example:
—
Picam_GetEnumerationString
returns a string by taking the address of a
pointer to a constant string. In other words an argument to the function is
const pichar**
.
—
Picam_GetParameterCollectionConstraint
returns a collection constraint
by taking the address of a pointer to a constant collection constraint. In
other words, an argument to the function is
const
PicamCollectionConstraint**
.
• All functions that allocate an array of memory to store the results of the
function call return a pointer to a constant array allocation of the appropriate
type as well as the number of items in the array.
For example,
Picam_GetParameters
returns an array of parameters by taking the
addresses of a pointer to a constant parameter array and a count. In other
words, two arguments to the function are
const PicamParameter**
and
piint*
.
• All functions that free memory allocated by PICam have a
Picam_Destroy
prefix
(e.g.,
Picam_DestroyString
,
PicamDestroy_CollectionConstraints
,
PicamDestroyRois
.)
• All types defined by PICam are prefixed with
Picam
and have a typedef to
<TypeName>
(e.g.,
PicamParameter
,
PicamRoi
.)
• All enum type members defined by PICam are prefixed with
<EnumName>_
(e.g.,
PicamValueType
enum has a
PicamValueType_Integer
constant.)
• All enum types that represent multiple values with bit masks have a
Mask
suffix
(e.g.,
P
icamCcdCharacteristicsMask
,
PicamTimeStampsMask
.)
2.6 Concepts
Figure 2-1 is a high-level block diagram of the basic PICam structure. Hardware that is
powered on and plugged into the host computer is initially represented by hardware
IDs. The content of the hardware ID will be unique for each piece of hardware. From the
hardware ID, basic information can be garnered such as availability and basic
information. It is also from a hardware ID that hardware can be opened. Once opened,
the hardware can be configured by adjusting the values of its parameters. The
permitted values a parameter can take are defined by its constraints. Different hardware
items not only possess different parameters, but different rules for interacting with
those parameters. This information for each parameter may also be queried. Once a
piece of hardware has been configured, data can be acquired from it.