Add usage guideline comments for custom GL context priority.

ui/gl/gl_context.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef UI_GL_GL_CONTEXT_H_
 #define UI_GL_GL_CONTEXT_H_
 
 #include <memory>
 #include <string>
 #include <vector>
@@ skipping 21 matching lines @@
 class DebugGLApi;
 struct DriverGL;
 class GLApi;
 class GLSurface;
 class GPUTiming;
 class GPUTimingClient;
 struct GLVersionInfo;
 class RealGLApi;
 class TraceGLApi;
 
+// Where available, choose a GL context priority for devices that support it.
+// Currently this requires the EGL_IMG_context_priority extension that is
+// present on Daydream ready Android devices. Default is Medium, and the
+// attribute is ignored if the extension is missing.
+//
+// "High" priority must only be used for special cases with strong realtime
+// requirements, it is incompatible with other critical system GL work such as
+// the GVR library's asynchronous reprojection for VR viewing. Please avoid
+// using it for any GL contexts that may be used during VR presentation,
+// see crbug.com/727800.
+//
+// Instead, consider using "Low" priority for possibly-slow GL work such as
+// user WebGL content.
 enum ContextPriority {
   ContextPriorityLow,
   ContextPriorityMedium,
   ContextPriorityHigh
 };
 
 struct GLContextAttribs {
   GpuPreference gpu_preference = PreferIntegratedGpu;
   bool bind_generates_resource = true;
   bool webgl_compatibility_context = false;
@@ skipping 195 matching lines @@
 // scoped_refptr containing the initialized GLContext or nullptr if
 // initialization fails.
 GL_EXPORT scoped_refptr<GLContext> InitializeGLContext(
     scoped_refptr<GLContext> context,
     GLSurface* compatible_surface,
     const GLContextAttribs& attribs);
 
 }  // namespace gl
 
 #endif  // UI_GL_GL_CONTEXT_H_