com.jogamp.newt

## Class MonitorMode

- java.lang.Object
- - com.jogamp.newt.MonitorMode

- All Implemented Interfaces:
    Comparable<MonitorMode>

      public class MonitorMode
      extends Object
      implements Comparable<MonitorMode>

  Immutable MonitorMode Class, consisting of it's read only components:
  - nativeId
  - `MonitorMode.SizeAndRRate`, consist out of non rotated `surface size`, `refresh rate` and `flags`.
  - `rotation`, measured counter clockwise (CCW)
  Aquire and filter MonitorMode
  - `MonitorDevice` Selection:
    - A List of all `MonitorDevice`s is accessible via `Screen.getMonitorDevices()`.
    - The main monitor used by a windows is accessible via `Window.getMainMonitor()`.
    - The main monitor covering an arbitrary rectangle is accessible via `Screen.getMainMonitor(RectangleImmutable)`.
  - The current MonitorMode can be obtained via `MonitorDevice.getCurrentMode()`.
  - The original MonitorMode can be obtained via `MonitorDevice.getOriginalMode()`.
  - `MonitorMode` Filtering:
    - A `MonitorDevice`'s MonitorModes is accessible via `MonitorDevice.getSupportedModes()`.
    - You may utilize `MonitorModeUtil` to filter and select a desired MonitorMode.
  Changing MonitorMode
  - Use `MonitorDevice.setCurrentMode(MonitorMode)` to change the current MonitorMode for all `Screen`s referenced via the `full qualified name (FQN)`.
  - The `original mode` is restored when
    - the last FQN referenced Screen closes.
    - the JVM shuts down.
  Example for changing the MonitorMode:

              // Pick the monitor:
              // Either the one used by a window ..
              MonitorDevice monitor = window.getMainMonitor();

              // Or arbitrary from the list ..
              List allMonitor = getMonitorDevices();
              MonitorDevice monitor = allMonitor.get(0);

              // Current and original modes ..
              MonitorMode mmCurrent = monitor.queryCurrentMode();
              MonitorMode mmOrig = monitor.getOriginalMode();

              // Target resolution in pixel units
              DimensionImmutable res = new Dimension(800, 600);

              // Target refresh rate shall be similar to current one ..
              float freq = mmCurrent.getRefreshRate();

              // Target rotation shall be similar to current one
              int rot = mmCurrent.getRotation();

              // Filter criterias sequential out of all available MonitorMode of the chosen MonitorDevice
              List monitorModes = monitor.getSupportedModes();
              monitorModes = MonitorModeUtil.filterByFlags(monitorModes, 0); // no interlace, double-scan etc
              monitorModes = MonitorModeUtil.filterByRotation(monitorModes, rot);
              monitorModes = MonitorModeUtil.filterByResolution(monitorModes, res);
              monitorModes = MonitorModeUtil.filterByRate(monitorModes, freq);
              monitorModes = MonitorModeUtil.getHighestAvailableBpp(monitorModes);

              // pick 1st one and set to current ..
              MonitorMode mm = monitorModes.get(0);
              monitor.setCurrentMode(mm);

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MonitorMode.SizeAndRRate` Immutable surfaceSize, flags and refreshRate Class, consisting of it's read only components: nativeId `SurfaceSize` surface memory size `flags` `refresh rate`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `FLAG_DOUBLESCAN` Lines are doubled.
    `static int` | `FLAG_INTERLACE` Frame is split into two fields.
    `static Comparator<MonitorMode>` | `monitorModeComparator` Comparator for 2 `MonitorMode`s, following comparison order as described in `compareTo(MonitorMode)`, returning the ascending order.
    `static Comparator<MonitorMode>` | `monitorModeComparatorInv` Comparator for 2 `MonitorMode`s, following comparison order as described in `compareTo(MonitorMode)`, returning the descending order.
    `static int` | `ROTATE_0` zero rotation, compared to normal settings
    `static int` | `ROTATE_180` 180 degrees CCW rotation
    `static int` | `ROTATE_270` 270 degrees CCW rotation
    `static int` | `ROTATE_90` 90 degrees CCW rotation

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MonitorMode(int nativeId, MonitorMode.SizeAndRRate sizeAndRRate, int rotation)`
    `MonitorMode(SurfaceSize surfaceSize, float refreshRate, int flags, int rotation)` Creates a user instance w/o `identity` to filter our matching modes w/ identity.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(MonitorMode mm)` Compares `sizeAndRRate` 1st, then `rotation`.
    `boolean` | `equals(Object obj)` Tests equality of two `MonitorMode` objects by evaluating equality of it's components: `nativeId` `sizeAndRRate` `rotation`
    `int` | `getFlags()` Returns bitfield w/ flags, i.e.
    `int` | `getId()`
    `float` | `getRefreshRate()` Returns the vertical refresh rate.
    `int` | `getRotatedHeight()` Returns the rotated screen height in pixel units, derived from `getMonitorMode().getSurfaceSize().getResolution()` and `getRotation()`
    `int` | `getRotatedWidth()` Returns the rotated screen width in pixel units, derived from `getMonitorMode().getSurfaceSize().getResolution()` and `getRotation()`
    `int` | `getRotation()` Returns the CCW rotation of this mode
    `MonitorMode.SizeAndRRate` | `getSizeAndRRate()` Returns the surfaceSize and refreshRate instance.
    `SurfaceSize` | `getSurfaceSize()` Returns the unrotated `SurfaceSize`
    `int` | `hashCode()` Returns a combined hash code of it's elements: `nativeId` `sizeAndRRate` `rotation`
    `static boolean` | `isRotationValid(int rotation)`
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### monitorModeComparator

          public static final Comparator<MonitorMode> monitorModeComparator

      Comparator for 2 `MonitorMode`s, following comparison order as described in `compareTo(MonitorMode)`, returning the ascending order.

    - #### monitorModeComparatorInv

          public static final Comparator<MonitorMode> monitorModeComparatorInv

      Comparator for 2 `MonitorMode`s, following comparison order as described in `compareTo(MonitorMode)`, returning the descending order.

    - #### ROTATE_0

          public static final int ROTATE_0

      zero rotation, compared to normal settings
      See Also:
        Constant Field Values

    - #### ROTATE_90

          public static final int ROTATE_90

      90 degrees CCW rotation
      See Also:
        Constant Field Values

    - #### ROTATE_180

          public static final int ROTATE_180

      180 degrees CCW rotation
      See Also:
        Constant Field Values

    - #### ROTATE_270

          public static final int ROTATE_270

      270 degrees CCW rotation
      See Also:
        Constant Field Values

    - #### FLAG_INTERLACE

          public static final int FLAG_INTERLACE

      Frame is split into two fields. See `getFlags()`.
      See Also:
        Constant Field Values

    - #### FLAG_DOUBLESCAN

          public static final int FLAG_DOUBLESCAN

      Lines are doubled. See `getFlags()`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MonitorMode

          public MonitorMode(int nativeId,
                     MonitorMode.SizeAndRRate sizeAndRRate,
                     int rotation)

      Parameters:
        `sizeAndRRate` - the surface size and refresh rate mode
        `rotation` - the screen rotation, measured counter clockwise (CCW)

    - #### MonitorMode

          public MonitorMode(SurfaceSize surfaceSize,
                     float refreshRate,
                     int flags,
                     int rotation)

      Creates a user instance w/o `identity` to filter our matching modes w/ identity.

      See `MonitorModeUtil` for filter utilities.

      Parameters:
        `surfaceSize` -
        `refreshRate` -
        `flags` -
        `rotation` -

  - ### Method Detail

    - #### isRotationValid

          public static boolean isRotationValid(int rotation)

    - #### getId

          public final int getId()

      Returns:
        the immutable native Id of this mode, may not be unique, may be 0.

    - #### getSizeAndRRate

          public final MonitorMode.SizeAndRRate getSizeAndRRate()

      Returns the surfaceSize and refreshRate instance.

    - #### getSurfaceSize

          public final SurfaceSize getSurfaceSize()

      Returns the unrotated `SurfaceSize`

    - #### getRefreshRate

          public final float getRefreshRate()

      Returns the vertical refresh rate.

    - #### getFlags

          public final int getFlags()

      Returns bitfield w/ flags, i.e. `FLAG_DOUBLESCAN`, `FLAG_INTERLACE`, ..

    - #### getRotation

          public final int getRotation()

      Returns the CCW rotation of this mode

    - #### getRotatedWidth

          public final int getRotatedWidth()

      Returns the rotated screen width in pixel units, derived from `getMonitorMode().getSurfaceSize().getResolution()` and `getRotation()`

    - #### getRotatedHeight

          public final int getRotatedHeight()

      Returns the rotated screen height in pixel units, derived from `getMonitorMode().getSurfaceSize().getResolution()` and `getRotation()`

    - #### toString

          public final String toString()

      Overrides:
        `toString` in class `Object`

    - #### compareTo

          public int compareTo(MonitorMode mm)

      Compares `sizeAndRRate` 1st, then `rotation`.

      Rotation is compared inverted, i.e. `360 - rotation`, so the lowest rotation reflects a higher value.

      Order of comparing MonitorMode:

      - resolution
      - bits per pixel
      - flags
      - refresh rate
      - rotation
      Specified by:
        `compareTo` in interface `Comparable<MonitorMode>`

    - #### equals

          public final boolean equals(Object obj)

      Tests equality of two `MonitorMode` objects by evaluating equality of it's components:
      - `nativeId`
      - `sizeAndRRate`
      - `rotation`
      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public final int hashCode()

      Returns a combined hash code of it's elements:
      - `nativeId`
      - `sizeAndRRate`
      - `rotation`
      Overrides:
        `hashCode` in class `Object`

Copyright 2010 JogAmp Community.