diff --git a/files/en-us/web/api/largestcontentfulpaint/index.md b/files/en-us/web/api/largestcontentfulpaint/index.md index 81c21beec76aedd..42b6c0ae5877cf2 100644 --- a/files/en-us/web/api/largestcontentfulpaint/index.md +++ b/files/en-us/web/api/largestcontentfulpaint/index.md @@ -32,38 +32,40 @@ Additional key paint moments are provided by the {{domxref("PerformancePaintTimi To get an accurate measurement of render time for cross-origin resources, set the {{httpheader("Timing-Allow-Origin")}} header. -Developers should use `startTime` instead of `renderTime` as the LCP value, as the `renderTime` may not be set in some browsers. - See [Cross-origin image render time](/en-US/docs/Web/API/LargestContentfulPaint/renderTime#cross-origin_image_render_time) and [Use startTime over renderTime](/en-US/docs/Web/API/LargestContentfulPaint/renderTime#use_starttime_over_rendertime) for more details. ## Instance properties -This interface extends the following {{domxref("PerformanceEntry")}} properties by qualifying and constraining the properties as follows: - -- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `"largest-contentful-paint"`. -- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Always returns an empty string. -- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("LargestContentfulPaint.loadTime", "loadTime")}}. -- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `0`, as `duration` is not applicable to this interface. - -It also supports the following properties: +This interface directly defines the following properties: - {{domxref("LargestContentfulPaint.element")}} {{ReadOnlyInline}} - : The element that is the current largest contentful paint. - {{domxref("LargestContentfulPaint.renderTime")}} {{ReadOnlyInline}} - - : The time the element was rendered to the screen. May be a coarsened value or `0` if the element is a cross-origin image loaded without the `Timing-Allow-Origin` header. + - : The time the element was rendered to the screen. May be a coarsened value if the element is a cross-origin image loaded without the `Timing-Allow-Origin` header. - {{domxref("LargestContentfulPaint.loadTime")}} {{ReadOnlyInline}} - : The time the element was loaded. - {{domxref("LargestContentfulPaint.size")}} {{ReadOnlyInline}} - : The intrinsic size of the element returned as the area (width \* height). - {{domxref("LargestContentfulPaint.id")}} {{ReadOnlyInline}} - : The id of the element. This property returns an empty string when there is no id. +- {{domxref("LargestContentfulPaint.paintTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. +- {{domxref("LargestContentfulPaint.presentationTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen. - {{domxref("LargestContentfulPaint.url")}} {{ReadOnlyInline}} - : If the element is an image, the request url of the image. +It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described: + +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns `"largest-contentful-paint"`. +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns an empty string. +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns the value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}}. +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns `0`, as `duration` is not applicable to this interface. + ## Instance methods _This interface also inherits methods from {{domxref("PerformanceEntry")}}._ @@ -75,7 +77,7 @@ _This interface also inherits methods from {{domxref("PerformanceEntry")}}._ ### Observing the largest contentful paint -In the following example, an observer is registered to get the largest contentful paint while the page is loading. The `buffered` flag is used to access data from before observer creation. +In the following example, a {{domxref("PerformanceObserver")}} is registered to get the largest contentful paint while the page is loading. The `buffered` flag is used to access data from before observer creation. The LCP API analyzes all content it finds (including content that is removed from the DOM). When new largest content is found, it creates a new entry. It stops searching for larger content when scroll or input events occur, since these events likely introduce new content on the website. Thus the LCP is the last performance entry reported by the observer. @@ -89,6 +91,34 @@ const observer = new PerformanceObserver((list) => { observer.observe({ type: "largest-contentful-paint", buffered: true }); ``` +### Observing separate paint and presentation timings + +The `paintTime` and `presentationTime` properties enable you to retrieve specific timings for the paint phase starting and the painted pixels being drawn on the screen. The `paintTime` is broadly interoperable, whereas the `presentationTime` is implementation-dependent. + +This example builds on the earlier observer example, showing how to check for `paintTime` and `presentationTime` support and retrieve those values if they are available. In non-supporting browsers, the code retrieves the `renderTime` or `loadTime`, depending on what is supported. + +```js +const observer = new PerformanceObserver((list) => { + const entries = list.getEntries(); + const lastEntry = entries[entries.length - 1]; // Use the latest LCP candidate + if (lastEntry.presentationTime) { + console.log( + "LCP paintTime:", + lastEntry.paintTime, + "LCP presentationTime:", + lastEntry.presentationTime, + ); + } else if (lastEntry.paintTime) { + console.log("LCP paintTime:", lastEntry.paintTime); + } else if (lastEntry.renderTime) { + console.log("LCP renderTime:", lastEntry.renderTime); + } else { + console.log("LCP loadTime:", lastEntry.loadTime); + } +}); +observer.observe({ type: "largest-contentful-paint", buffered: true }); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/largestcontentfulpaint/painttime/index.md b/files/en-us/web/api/largestcontentfulpaint/painttime/index.md new file mode 100644 index 000000000000000..b608ebb32ce9b63 --- /dev/null +++ b/files/en-us/web/api/largestcontentfulpaint/painttime/index.md @@ -0,0 +1,33 @@ +--- +title: "LargestContentfulPaint: paintTime property" +short-title: paintTime +slug: Web/API/LargestContentfulPaint/paintTime +page-type: web-api-instance-property +browser-compat: api.LargestContentfulPaint.paintTime +--- + +{{APIRef("Performance API")}} + +The **`paintTime`** read-only property of the {{domxref("LargestContentfulPaint")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. + +The `paintTime` is broadly interoperable: The value should be the same across different implementations. + +## Value + +A {{domxref("DOMHighResTimeStamp")}}. + +## Examples + +See [Observing separate paint and presentation timings](/en-US/docs/Web/API/LargestContentfulPaint#observing_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("LargestContentfulPaint.presentationTime")}} diff --git a/files/en-us/web/api/largestcontentfulpaint/presentationtime/index.md b/files/en-us/web/api/largestcontentfulpaint/presentationtime/index.md new file mode 100644 index 000000000000000..01fbebb8a136b4f --- /dev/null +++ b/files/en-us/web/api/largestcontentfulpaint/presentationtime/index.md @@ -0,0 +1,33 @@ +--- +title: "LargestContentfulPaint: presentationTime property" +short-title: presentationTime +slug: Web/API/LargestContentfulPaint/presentationTime +page-type: web-api-instance-property +browser-compat: api.LargestContentfulPaint.presentationTime +--- + +{{APIRef("Performance API")}} + +The **`presentationTime`** read-only property of the {{domxref("LargestContentfulPaint")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen. + +The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it. + +## Value + +A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed. + +## Examples + +See [Observing separate paint and presentation timings](/en-US/docs/Web/API/LargestContentfulPaint#observing_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("LargestContentfulPaint.paintTime")}} diff --git a/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md b/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md index 5aeddcf66cc06c9..3f213e3e9a94024 100644 --- a/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md +++ b/files/en-us/web/api/performance_api/long_animation_frame_timing/index.md @@ -49,6 +49,8 @@ The following is a complete `"long-animation-frame"` performance entry example, entryType: "long-animation-frame", firstUIEventTimestamp: 11801.099999999627, name: "long-animation-frame", + paintTime: 11862.400000000373, + presentationTime: 11863.199999999255, renderStart: 11858.800000000745, scripts: [ { @@ -81,6 +83,10 @@ Beyond the standard data returned by a {{domxref("PerformanceEntry")}} entry, th - : A {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds for which the main thread was blocked from responding to high priority tasks, such as user input. This is calculated by taking all the [long tasks](/en-US/docs/Web/API/PerformanceLongTaskTiming#description) within the LoAF that have a `duration` of more than `50ms`, subtracting `50ms` from each, adding the rendering time to the longest task time, and summing the results. - {{domxref("PerformanceLongAnimationFrameTiming.firstUIEventTimestamp", "firstUIEventTimestamp")}} - : A {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be processed during the current animation frame. Note this timestamp can be before the start of this animation frame if there was a delay between the event happening and it being processed. +- {{domxref("PerformanceLongAnimationFrameTiming.paintTime", "paintTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the animation frame started. +- {{domxref("PerformanceLongAnimationFrameTiming.presentationTime", "presentationTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the UI update was actually drawn on the screen. - {{domxref("PerformanceLongAnimationFrameTiming.renderStart", "renderStart")}} - : A {{domxref("DOMHighResTimeStamp")}} indicating the start time of the rendering cycle, which includes {{domxref("Window.requestAnimationFrame()")}} callbacks, style and layout calculation, {{domxref("ResizeObserver")}} callbacks, and {{domxref("IntersectionObserver")}} callbacks. - {{domxref("PerformanceLongAnimationFrameTiming.styleAndLayoutStart", "styleAndLayoutStart")}} @@ -113,7 +119,7 @@ The timestamps provided in the {{domxref("PerformanceLongAnimationFrameTiming")} | Timing | Calculation | | --------------------------------- | ------------------------------------------------------------------------ | | Start time | `startTime` | -| End time | `startTime + duration` | +| End time | `startTime + duration` (or `paintTime`/`presentationTime`) | | Work duration | `renderStart ? renderStart - startTime : duration` | | Render duration | `renderStart ? (startTime + duration) - renderStart : 0` | | Render: Pre-layout duration | `styleAndLayoutStart ? styleAndLayoutStart - renderStart : 0` | @@ -142,7 +148,8 @@ const observer = new PerformanceObserver((list) => { for (const entry of list.getEntries()) { if (entry.duration > REPORTING_THRESHOLD_MS) { // Example here logs to console; real code could send to analytics endpoint - console.log(entry); + console.log(entry.paintTime); + console.log(entry.presentationTime); } } }); diff --git a/files/en-us/web/api/performanceelementtiming/index.md b/files/en-us/web/api/performanceelementtiming/index.md index 25905e55168ec92..25e75907644d5ec 100644 --- a/files/en-us/web/api/performanceelementtiming/index.md +++ b/files/en-us/web/api/performanceelementtiming/index.md @@ -31,18 +31,7 @@ The author flags an element for observation by adding the [`elementtiming`](/en- ## Instance properties -This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows: - -- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Always returns `0` as `duration` does not apply to this interface. -- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Always returns `"element"`. -- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns `"image-paint"` for images and `"text-paint"` for text. -- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}. - -This interface also supports the following properties: +This interface directly defines the following properties: - {{domxref("PerformanceElementTiming.element")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : An {{domxref("Element")}} representing the element we are returning information about. @@ -58,11 +47,26 @@ This interface also supports the following properties: - : An unsigned 32-bit integer (unsigned long) which is the intrinsic height of the image if this is applied to an image, 0 for text. - {{domxref("PerformanceElementTiming.naturalWidth")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : An unsigned 32-bit integer (unsigned long) which is the intrinsic width of the image if this is applied to an image, 0 for text. +- {{domxref("PerformanceElementTiming.paintTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. +- {{domxref("PerformanceElementTiming.presentationTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the element was actually drawn on the screen. - {{domxref("PerformanceElementTiming.renderTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : A {{domxref("DOMHighResTimeStamp")}} with the renderTime of the element. - {{domxref("PerformanceElementTiming.url")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : A string which is the initial URL of the resources request for images, 0 for text. +It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described: + +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `0` as `duration` does not apply to this interface. +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `"element"`. +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns `"image-paint"` for images and `"text-paint"` for text. +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}. + ## Instance methods - {{domxref("PerformanceElementTiming.toJSON()")}} {{Experimental_Inline}} @@ -90,6 +94,35 @@ observer.observe({ type: "element", buffered: true }); Two entries will be output to the console. The first containing details of the image, the second with details of the text node. +### Observing separate paint and presentation timings + +The `paintTime` and `presentationTime` properties enable you to retrieve specific timings for the paint phase starting and the element being drawn on the screen. The `paintTime` is broadly interoperable, whereas the `presentationTime` is implementation-dependent. + +This example uses a `PerformanceObserver` to observe all performance entries of type `"element"` (remember that, to be observed, elements need to have `elementtiming` attributes set on them). We check for `paintTime` and `presentationTime` support and retrieve those values if they are available. In non-supporting browsers, the code retrieves the `renderTime` or `loadTime`, depending on what is supported. + +```js +const observer = new PerformanceObserver((list) => { + const entries = list.getEntries(); + entries.forEach((entry) => { + if (entry.presentationTime) { + console.log( + "Element paintTime:", + entry.paintTime, + "Element presentationTime:", + entry.presentationTime, + ); + } else if (entry.paintTime) { + console.log("Element paintTime:", entry.paintTime); + } else if (entry.renderTime) { + console.log("Element renderTime:", entry.renderTime); + } else { + console.log("Element loadTime", entry.loadTime); + } + }); +}); +observer.observe({ type: "element", buffered: true }); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/performanceelementtiming/painttime/index.md b/files/en-us/web/api/performanceelementtiming/painttime/index.md new file mode 100644 index 000000000000000..be11dd726d42728 --- /dev/null +++ b/files/en-us/web/api/performanceelementtiming/painttime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceElementTiming: paintTime property" +short-title: paintTime +slug: Web/API/PerformanceElementTiming/paintTime +page-type: web-api-instance-property +browser-compat: api.PerformanceElementTiming.paintTime +--- + +{{APIRef("Performance API")}} + +The **`paintTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. + +The `paintTime` is broadly interoperable: The value should be the same across different implementations. + +## Value + +A {{domxref("DOMHighResTimeStamp")}}. + +## Examples + +See [Observing separate paint and presentation timings](/en-US/docs/Web/API/PerformanceElementTiming#observing_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceElementTiming.presentationTime")}} diff --git a/files/en-us/web/api/performanceelementtiming/presentationtime/index.md b/files/en-us/web/api/performanceelementtiming/presentationtime/index.md new file mode 100644 index 000000000000000..85ef9775a743c0c --- /dev/null +++ b/files/en-us/web/api/performanceelementtiming/presentationtime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceElementTiming: presentationTime property" +short-title: presentationTime +slug: Web/API/PerformanceElementTiming/presentationTime +page-type: web-api-instance-property +browser-compat: api.PerformanceElementTiming.presentationTime +--- + +{{APIRef("Performance API")}} + +The **`presentationTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the element was actually drawn on the screen. + +The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it. + +## Value + +A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed. + +## Examples + +See [Observing separate paint and presentation timings](/en-US/docs/Web/API/PerformanceElementTiming#observing_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceElementTiming.paintTime")}} diff --git a/files/en-us/web/api/performancelonganimationframetiming/index.md b/files/en-us/web/api/performancelonganimationframetiming/index.md index 416bc7f5fccaef9..ddd0c05fcf16e5d 100644 --- a/files/en-us/web/api/performancelonganimationframetiming/index.md +++ b/files/en-us/web/api/performancelonganimationframetiming/index.md @@ -26,23 +26,16 @@ The `PerformanceLongAnimationFrameTiming` interface provides the following granu ## Instance properties -This interface extends the following {{domxref("PerformanceEntry")}} properties for long animation frame performance entries: - -- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time taken in milliseconds to process the LoAF in its entirety. -- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the entry type, which is always `"long-animation-frame"`. -- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns the entry name, which is always `"long-animation-frame"`. -- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time when the animation frame started. - -This interface also supports the following properties: +This interface directly defines the following properties: - {{domxref("PerformanceLongAnimationFrameTiming.blockingDuration")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the total time in milliseconds that the main thread was blocked from responding to high priority tasks, such as user input. This is calculated by taking all the [long tasks](/en-US/docs/Web/API/PerformanceLongTaskTiming#description) within the LoAF that have a `duration` of more than `50ms`, subtracting `50ms` from each, adding the rendering time to the longest task time, and summing the results. - {{domxref("PerformanceLongAnimationFrameTiming.firstUIEventTimestamp")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the time of the first UI event — such as a mouse or keyboard event — to be queued during the current animation frame. +- {{domxref("PerformanceLongAnimationFrameTiming.paintTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the animation frame started. +- {{domxref("PerformanceLongAnimationFrameTiming.presentationTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the UI update was actually drawn on the screen. - {{domxref("PerformanceLongAnimationFrameTiming.renderStart")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the start time of the rendering cycle, which includes {{domxref("Window.requestAnimationFrame()")}} callbacks, style and layout calculation, {{domxref("ResizeObserver")}} callbacks, and {{domxref("IntersectionObserver")}} callbacks. - {{domxref("PerformanceLongAnimationFrameTiming.scripts")}} {{ReadOnlyInline}} {{Experimental_Inline}} @@ -50,6 +43,17 @@ This interface also supports the following properties: - {{domxref("PerformanceLongAnimationFrameTiming.styleAndLayoutStart")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMHighResTimeStamp")}} indicating the beginning of the time period spent in style and layout calculations for the current animation frame. +It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described: + +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time taken in milliseconds to process the LoAF in its entirety. +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns the entry type, which is always `"long-animation-frame"`. +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns the entry name, which is always `"long-animation-frame"`. +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time when the animation frame started. + ## Instance methods - {{domxref("PerformanceLongAnimationFrameTiming.toJSON()")}} {{Experimental_Inline}} diff --git a/files/en-us/web/api/performancelonganimationframetiming/painttime/index.md b/files/en-us/web/api/performancelonganimationframetiming/painttime/index.md new file mode 100644 index 000000000000000..397bb45e5f53990 --- /dev/null +++ b/files/en-us/web/api/performancelonganimationframetiming/painttime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceLongAnimationFrameTiming: paintTime property" +short-title: paintTime +slug: Web/API/PerformanceLongAnimationFrameTiming/paintTime +page-type: web-api-instance-property +browser-compat: api.PerformanceLongAnimationFrameTiming.paintTime +--- + +{{APIRef("Performance API")}} + +The **`paintTime`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the animation frame started. + +The `paintTime` is broadly interoperable: The value should be the same across different implementations. + +## Value + +A {{domxref("DOMHighResTimeStamp")}}. + +## Examples + +See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceLongAnimationFrameTiming.presentationTime")}} diff --git a/files/en-us/web/api/performancelonganimationframetiming/presentationtime/index.md b/files/en-us/web/api/performancelonganimationframetiming/presentationtime/index.md new file mode 100644 index 000000000000000..8c2850bc7f67977 --- /dev/null +++ b/files/en-us/web/api/performancelonganimationframetiming/presentationtime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceLongAnimationFrameTiming: presentationTime property" +short-title: presentationTime +slug: Web/API/PerformanceLongAnimationFrameTiming/presentationTime +page-type: web-api-instance-property +browser-compat: api.PerformanceLongAnimationFrameTiming.presentationTime +--- + +{{APIRef("Performance API")}} + +The **`presentationTime`** read-only property of the {{domxref("PerformanceLongAnimationFrameTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the UI update was actually drawn on the screen. + +The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it. + +## Value + +A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed. + +## Examples + +See [Long animation frame timing](/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing#examples) for examples related to the Long Animation Frames API. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceLongAnimationFrameTiming.paintTime")}} diff --git a/files/en-us/web/api/performancepainttiming/index.md b/files/en-us/web/api/performancepainttiming/index.md index 89da6cf75603dc8..30583ef1317496b 100644 --- a/files/en-us/web/api/performancepainttiming/index.md +++ b/files/en-us/web/api/performancepainttiming/index.md @@ -26,7 +26,14 @@ Like other Performance APIs, this API extends {{domxref("PerformanceEntry")}}. ## Instance properties -This interface has no properties but it extends the following {{domxref("PerformanceEntry")}} properties by qualifying and constraining the properties as follows: +This interface directly defines the following properties: + +- {{domxref("PerformancePaintTiming.paintTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. +- {{domxref("PerformancePaintTiming.presentationTime")}} + - : Returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen. + +It also extends the following {{domxref("PerformanceEntry")}} properties, qualifying and constraining them as described: - {{domxref("PerformanceEntry.entryType")}} - : Returns `"paint"`. @@ -44,7 +51,7 @@ This interface has no properties but it extends the following {{domxref("Perform ## Examples -### Getting paint timings +### Getting basic paint timings Example using a {{domxref("PerformanceObserver")}}, which notifies of new `paint` performance entries as they are recorded in the browser's performance timeline. Use the `buffered` option to access entries from before the observer creation. @@ -73,6 +80,30 @@ entries.forEach((entry) => { }); ``` +### Getting separate paint and presentation timings + +The `paintTime` and `presentationTime` properties enable you to retrieve specific timings for the paint phase starting and the painted pixels being drawn on the screen. The `paintTime` is broadly interoperable, whereas the `presentationTime` is implementation-dependent. + +This example builds on the earlier {{domxref("Performance.getEntriesByType()")}} example, showing how to check for `paintTime` and `presentationTime` support and retrieve those values if they are available. In non-supporting browsers, the code retrieves the `loadTime`. + +```js +const entries = performance.getEntriesByType("paint"); +entries.forEach((entry) => { + if (entry.presentationTime) { + console.log( + "paintTime:", + entry.paintTime, + "presentationTime:", + entry.presentationTime, + ); + } else if (entry.paintTime) { + console.log("paintTime:", entry.paintTime); + } else { + console.log("loadTime", entry.loadTime); + } +}); +``` + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/performancepainttiming/painttime/index.md b/files/en-us/web/api/performancepainttiming/painttime/index.md new file mode 100644 index 000000000000000..219359e7a7429cb --- /dev/null +++ b/files/en-us/web/api/performancepainttiming/painttime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformancePaintTiming: paintTime property" +short-title: paintTime +slug: Web/API/PerformancePaintTiming/paintTime +page-type: web-api-instance-property +browser-compat: api.PerformancePaintTiming.paintTime +--- + +{{APIRef("Performance API")}} + +The **`paintTime`** read-only property of the {{domxref("PerformancePaintTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the rendering phase ended and the paint phase started. + +The `paintTime` is broadly interoperable: The value should be the same across different implementations. + +## Value + +A {{domxref("DOMHighResTimeStamp")}}. + +## Examples + +See [Getting separate paint and presentation timings](/en-US/docs/Web/API/PerformancePaintTiming#getting_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformancePaintTiming.presentationTime")}} diff --git a/files/en-us/web/api/performancepainttiming/presentationtime/index.md b/files/en-us/web/api/performancepainttiming/presentationtime/index.md new file mode 100644 index 000000000000000..03afa9af5a10e43 --- /dev/null +++ b/files/en-us/web/api/performancepainttiming/presentationtime/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformancePaintTiming: presentationTime property" +short-title: presentationTime +slug: Web/API/PerformancePaintTiming/presentationTime +page-type: web-api-instance-property +browser-compat: api.PerformancePaintTiming.presentationTime +--- + +{{APIRef("Performance API")}} + +The **`presentationTime`** read-only property of the {{domxref("PerformancePaintTiming")}} interface returns the {{domxref("DOMHighResTimeStamp","timestamp")}} when the painted pixels were actually drawn on the screen. + +The `presentationTime` is optional — some browsers may choose always to return `0` or not to expose the value at all. The value is also implementation-dependent — it may differ across browsers that choose to expose it. + +## Value + +A {{domxref("DOMHighResTimeStamp")}} or {{jsxref("Operators/null", "null")}} if the value is not exposed. + +## Examples + +See [Getting separate paint and presentation timings](/en-US/docs/Web/API/PerformancePaintTiming#getting_separate_paint_and_presentation_timings). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformancePaintTiming.paintTime")}}