| synopsis || return value || arguments || prev || next |
bool get( const char * name, int record_idx, int field_idx, int & value, bool allow_inherit=true, bool allow_extend=true, bool allow_derived=true)
Java: boolean Get( String name, int record_idx, int field_idx, int[] value, boolean allow_inherit, boolean allow_extend, boolean allow_derived)
[Declared in "../coresys/common/kdu_params.h"]
Retrieves a single integer (or integer compatible) parameter (field) from the named attribute.
The parameter values managed by any given attribute are organized as an array of records, each of which has an identical structure, defined by fields. Fields are typed and each field in the record may have a different type; however, the type of each field is immutable after configuration by the relevant parameter class's constructor. Simple field types are as follows: I (integer); B (boolean); and F (float). The attribute definition language used by parameter class constructors also supports enumerated and flag field types, both of which have integer values for the purpose of direct function queries. The enumerated type can take on only one of a number of pre-defined values, each of which has a textual identifier for use in parsing and textualization. The flag type represents a logical OR of any or all of a set of bit flags, each of which has a pre-defined value and associated textual identifier.
The present function may be used to query field values which may be represented as integers. This includes boolean fields, for which a value of 0 means false and a value of 1 means true; however, it is recommended that you use the explicit boolean form of this function for querying boolean valued fields.
The function generates an error (through kdu_error) if the request is incompatible with the record structure defined for this attribute. For example, the attribute might not support multiple records, it might not define sufficient fields, or the identified field might not have an integer type.
If the request is legal, but the relevant field has simply not been set, the function may return false. Before doing so, however, it applies a set of synthesis rules which may be used to synthesize the required value from available information. These synthesis rules form an essential role in effectively managing the vast number of coding parameters which could potentially be specified as part of a legal JPEG2000 code-stream. It is important to note that the allow_inherit and allow_extend arguments may be used to override certain aspects of the synthesis rules. We now describe the synthesis rules themselves.
If one or more values have already been supplied for the attribute, it may be possible to extrapolate these to satisfy a request for which data is not available. Extrapolation is permitted only if the allow_extend argument is true (the default) and the parameter class's constructor supplied the CAN_EXTRAPOLATE flag when defining this attribute (calling the protected define_attribute function). Extrapolation applies only when the requested record lies beyond the last record for which any field values have been supplied, in which case, the function returns the value of the indicated field from the last available record. If the field has not been defined in that record, the function returns false; no further synthesis is attempted.
If the attribute is empty (no field values have been supplied for any records), the request may be passed on to another object in the same cluster, following the inheritance rules outlined in the discussion appearing with the declaration of kdu_params. In particular, the request is first passed on to the tile head (object with the same tile index, but a component index of -1), if one exists — this object manages tile defaults for the cluster. If that object is also unable to satisfy the request, it is passed on to the object which has the same component index, but a tile index of -1 — this object manages component defaults for the cluster. If both of these fail, the request is forwarded to the cluster head (has both tile and component indices of -1). These inheritance rules apply only if the allow_inherit argument is true (the default) and only if the current object is the head of its instance list (instance index of 0). Inheritance is not available for non-primary instances.
False if the requested value has not yet been set and it cannot be synthesized from information available within the same cluster. Synthesis rules are described above.
Name of the attribute, from which a single parameter value is being queried. Attribute names are unique across all clusters. If necessary, a full string match is performed on the attribute name, but you would do well to use one of the pre-defined macros for the relevant derived parameter class. These are documented with the derived classes themselves.
0 for the first record.
0 for the first field in the record.
Used to return the requested value. Affected only if the function returns true.
If true, the request may be deferred to any other object in the cluster, following the standard inheritance rules. Otherwise, the request may be satisfied only from information in the current object.
If true, the request may be satisfied by extrapolating from the last available record, if that record has an index less than record_idx and it contains a value for the requested field.
If false, the function will ignore any attributes which have been marked as holding derived quantities through calls to the set_derived member function. This is useful when you want to inherit attributes from objects in the same cluster, bypassing any intermediate objects for which values might have been automatically derived. This capability is most useful when implementing finalize functions for specific parameter classes; these functions may have to do quite a bit of work to come up with appropriate default values where required parameter attributes have not been explicitly supplied.
| top || synopsis || return value || arguments || prev || next |