1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// @docImport 'dart:developer';
6/// @docImport 'dart:ui';
7///
8/// @docImport 'package:flutter_test/flutter_test.dart';
9///
10/// @docImport 'borders.dart';
11/// @docImport 'box_decoration.dart';
12/// @docImport 'box_shadow.dart';
13/// @docImport 'image_provider.dart';
14/// @docImport 'shader_warm_up.dart';
15/// @docImport 'shape_decoration.dart';
16library;
17
18import 'dart:io';
19import 'dart:ui' show Image, Picture, Size;
20
21import 'package:flutter/foundation.dart';
22
23/// Whether to replace all shadows with solid color blocks.
24///
25/// This is useful when writing golden file tests (see [matchesGoldenFile]) since
26/// the rendering of shadows is not guaranteed to be pixel-for-pixel identical from
27/// version to version (or even from run to run).
28///
29/// This is set to true in [AutomatedTestWidgetsFlutterBinding]. Tests will fail
30/// if they change this value and do not reset it before the end of the test.
31///
32/// When this is set, [BoxShadow.toPaint] acts as if the [BoxShadow.blurStyle]
33/// was [BlurStyle.normal] regardless of the actual specified blur style. This
34/// is compensated for in [BoxDecoration] and [ShapeDecoration] but may need to
35/// be explicitly considered in other situations.
36///
37/// This property should not be changed during a frame (e.g. during a call to
38/// [ShapeBorder.paintInterior] or [ShapeBorder.getOuterPath]); doing so may
39/// cause undefined effects.
40bool debugDisableShadows = false;
41
42/// Signature for a method that returns an [HttpClient].
43///
44/// Used by [debugNetworkImageHttpClientProvider].
45typedef HttpClientProvider = HttpClient Function();
46
47/// Provider from which [NetworkImage] will get its [HttpClient] in debug builds.
48///
49/// If this value is unset, [NetworkImage] will use its own internally-managed
50/// [HttpClient].
51///
52/// This setting can be overridden for testing to ensure that each test receives
53/// a mock client that hasn't been affected by other tests.
54///
55/// This value is ignored in non-debug builds.
56HttpClientProvider? debugNetworkImageHttpClientProvider;
57
58/// Called when the framework is about to paint an [Image] to a [Canvas] with an
59/// [ImageSizeInfo] that contains the decoded size of the image as well as its
60/// output size.
61///
62/// See: [debugOnPaintImage].
63typedef PaintImageCallback = void Function(ImageSizeInfo info);
64
65/// Tracks the bytes used by a [dart:ui.Image] compared to the bytes needed to
66/// paint that image without scaling it.
67@immutable
68class ImageSizeInfo {
69 /// Creates an object to track the backing size of a [dart:ui.Image] compared
70 /// to its display size on a [Canvas].
71 ///
72 /// This class is used by the framework when it paints an image to a canvas
73 /// to report to `dart:developer`'s [postEvent], as well as to the
74 /// [debugOnPaintImage] callback if it is set.
75 const ImageSizeInfo({this.source, required this.displaySize, required this.imageSize});
76
77 /// A unique identifier for this image, for example its asset path or network
78 /// URL.
79 final String? source;
80
81 /// The size of the area the image will be rendered in.
82 final Size displaySize;
83
84 /// The size the image has been decoded to.
85 final Size imageSize;
86
87 /// The number of bytes needed to render the image without scaling it.
88 int get displaySizeInBytes => _sizeToBytes(displaySize);
89
90 /// The number of bytes used by the image in memory.
91 int get decodedSizeInBytes => _sizeToBytes(imageSize);
92
93 int _sizeToBytes(Size size) {
94 // Assume 4 bytes per pixel and that mipmapping will be used, which adds
95 // 4/3.
96 return (size.width * size.height * 4 * (4 / 3)).toInt();
97 }
98
99 /// Returns a JSON encodable representation of this object.
100 Map<String, Object?> toJson() {
101 return <String, Object?>{
102 'source': source,
103 'displaySize': <String, Object?>{'width': displaySize.width, 'height': displaySize.height},
104 'imageSize': <String, Object?>{'width': imageSize.width, 'height': imageSize.height},
105 'displaySizeInBytes': displaySizeInBytes,
106 'decodedSizeInBytes': decodedSizeInBytes,
107 };
108 }
109
110 @override
111 bool operator ==(Object other) {
112 if (other.runtimeType != runtimeType) {
113 return false;
114 }
115 return other is ImageSizeInfo &&
116 other.source == source &&
117 other.imageSize == imageSize &&
118 other.displaySize == displaySize;
119 }
120
121 @override
122 int get hashCode => Object.hash(source, displaySize, imageSize);
123
124 @override
125 String toString() => 'ImageSizeInfo($source, imageSize: $imageSize, displaySize: $displaySize)';
126}
127
128/// If not null, called when the framework is about to paint an [Image] to a
129/// [Canvas] with an [ImageSizeInfo] that contains the decoded size of the
130/// image as well as its output size.
131///
132/// A test can use this callback to detect if images under test are being
133/// rendered with the appropriate cache dimensions.
134///
135/// For example, if a 100x100 image is decoded it takes roughly 53kb in memory
136/// (including mipmapping overhead). If it is only ever displayed at 50x50, it
137/// would take only 13kb if the cacheHeight/cacheWidth parameters had been
138/// specified at that size. This problem becomes more serious for larger
139/// images, such as a high resolution image from a 12MP camera, which would be
140/// 64mb when decoded.
141///
142/// When using this callback, developers should consider whether the image will
143/// be panned or scaled up in the application, how many images are being
144/// displayed, and whether the application will run on multiple devices with
145/// different resolutions and memory capacities. For example, it should be fine
146/// to have an image that animates from thumbnail size to full screen be at
147/// a higher resolution while animating, but it would be problematic to have
148/// a grid or list of such thumbnails all be at the full resolution at the same
149/// time.
150PaintImageCallback? debugOnPaintImage;
151
152/// If true, the framework will color invert and horizontally flip images that
153/// have been decoded to a size taking at least [debugImageOverheadAllowance]
154/// bytes more than necessary.
155///
156/// It will also call [FlutterError.reportError] with information about the
157/// image's decoded size and its display size, which can be used resize the
158/// asset before shipping it, apply `cacheHeight` or `cacheWidth` parameters, or
159/// directly use a [ResizeImage]. Whenever possible, resizing the image asset
160/// itself should be preferred, to avoid unnecessary network traffic, disk space
161/// usage, and other memory overhead incurred during decoding.
162///
163/// Developers using this flag should test their application on appropriate
164/// devices and display sizes for their expected deployment targets when using
165/// these parameters. For example, an application that responsively resizes
166/// images for a desktop and mobile layout should avoid decoding all images at
167/// sizes appropriate for mobile when on desktop. Applications should also avoid
168/// animating these parameters, as each change will result in a newly decoded
169/// image. For example, an image that always grows into view should decode only
170/// at its largest size, whereas an image that normally is a thumbnail and then
171/// pops into view should be decoded at its smallest size for the thumbnail and
172/// the largest size when needed.
173///
174/// This has no effect unless asserts are enabled.
175bool debugInvertOversizedImages = false;
176
177const int _imageOverheadAllowanceDefault = 128 * 1024;
178
179/// The number of bytes an image must use before it triggers inversion when
180/// [debugInvertOversizedImages] is true.
181///
182/// Default is 128kb.
183int debugImageOverheadAllowance = _imageOverheadAllowanceDefault;
184
185/// Returns true if none of the painting library debug variables have been changed.
186///
187/// This function is used by the test framework to ensure that debug variables
188/// haven't been inadvertently changed.
189///
190/// See [the painting library](painting/painting-library.html) for a complete
191/// list.
192///
193/// The `debugDisableShadowsOverride` argument can be provided to override
194/// the expected value for [debugDisableShadows]. (This exists because the
195/// test framework itself overrides this value in some cases.)
196bool debugAssertAllPaintingVarsUnset(String reason, {bool debugDisableShadowsOverride = false}) {
197 assert(() {
198 if (debugDisableShadows != debugDisableShadowsOverride ||
199 debugNetworkImageHttpClientProvider != null ||
200 debugOnPaintImage != null ||
201 debugInvertOversizedImages ||
202 debugImageOverheadAllowance != _imageOverheadAllowanceDefault) {
203 throw FlutterError(reason);
204 }
205 return true;
206 }());
207 return true;
208}
209
210/// The signature of [debugCaptureShaderWarmUpPicture].
211///
212/// Used by tests to run assertions on the [Picture] created by
213/// [ShaderWarmUp.execute]. The return value indicates whether the assertions
214/// pass or not.
215typedef ShaderWarmUpPictureCallback = bool Function(Picture picture);
216
217/// The signature of [debugCaptureShaderWarmUpImage].
218///
219/// Used by tests to run assertions on the [Image] created by
220/// [ShaderWarmUp.execute]. The return value indicates whether the assertions
221/// pass or not.
222typedef ShaderWarmUpImageCallback = bool Function(Image image);
223
224/// Called by [ShaderWarmUp.execute] immediately after it creates a [Picture].
225///
226/// Tests may use this to capture the picture and run assertions on it.
227ShaderWarmUpPictureCallback debugCaptureShaderWarmUpPicture = _defaultPictureCapture;
228bool _defaultPictureCapture(Picture picture) => true;
229
230/// Called by [ShaderWarmUp.execute] immediately after it creates an [Image].
231///
232/// Tests may use this to capture the picture and run assertions on it.
233ShaderWarmUpImageCallback debugCaptureShaderWarmUpImage = _defaultImageCapture;
234bool _defaultImageCapture(Image image) => true;
235

Provided by KDAB

Privacy Policy
Learn more about Flutter for embedded and desktop on industrialflutter.com