tmf/org.eclipse.tracecompass.tmf.ui/src/org/eclipse/tracecompass/tmf/ui/viewers/xycharts/ITmfChartTimeProvider.java

   1 /**********************************************************************
   2  * Copyright (c) 2013, 2014 Ericsson, École Polytechnique de Montréal
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Bernd Hufmann - Initial API and implementation
  11  *   Geneviève Bastien - Moved some methods to ITmfTimeProvider
  12  **********************************************************************/
  13 package org.eclipse.tracecompass.tmf.ui.viewers.xycharts;
  14
  15 import org.eclipse.tracecompass.tmf.ui.viewers.ITmfTimeProvider;
  16
  17 /**
  18  * Interface adding some methods specific for SWT charts to the base time
  19  * provider interface. Typically, the time will be shown on the x-axis.
  20  *
  21  * @author Bernd Hufmann
  22  */
  23 public interface ITmfChartTimeProvider extends ITmfTimeProvider {
  24
  25     /**
  26      * Returns a constant time offset that is used to normalize the time values
  27      * to a range of 0..53 bits to avoid loss of precision when converting long
  28      * <-> double.
  29      *
  30      * Time values are stored in TMF as long values. The SWT chart library uses
  31      * values of type double (on x and y axis). To avoid loss of precision when
  32      * converting long <-> double the values need to fit within 53 bits.
  33      *
  34      * Subtract the offset when using time values provided externally for
  35      * internal usage in SWT chart. Add the offset when using time values
  36      * provided by SWT chart (e.g. for display purposes) and when broadcasting
  37      * them externally (e.g. time synchronization signals).
  38      *
  39      * For example the offset can be calculated as the time of the first time
  40      * value in the current time range to be displayed in the chart. Add +1 to
  41      * avoid 0 when using logarithmic scale.
  42      *
  43      * t0=10000, t2=20000, tn=N -> timeOffset=t0-1 -> t0'=1, t1'=10001,
  44      * tn'=N-timeOffset
  45      *
  46      * where t0 ... tn are times used externally and t0' ... tn' are times used
  47      * internally by the SWT chart.
  48      *
  49      * @return the time offset
  50      */
  51     long getTimeOffset();
  52
  53 }