src/main/proto/search/now/ui/piet/images.proto

// Copyright 2018 The Feed Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package search.now.ui.piet;

option optimize_for=LITE_RUNTIME;

import "src/main/proto/search/now/ui/piet/media_queries.proto";

option java_package = "com.google.search.now.ui.piet";
option java_outer_classname = "ImagesProto";
option cc_enable_arenas = true;

// An image asset.
message Image {
  // Image sources are `repeated` so that a feature author can specify multiple
  // image sources in the order that they should be attempted to be fetched.
  // Clients can go through the list until they find one they wish to fetch,
  // based either on the type of URL (e.g. `https://` versus `asset://`) or
  // based on the size of the raw image (e.g. 1x DPI or 2x DPI). Feature
  // authors are responsible for ensuring that at least one image source is
  // valid and accessible (https://gstatic.com URLs are recommended as the
  // ultimate fallback).
  // See [INTERNAL LINK] for more details on Image handling.
  repeated ImageSource sources = 1;

  // The type of scaling to apply.
  enum ScaleType {
    // When scale type is unspecified, we err on the side of preserving all
    // areas of the image, so this is equivalent to CENTER_INSIDE.
    SCALE_TYPE_UNSPECIFIED = 0;

    // Scale the image uniformly such that width or height will be equal to the
    // size of its view. The image will not be cropped.
    CENTER_INSIDE = 1;

    // Scale the image uniformly to fill its view. Some portion of the image
    // will be cropped.
    CENTER_CROP = 2;
  }

  // Reserved tags from deprecated fields
  reserved 2, 3;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;
}

// A single physical image, as contained in a single image file or embedded
// resource. To accommodate devices with varying Device Pixel Ratios, each image
// in a different DPI bucket can be represented as a separate `ImageSource`.
// E.g. the same image can be offered as multiple resources as:
//     ImageSource{
//       url="ic_icon_24@1x.png",
//       width=24,
//       height=24
//     }
// and:
//     ImageSource{
//       url="ic_icon_24@2x.png",
//       width=48,
//       height=48
//     }
// This enables clients to choose which image to fetch based on the expected
// width and height, without actually having to fetch it first.
// These dimensions also allow clients to pre-size the view for the image before
// it loads so that the view's size doesn't change once the image is loaded.
message ImageSource {
  // URLs can be "https://" or "asset://".
  // HTTPS URLs can be fetched by a regular network communication library.
  // Asset URLs can be fetched by implementation-specific asset helpers.
  // Asset URLs must be specified in an implementation-agnostic manner.
  // If missing, ERR_IMAGE_URL_EMPTY is raised.
  optional string url = 1;

  // This ImageSource is only eligible to be used if *all* the conditions
  // enumerated below are met. If even one condition is unsatisfied, this
  // ImageSource is skipped, and Piet will pick another image. It is recommended
  // to include at least one ImageSource that is loaded unconditionally.
  repeated MediaQueryCondition conditions = 2;

  // The intrinsic width of this image, expressed in raw pixels. This may be
  // different from the width of the container in which this image should be
  // displayed. This can be used for pre-allocating space for the image before
  // it loads. It is expected that the server will usually provide this field.
  optional int32 width_px = 4;

  // The intrinsic height of this image, expressed in raw pixels. This may be
  // different from the height of the container in which this image should be
  // displayed. This can be used for pre-allocating space for the image before
  // it loads. It is expected that the server will usually provide this field.
  optional int32 height_px = 5;
}