Document difference between Vector and VectorImage layers

config/jsdoc/api/index.md

@@ -27,6 +27,7 @@
         <a href="module-ol_layer_Tile-TileLayer.html">ol/layer/Tile</a><br>
         <a href="module-ol_layer_Image-ImageLayer.html">ol/layer/Image</a><br>
         <a href="module-ol_layer_Vector-VectorLayer.html">ol/layer/Vector</a><br>
+        <a href="module-ol_layer_VectorImage-VectorImageLayer.html">ol/layer/VectorImage</a><br>
         <a href="module-ol_layer_VectorTile-VectorTileLayer.html">ol/layer/VectorTile</a><br>
         <a href="module-ol_layer_WebGLTile-WebGLTileLayer.html">ol/layer/WebGLTile</a>
       </div>

src/ol/layer/Vector.js

@@ -6,7 +6,11 @@ import CanvasVectorLayerRenderer from '../renderer/canvas/VectorLayer.js';
 
 /**
  * @classdesc
- * Vector data that is rendered client-side.
+ * Vector data is rendered client-side, as vectors. This layer type provides most accurate rendering
+ * even during animations. Points and labels stay upright on rotated views. For very large
+ * amounts of vector data, performance may suffer during pan and zoom animations. In this case,
+ * try {@link module:ol/layer/VectorImage~VectorImageLayer}.
+ *
  * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.

src/ol/layer/VectorImage.js

@@ -49,7 +49,11 @@ import {assign} from '../obj.js';
 
 /**
  * @classdesc
- * Vector data that is rendered client-side.
+ * Vector data is rendered client-side, to an image. This layer type provides great performance
+ * during panning and zooming, but point symbols and texts are always rotated with the view and
+ * pixels are scaled during zoom animations. For more accurate rendering of vector data, use
+ * {@link module:ol/layer/Vector~VectorLayer} instead.
+ *
  * Note that any property set in the options is set as a {@link module:ol/Object~BaseObject}
  * property on the layer object; for example, setting `title: 'My Title'` in the
  * options means that `title` is observable, and has get/set accessors.