001package Torello.Browser.BrowserAPI; 002 003// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 004// Java-HTML Imports 005// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 006 007import Torello.Browser.*; 008import Torello.Browser.helper.*; 009import Torello.Browser.JavaScriptAPI.*; 010import Torello.JSON.*; 011 012import Torello.Java.ReadOnly.ReadOnlyList; 013import Torello.Java.ReadOnly.ReadOnlyArrayList; 014 015import Torello.JavaDoc.Annotations.StaticFunctional; 016import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg; 017 018import Torello.Browser.BrowserAPI.NestedHelpers.Commands.HeadlessExperimental$$Commands; 019 020 021// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 022// JDK Imports 023// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 024 025import javax.json.JsonObject; 026import javax.json.JsonValue; 027 028/** 029 * <SPAN CLASS=COPIEDJDK><B>This domain provides experimental commands only supported in headless mode.</B></SPAN> 030 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE> 031 */ 032@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE") 033public class HeadlessExperimental 034{ 035 // No Pubic Constructors 036 private HeadlessExperimental() { } 037 038 039 040 // ******************************************************************************************** 041 // ******************************************************************************************** 042 // Basic Types 043 // ******************************************************************************************** 044 // ******************************************************************************************** 045 046 047 /** 048 * Encoding options for a screenshot. 049 * 050 * <EMBED CLASS=globalDefs DATA-DOMAIN=HeadlessExperimental DATA-API=BrowserAPI> 051 */ 052 @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_TYPE_JDHBI") 053 public static class ScreenshotParams 054 extends BaseType<ScreenshotParams> 055 implements java.io.Serializable 056 { 057 /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */ 058 protected static final long serialVersionUID = 1; 059 060 private static final NestedHelper<HeadlessExperimental.ScreenshotParams> singleton = 061 Torello.Browser.BrowserAPI.NestedHelpers.Types. 062 HeadlessExperimental$$ScreenshotParams$$.singleton; 063 064 /** 065 * Image compression format (defaults to png). 066 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 067 * <EMBED CLASS='external-html' DATA-D=HeadlessExperimental DATA-C=ScreenshotParams DATA-F=format DATA-FILE-ID=CDP.EL1> 068 * @see BaseType#enumStrList(String) 069 */ 070 public final String format; 071 072 /** 073 * Compression quality from range [0..100] (jpeg and webp only). 074 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 075 */ 076 public final Integer quality; 077 078 /** 079 * Optimize image encoding for speed, not for resulting size (defaults to false) 080 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 081 */ 082 public final Boolean optimizeForSpeed; 083 084 /** Constructor. Please review this class' fields for documentation. */ 085 public ScreenshotParams( 086 ReadOnlyList<Boolean> isPresent, String format, Integer quality, 087 Boolean optimizeForSpeed 088 ) 089 { 090 super(singleton, Domains.HeadlessExperimental, "ScreenshotParams", 3); 091 092 this.format = format; 093 this.quality = quality; 094 this.optimizeForSpeed = optimizeForSpeed; 095 096 this.isPresent = (isPresent == null) 097 ? singleton.generateIsPresentList(this) 098 : THROWS.check(isPresent, 3, "HeadlessExperimental.ScreenshotParams"); 099 } 100 101 /** Creates an instance of this class from a {@link JsonObject}.*/ 102 public static ScreenshotParams fromJSON(JsonObject jo) 103 { return singleton.fromJSON(jo); } 104 105 /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/ 106 public static NestedDescriptor<ScreenshotParams> descriptor() 107 { return singleton.descriptor(); } 108 } 109 110 111 // ******************************************************************************************** 112 // ******************************************************************************************** 113 // Command-Return Types 114 // ******************************************************************************************** 115 // ******************************************************************************************** 116 117 118 /** 119 * Sends a BeginFrame to the target and returns when the frame was completed. Optionally captures a 120 * screenshot from the resulting frame. Requires that the target was created with enabled 121 * BeginFrameControl. Designed for use with --run-all-compositor-stages-before-draw, see also 122 * https://goo.gle/chrome-headless-rendering for more background. 123 * 124 * <EMBED CLASS=globalDefs DATA-DOMAIN=HeadlessExperimental DATA-API=BrowserAPI DATA-CMD=beginFrame> 125 * @see HeadlessExperimental#beginFrame 126 */ 127 @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_CMD_JDHBI") 128 public static class beginFrame$$RET 129 extends BaseType<beginFrame$$RET> 130 implements java.io.Serializable 131 { 132 /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */ 133 protected static final long serialVersionUID = 1; 134 135 private static final NestedHelper<HeadlessExperimental.beginFrame$$RET> singleton = 136 Torello.Browser.BrowserAPI.NestedHelpers.CmdReturns. 137 HeadlessExperimental$$beginFrame$$RET.singleton; 138 139 /** 140 * Whether the BeginFrame resulted in damage and, thus, a new frame was committed to the 141 * display. Reported for diagnostic uses, may be removed in the future. 142 */ 143 public final boolean hasDamage; 144 145 /** 146 * Base64-encoded image data of the screenshot, if one was requested and successfully taken. (Encoded as a base64 string when passed over JSON) 147 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 148 */ 149 public final String screenshotData; 150 151 /** Constructor. Please review this class' fields for documentation. */ 152 public beginFrame$$RET 153 (ReadOnlyList<Boolean> isPresent, boolean hasDamage, String screenshotData) 154 { 155 super(singleton, Domains.HeadlessExperimental, "beginFrame", 2); 156 157 this.hasDamage = hasDamage; 158 this.screenshotData = screenshotData; 159 160 this.isPresent = (isPresent == null) 161 ? singleton.generateIsPresentList(this) 162 : THROWS.check(isPresent, 2, "HeadlessExperimental.beginFrame$$RET"); 163 } 164 165 /** Creates an instance of this class from a {@link JsonObject}.*/ 166 public static beginFrame$$RET fromJSON(JsonObject jo) 167 { return singleton.fromJSON(jo); } 168 169 /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/ 170 public static NestedDescriptor<beginFrame$$RET> descriptor() 171 { return singleton.descriptor(); } 172 } 173 174 175 176 177 // ******************************************************************************************** 178 // ******************************************************************************************** 179 // Commands 180 // ******************************************************************************************** 181 // ******************************************************************************************** 182 183 184 /** 185 * Sends a BeginFrame to the target and returns when the frame was completed. Optionally captures a 186 * screenshot from the resulting frame. Requires that the target was created with enabled 187 * BeginFrameControl. Designed for use with --run-all-compositor-stages-before-draw, see also 188 * https://goo.gle/chrome-headless-rendering for more background. 189 * 190 * @param frameTimeTicks 191 * Timestamp of this BeginFrame in Renderer TimeTicks (milliseconds of uptime). If not set, 192 * the current time will be used. 193 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 194 * 195 * @param interval 196 * The interval between BeginFrames that is reported to the compositor, in milliseconds. 197 * Defaults to a 60 frames/second interval, i.e. about 16.666 milliseconds. 198 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 199 * 200 * @param noDisplayUpdates 201 * Whether updates should not be committed and drawn onto the display. False by default. If 202 * true, only side effects of the BeginFrame will be run, such as layout and animations, but 203 * any visual updates may not be visible on the display or in screenshots. 204 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 205 * 206 * @param screenshot 207 * If set, a screenshot of the frame will be captured and returned in the response. Otherwise, 208 * no screenshot will be captured. Note that capturing a screenshot can fail, for example, 209 * during renderer initialization. In such a case, no screenshot data will be returned. 210 * <BR /><B CLASS=Opt-Top>OPTIONAL</B> 211 * 212 * @return An instance of <CODE>{@link Script}<{@link beginFrame$$RET}></CODE> 213 * 214 * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using 215 * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise} 216 * <CODE><{@link beginFrame$$RET}></CODE> will be returned 217 * 218 * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>, 219 * using {@link Promise#await()}, <I>and the returned result of this Browser Function may 220 * be retrieved.</I> 221 * 222 * <BR /><BR /><DIV CLASS=JDHint> 223 * This Browser Function's {@code Promise} returns:{@link beginFrame$$RET} 224 * A dedicated return type implies that the browser may return more than 1 datum 225 * </DIV> 226 */ 227 public static Script<beginFrame$$RET> beginFrame( 228 Number frameTimeTicks, Number interval, Boolean noDisplayUpdates, 229 ScreenshotParams screenshot 230 ) 231 { 232 // Convert all Method Parameters into a JSON Request-Object (as a String) 233 final String requestJSON = WriteJSON.get( 234 HeadlessExperimental$$Commands.beginFrame$$, "HeadlessExperimental.beginFrame", 235 frameTimeTicks, interval, noDisplayUpdates, screenshot 236 ); 237 238 return new Script<>( 239 Domains.HeadlessExperimental, "beginFrame", requestJSON, 240 beginFrame$$RET::fromJSON, 241 beginFrame$$RET.class 242 ); 243 } 244 245 /** 246 * Disables headless events for the target. 247 * 248 * <BR /><B CLASS=Dep-Top>DEPRECATED</B> 249 * 250 * @return An instance of <CODE>{@link Script}<Void></CODE> 251 * 252 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 253 * browser receives the invocation-request. 254 * 255 * <BR /><BR /><DIV CLASS=JDHint> 256 * This Browser-Function <I>does not have</I> a return-value. You may choose to 257 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 258 * the Browser Function has run to completion. 259 * </DIV> 260 */ 261 public static Script<Void> disable() 262 { 263 // Ultra-Simple Request JSON - Because this method has no parameters 264 final String requestJSON = "{\"method\":\"HeadlessExperimental.disable\"}"; 265 266 return Script.NO_RET(Domains.HeadlessExperimental, "disable", requestJSON); 267 } 268 269 /** 270 * Enables headless events for the target. 271 * 272 * <BR /><B CLASS=Dep-Top>DEPRECATED</B> 273 * 274 * @return An instance of <CODE>{@link Script}<Void></CODE> 275 * 276 * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the 277 * browser receives the invocation-request. 278 * 279 * <BR /><BR /><DIV CLASS=JDHint> 280 * This Browser-Function <I>does not have</I> a return-value. You may choose to 281 * <B STYLE='color: red'>await</B> the {@link Promise}{@code <Void>} to ensure that 282 * the Browser Function has run to completion. 283 * </DIV> 284 */ 285 public static Script<Void> enable() 286 { 287 // Ultra-Simple Request JSON - Because this method has no parameters 288 final String requestJSON = "{\"method\":\"HeadlessExperimental.enable\"}"; 289 290 return Script.NO_RET(Domains.HeadlessExperimental, "enable", requestJSON); 291 } 292 293 294}