gpuweb · kainino0x · Sep 5, 2019 · Aug 22, 2019 · kainino0x · Aug 23, 2019
diff --git a/spec/index.bs b/spec/index.bs
@@ -192,22 +192,45 @@ dictionary GPULimits {
 </script>
 
 
-Buffers {#buffers}
-==================
+# {{GPUBuffer}} # {#GPUBuffer}
 
-## GPUBuffer ## {#buffer}
+A {{GPUBuffer}} represents a block of memory that can be used in GPU operations.
+Data is stored in linear layout, meaning that each byte of the allocation can be
+addressed by its offset from the start of the {{GPUBuffer}}, subject to alignment
+restrictions depending on the operation.
 
-<script type=idl>
-interface GPUBuffer : GPUObjectBase {
-    Promise<ArrayBuffer> mapReadAsync();
-    Promise<ArrayBuffer> mapWriteAsync();
-    void unmap();
+{{GPUBuffer}} has the following internal slots:
 
-    void destroy();
-};
-</script>
+<dl dfn-type=attribute dfn-for="GPUBuffer">
+	: <dfn>\[[size]]</dfn> of type {{GPUBufferSize}}.
+	::
+        The length of the {{GPUBuffer}} allocation in bytes.
 
-### Creation ### {#buffer-creation}
+	: <dfn>\[[usage]]</dfn> of type {{GPUBufferUsageFlags}}.
+	::
+        The allowed usages for this {{GPUBuffer}}.
+
+    : <dfn>\[[state]]</dfn> of type [=buffer state=].
+    ::
+        The current state of the {{GPUBuffer}}.
+</dl>
+
+Each {{GPUBuffer}} has a current <dfn dfn>buffer state</dfn> which is one of the following:
+
+ - "<dfn dfn for="buffer state">mapped</dfn>" where the {{GPUBuffer}} is available for CPU operations.
+ - "<dfn dfn for="buffer state">unmapped</dfn>" where the {{GPUBuffer}} is available for GPU operations.
+ - "<dfn dfn for="buffer state">destroyed</dfn>" where the {{GPUBuffer}} is no longer available for any operations except {{GPUBuffer/destroy}}.
+
+Note:
+{{GPUBuffer/[[size]]}} and {{GPUBuffer/[[usage]]}} are immutable once the {{GPUBuffer}} has been created.
+
+## Creation ## {#buffer-creation}
+
+A {{GPUBuffer}} can be created in the "[=buffer state/unmapped=]" state using the {{GPUDevice}}.{{GPUDevice/createBuffer(descriptor)}} method.
+
+### {{GPUBufferDescriptor}} ### {#GPUBufferDescriptor}
+
+This specifies the options to use in creating a {{GPUBuffer}}.
 
 <script type=idl>
 dictionary GPUBufferDescriptor : GPUObjectDescriptorBase {
@@ -216,6 +239,40 @@ dictionary GPUBufferDescriptor : GPUObjectDescriptorBase {
 };
 </script>
 
+<!-- TODO(kangz): Describe what are the {{device}} [[allowed buffer usages]] -->
+
+<dl dfn-type="abstract-op">
+    : <dfn>validating GPUBufferDescriptor</dfn>(device, descriptor)
+    ::
+        <div algorithm="validation GPUBufferDescriptor(device, descriptor)">
+            1. If device is lost return false.
+            1. If any of the bits of |descriptor|'s {{GPUBufferDescriptor/usage}} aren't present in this device's [[allowed buffer usages]] return false.
+            1. If both the {{GPUBufferUsage/MAP_READ}} and {{GPUBufferUsage/MAP_WRITE}} bits of |descriptor|'s {{GPUBufferDescriptor/usage}} attribute are set, return false.
+            1. Return true.
+        </div>
+</dl>
+
+### {{GPUDevice/createBuffer(descriptor)|GPUDevice.createBuffer(descriptor)}} ### {#GPUDevice-createBuffer}
+
+<dl dfn-type="method" dfn-for="GPUDevice">
+	: <dfn>createBuffer(descriptor)</dfn>
+	::
+		<div algorithm="GPUDevice.createBuffer(descriptor)">
+            1. If the result of [$validating GPUBufferDescriptor$](this, descriptor) is false:
+
+                1. Record a validation error in the current scope.
+                <!-- TODO(kangz): Once we have a description of the error monad, explain what the error buffer is. -->
+                1. Create an error buffer and return the result.
+
+            1. Let |b| be a new {{GPUBuffer}} object.
+            1. Set the {{GPUBuffer/[[size]]}} slot of |b| to the value of the {{GPUBufferDescriptor/size}} attribute of |descriptor|.
+            1. Set the {{GPUBuffer/[[usage]]}} slot of |b| to the value of the {{GPUBufferDescriptor/usage}} attribute of |descriptor|.
+            1. Set the {{GPUBuffer/[[state]]}} internal slot of |b| to `"unmapped"`.
+            1. Set each byte of |b|'s allocation to zero.
+            1. Return |b|.
+        </div>
+</dl>
+
 ## Buffer Usage ## {#buffer-usage}
 
 <script type=idl>
@@ -236,7 +293,16 @@ interface GPUBufferUsage {
 
 ## Buffer Mapping ## {#buffer-mapping}
 
+
 <script type=idl>
+interface GPUBuffer : GPUObjectBase {
+    Promise<ArrayBuffer> mapReadAsync();
+    Promise<ArrayBuffer> mapWriteAsync();
+    void unmap();
+
+    void destroy();
+};
+
 typedef sequence<any> GPUMappedBuffer;
 </script>
 
@@ -1331,3 +1397,9 @@ partial interface GPUDevice {
     attribute EventHandler onuncapturederror;
 };
 </script>
+
+# Temporary usages of non-exported dfns ## {#temp-dfn-usages}
+
+Eventually all of these should disappear but they are useful to avoid warning while building the specification.
+
+[=buffer state/mapped=] [=buffer state/destroyed=]