About

The RangeData stores data on ranges and on the current value within these ranges. It is typically used with the LodObject. The RangeData class is defined in the customgui_range.h header file. The ID is ::CUSTOMDATATYPE_RANGE.

Access

RangeData data is typically accessed from a LodObject. See LodObject Manual.

  // This example reads the range data from the given LOD object.
 
  GeData rangeData;
  if (!lodObject->GetParameter(ConstDescID(DescLevel(LOD_BAR)), rangeData, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const RangeData* const rangeCustomData = rangeData.GetCustomDataType<RangeData>();
  if (rangeCustomData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  ApplicationOutput("Value: " + String::FloatToString(currentValue));

Allocation/Deallocation

RangeData objects are created with the usual tools, see Entity Creation and Destruction Manual (Cinema API).

RangeData::Alloc(): Creates a new RangeData object.
RangeData::Free(): Deletes the given RangeData object.

A RangeData object must be initialized:

RangeData::Init(): Initializes the object with the passed range number.
RangeData::Reset(): Resets the object to the initial state.

  // This example configures the given LOD object and defines the
  // number of manual groups using the RangeData data.
 
  // create custom data
  AutoAlloc<RangeData> rangeCustomData;
  if (rangeCustomData == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // configure LodObject
 
  lodObject->SetParameter(ConstDescID(DescLevel(LOD_MODE)), LOD_MODE_MANUAL_GROUPS, DESCFLAGS_SET::NONE);
  lodObject->SetParameter(ConstDescID(DescLevel(LOD_CRITERIA)), LOD_CRITERIA_SCREEN_H, DESCFLAGS_SET::NONE);
 
  // configure range data
  if (!rangeCustomData->Init(10))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // store to LodObject
 
  GeData rangeGeData;
  rangeGeData.SetCustomDataType<RangeData>(rangeCustomData);
  lodObject->SetParameter(ConstDescID(DescLevel(LOD_BAR)), rangeGeData, DESCFLAGS_SET::NONE);

Value

A RangeData stores a value between 0.0 and 1.0:

RangeData::GetCurrentValue(): Returns the current value.
RangeData::SetCurrentValue(): Sets the current value.

  // This example sets the current, user defined value of the range slider.
 
  // get range data
 
  GeData rangeData;
  lodObject->GetParameter(ConstDescID(DescLevel(LOD_BAR)), rangeData, DESCFLAGS_GET::NONE);
 
  RangeData* const rangeCustomData = rangeData.GetCustomDataTypeWritable<RangeData>();
  if (rangeCustomData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // User LOD Value
  lodObject->SetParameter(ConstDescID(DescLevel(LOD_CRITERIA)), LOD_CRITERIA_MANUAL_SLIDER, DESCFLAGS_SET::NONE);
 
  // set value
  rangeCustomData->SetCurrentValue(0.5);
  lodObject->SetParameter(ConstDescID(DescLevel(LOD_BAR)), rangeData, DESCFLAGS_SET::NONE);

Knots

Multiple knots can be added to a RangeData object. These knots define the borders of the ranges.

RangeData::AddValue(): Adds a new knot at the given value. The existing range is split.
RangeData::GetKnotsCount(): Returns the number of knots.
RangeData::DeleteKnot(): Deletes the knot with the given index.
RangeData::GetKnotValue(): Returns the value of the knot with the given index.
RangeData::SetKnotValue(): Sets the value of the knot with the given index.
RangeData::GetKnotIndexByValue(): Returns the index of the knot which value is equal to the given value.

  // This example clears the given RangeData and
  // adds two new knots.
 
  // clear
  rangeCustomData->Reset();
 
  // add knots
  rangeCustomData->AddValue(0.33);
  rangeCustomData->AddValue(0.66);
 
  // set selection
  rangeCustomData->SetSelectedKnot(0);
 

A single knot can be selected:

RangeData::GetSelectedKnot(): Returns the index of the selected knot or NOTOK.
RangeData::SetSelectedKnot(): Selects the knot with the given index.

  // This example deletes the currently selected knot.
 
  const Int knotIndex = rangeCustomData->GetSelectedKnot();
 
  rangeCustomData->DeleteKnot(knotIndex);

Ranges

Value ranges are defined as the space confined by knots:

RangeData::GetRangesCount(): Returns the number of ranges.
RangeData::GetRangeIndex(): Returns the range index for the given value.
RangeData::GetSelectedRange(): Returns the index of the selected range or NOTOK.
RangeData::SetSelectedRange(): Selects the range with the given index.

  // This example sets the color of the range containing the current value.
 
  // get current range
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  const Int   currentRange = rangeCustomData->GetRangeIndex(currentValue);
 
  // set color
 
  const Vector color { 1.0, 0.0, 0.0 };
  rangeCustomData->SetRangeColor(currentRange, color);

Color Modes

The ranges between knots can be colored in different ways:

RangeData::IsPerRangeColorMode(): Returns true if a color is stored for each range.
RangeData::SetColorMode(): Sets the color mode.
RangeData::GetRangeColor(): Returns the color of the range with the given index.
RangeData::SetRangeColor(): Sets the color of the range with the given index.
RangeData::IsRandomColorMode(): Returns true if the assigned colors are random.
RangeData::SetRandomColorMode(): Sets the random color mode.

  // This example assigns a new color to each range.
 
  // set mode
  rangeCustomData->SetRandomColorMode(false);
  rangeCustomData->SetColorMode(true);
 
  // get number of ranges
 
  const Int   rangeCount = rangeCustomData->GetRangesCount();
  const Float colorStep  = 1.0 / Float(rangeCount);
 
  // set color of each range
  for (Int i = 0; i < rangeCount; ++i)
  {
    const Vector hsv { Float(i) * colorStep, 1.0, 1.0 };
    const Vector rgb = HSVToRGB(hsv);
 
    rangeCustomData->SetRangeColor(i, rgb);
  }

RangePair

The dimensions of a range are stored with a RangePair object:

RangeData::GetRange(): Returns the RangePair for the range with the given index.

The RangePair class includes:

RangePair::Contains(): Returns true if the given value is within the range.
RangePair::GetMin(): Return the minimal value of the range.
RangePair::GetMax(): Returns the maximal value of the range.
RangePair::GetCenter(): Returns the center of the range.

  // This example sets the current value to the center
  // of the current range.
 
  // get current value and range
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  const Int   currentRange = rangeCustomData->GetRangeIndex(currentValue);
 
  // get range center
 
  const RangePair rData = rangeCustomData->GetRange(currentRange);
  const Float     centerValue = rData.GetCenter();
 
  // set value
  rangeCustomData->SetCurrentValue(centerValue);

Table of Contents