Bug 742 HiDPI: Add access to private HiDPI in AWT pixelScale value in JAWTUtil and JAWTWindow
Bug 742 HiDPI: Add prelim HiDPI support to GLJPanel w/o API change and w/o fixing AWTPrintLifecycle DPI evaluation

We also have to re-validating AWTPrintLifecycle's DPI semantics,
since we currently are based on pixel dimension w/ 72 dpi!
Bug 742 HiDPI: [Core API Change] Distinguish window-units and pixel-units; Add HiDPI for AWT GLCanvas w/ OSX CALayer

Core API Change:

To support HiDPI thoroughly in JOGL (NativeWindow, JOGL, NEWT)
we need to separate window- and pixel units.

NativeWindow and NativeSurface now have distinguished
access methods for window units and pixel units.

  NativeWindow: Using window units
      - getWindowWidth()    * NEW Method *
      - getWindowHeight()   * NEW Method *
      - getX(), getY(), ...

  NativeSurface: Using pixel units
      - getWidth()  -> getSurfaceWidth()   * RENAMED *
      - getHeight() -> getSurfaceHeight()  * RENAMED *

  GLDrawable:  Using pixel units
      - getWidth()  -> getSurfaceWidth()   * RENAMED, aligned w/ NativeSurface *
      - getHeight() -> getSurfaceHeight()  * RENAMED, aligned w/ NativeSurface *

Above changes also removes API collision w/ other windowing TK,
e.g. AWT's getWidth()/getHeight() in GLCanvas
and the same method names in GLDrawable before this change.

+++

Now preliminary 'working':
  - AWT GLCanvas
  - AWT GLJPanel

Tested manually on OSX w/ and w/o HiDPI Retina:
  java com.jogamp.opengl.test.junit.jogl.demos.es2.awt.TestGearsES2AWT -manual -noanim -time 1000000
  java com.jogamp.opengl.test.junit.jogl.demos.es2.awt.TestGearsES2GLJPanelAWT -manual -noanim -time 1000000

+++

TODO:
  - NEWT
    - Change Window.setSize(..) to use pixel units ?
    - OSX HiDPI support

  - Testing ..

  - API refinement
Bug 742 HiDPI: [Core API Change] Distinguish window-units and pixel-units: Refine commit f9a00b91dcd146c72a50237b62270f33bd0da98e

- Using comment tag 'FIXME HiDPI' to locate remaining issues

- Fix remaining 'getPixel*(..)' -> 'getSurface*(..)'
  - UpstreamSurfaceHook

- Fix usage (one by one) of
  - NativeWindow: getWindowWidth() / getWindowHeight()
  - NativeSurface/GLDrawable: getSurfaceWidth() / getSurfaceHeight()

- mention window- or pixel units in API doc where required

- use 'setSurfaceSize(..)' where appropriate to match 'getSurface*()'
  - GLFBODrawable
  - GLOffscreenAutoDrawable
  - UpstreamSurfaceHook.MutableSize

- NativeWindow's Point: Add API doc and 'Point scaleInv(..)'

- NativeSurface
  Simplify new conversion methods and use single in-place storage
  - 'int[] getWindowUnitXY(int[], int[])' -> 'int[] convertToWindowUnits(int[], int[])'
  - 'int[] getPixelUnitXY(int[], int[])' -> 'int[] convertToPixelUnits(int[], int[])'

- NEWT Screen/Monitor
  - Assume screen/window units
  - TODO: Refine semantics - Monitor resolution probably is in pixel units ?!
    - Including the Rectangle/Monitor association etc etc

- NEWT Window
  - Add setSurfaceSize(..) for convenience
  - Add 'Point convertToWindowUnits(final Point pixelUnitsAndResult)', etc ..
  - All window ops are using window units (size, pos, ..),
    but methods operating on the surface/drawable: windowRepaint(..) ..

- TODO: Consider changing method names 'window*(..)' to 'surface*(..)'
  actually operating on surface/drawable
  - Window.windowRepaint(..)
  - GLAutoDrawableDelegate.windowResizedOp(..) (maybe all similar methods in here)

- NEWT Mouse/Pointer Events
  - Using pixel units
Bug 742 HiDPI: [Core API Change] Distinguish window-units and pixel-units: Refine commit fb57c652fee6be133990cd7afbbd2fdfc084afaa

- NEWT Screen, Monitor, MonitorMode, ..
  - All Units are in pixel units, not window units!

  - On OSX HiDPI, we report the current scaled monitor resolution,
    instead of the native pixel sized.
    Need to filter out those, i.e. report only native unscaled resolutions,
    since out MonitorMode analogy is per MonitorDevice and not per window!

- Fix usage (one by one) of
   - Screen and Monitor viewport usage
Bug 741 HiDPI: Refine Monitor/Screen [virtual] Viewport Definition / Add NEWT Support / Fix JAWT getPixelScale deadlock

- NativeWindow/Surface/NEWT API DOC: Define Coordinate System of Window and Screen

- OSXUtil: Add getPixelScale(..) via Screen index and 'windowOrView'

- JAWTWindow/JAWTUtil.getPixelScale(..): Use pre-fetched AWT GraphicsConfiguration to solve AWT-TreeLock (deadlock)

- [Virtual] Viewport of MonitorDevice and Screen:
  - Properly calculate and expose [virtual] viewport in window and pixel units
    - OSX Monitor viewports in pixel units are 'reconstructed'
  - Window/Viewport to Monitor selection shall be perfomed via window units (unique)

- OSX NEWT Window create/init (native): Use given size and coordinates even in fullscreen mode
  Don't override by quering NSScreen coordinates, trust given values.

- Fix test cases, i.e. usage of pixel- and window-units
Bug 1012: Fix erroneous handling of multiple monitor coordinates on OSX with NEWT

To properly convert Top-Left (TL) from/to Bottom-Left (BL) coordinates
we need to utilize the given CGDisplay viewport (TL)
and NSScreen (BL) to perform the y-flip.

This is especially true for the case of having multiple monitors
covering different viewports (mixed resolution).
Bug 1013: Fix switching monitor resolution for NEWT Window (content black after) / Bug 741 HiDPI: Update pixelScale after monitor mode change

This seems to be a bug within QUARTZ .. hence this is a workaround

Monitor-Mode-Changed Notification:
  - In case the window is not in fullscreen,
    render it temporary invisible until the mode change is completed.

  - Also update the HiDPI pixel-scale when the mode change is completed.
Bug 1009: Make FBObject's sampling sink format compatible w/ sampling source if possible (ES3 spec requirement)

Make FBObject's sampling sink format compatible w/ sampling source if possible,
i.e. for all GL profiles but ES1 and ES2.

This is an ES3 spec requirement:

For ES3, sampling-sink colorbuffer format must be equal w/
the sampling-source Colorbuffer.

ES3 BlitFramebuffer Requirements: OpenGL ES 3.0.2 p194: 4.3.2  Copying Pixels:

  If SAMPLE_BUFFERS for the read framebuffer is greater than zero, no copy
  is performed and an INVALID_OPERATION error is generated if the formats of
  the read and draw framebuffers are not identical or if the source and destination
  rectangles are not defined with the same (X0, Y 0) and (X1, Y 1) bounds.

Texture and Renderbuffer format details:

ES2 Base iFormat: OpenGL ES 2.0.24 p66: 3.7.1 Texture Image Specification, Table 3.8
 - ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA

ES3 Base iFormat: OpenGL ES 3.0.2 p125: 3.8.3 Texture Image Specification, Table 3.11
 - ALPHA, LUMINANCE, LUMINANCE_ALPHA, RGB, RGBA
   DEPTH_COMPONENT, STENCIL_COMPONENT, RED, RG

ES3 Required Texture and Renderbuffer iFormat: OpenGL ES 3.0.2 p126: 3.8.3 Texture Image Specification
 - RGBA32I, RGBA32UI, RGBA16I, RGBA16UI, RGBA8, RGBA8I,
   RGBA8UI, SRGB8_ALPHA8, RGB10_A2, RGB10_A2UI, RGBA4, and
   RGB5_A1.
 - RGB8 and RGB565.
 - RG32I, RG32UI, RG16I, RG16UI, RG8, RG8I, and RG8UI.
 - R32I, R32UI, R16I, R16UI, R8, R8I, and R8UI.

+++

Our implementation shall attempt to use the same format
for the sampling-source and -sink
wherever possible, e.g. GL2ES3 (excluding ES1 and ES2)!
Bug 1009: Refine test case (Add test06_GL3_Demo0Normal)
Bug 1010 - Fix ES3.glPixelStorei and revalidate GLPixelStorageModes

Remove GLES3Impl.glPixelStorei pname validation which was true for ES2 impl,
but is no more valid for ES3, which accepts more values than
GL_PACK_ALIGNMENT & GL_UNPACK_ALIGNMENT.

Revalidate GLPixelStorageModes:
  - Properly support ES3 PixelStorageModes
  - Revalidate PixelStorageModes for all GL profiles
  - Properly reset values at save
  - Separate PACK and UNPACK save/reset/restore implementation
NewtCanvasSWT: Fixe newtChild NPE; Perform getParentLocationOnScreen() on valid SWT thread (OSX: on main-thread); unclutter updatePosSizeCheck(..)
Bug 741 HiDPI: [Core API Change] Bring back get[Width|Height]() in NativeWindow, i.e. getWindow[Width|Height]() ->  get[Width|Height]()

We have distinguished pixel- and window units in commit f9a00b91dcd146c72a50237b62270f33bd0da98e
and introduced NativeWindow.getWindow[Width|Height]() and NativeSurface.getSurface[Width|Height]().

To have a unique naming scheme, we could rename all method using 'Window',
but for simplicity and since there will be no 'semantic override'
just use the simple version.