org.eclipse.tracecompass.tmf.ui/src/org/eclipse/linuxtools/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.linuxtools.tmf.ui.viewers.xycharts;
  14
  15 import org.eclipse.linuxtools.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  * @since 3.0
  23  */
  24 public interface ITmfChartTimeProvider extends ITmfTimeProvider {
  25
  26     /**
  27      * Returns a constant time offset that is used to normalize the time values
  28      * to a range of 0..53 bits to avoid loss of precision when converting long
  29      * <-> double.
  30      *
  31      * Time values are stored in TMF as long values. The SWT chart library uses
  32      * values of type double (on x and y axis). To avoid loss of precision when
  33      * converting long <-> double the values need to fit within 53 bits.
  34      *
  35      * Subtract the offset when using time values provided externally for
  36      * internal usage in SWT chart. Add the offset when using time values
  37      * provided by SWT chart (e.g. for display purposes) and when broadcasting
  38      * them externally (e.g. time synchronization signals).
  39      *
  40      * For example the offset can be calculated as the time of the first time
  41      * value in the current time range to be displayed in the chart. Add +1 to
  42      * avoid 0 when using logarithmic scale.
  43      *
  44      * t0=10000, t2=20000, tn=N -> timeOffset=t0-1 -> t0'=1, t1'=10001,
  45      * tn'=N-timeOffset
  46      *
  47      * where t0 ... tn are times used externally and t0' ... tn' are times used
  48      * internally by the SWT chart.
  49      *
  50      * @return the time offset
  51      */
  52     long getTimeOffset();
  53
  54 }