[Exposed=(Window,Worker), Serializable, Transferable]
interface ImageBitmap {
readonly attribute unsigned long width;
readonly attribute unsigned long height;
void close();
};
typedef (CanvasImageSource or
Blob or
ImageData) ImageBitmapSource;
enum ImageOrientation { "none", "flipY" };
enum PremultiplyAlpha { "none", "premultiply", "default" };
enum ColorSpaceConversion { "none", "default" };
enum ResizeQuality { "pixelated", "low", "medium", "high" };
dictionary ImageBitmapOptions {
ImageOrientation imageOrientation = "none";
PremultiplyAlpha premultiplyAlpha = "default";
ColorSpaceConversion colorSpaceConversion = "default";
[EnforceRange] unsigned long resizeWidth;
[EnforceRange] unsigned long resizeHeight;
ResizeQuality resizeQuality = "low";
};
An
ImageBitmap
object
represents
a
bitmap
image
that
can
be
painted
to
a
canvas
without
undue
latency.
The exact judgement of what is undue latency of this is left up to the implementer, but in general if making use of the bitmap requires network I/O, or even local disk I/O, then the latency is probably undue; whereas if it only requires a blocking read from a GPU or system RAM, the latency is probably acceptable.
createImageBitmap
(
image
[,
options
])
createImageBitmap
(
image
,
sx
,
sy
,
sw
,
sh
[,
options
])
Takes
image
,
which
can
be
an
img
element,
an
SVG
image
element,
a
video
element,
a
canvas
element,
a
Blob
object,
an
ImageData
object,
or
another
ImageBitmap
object,
and
returns
a
promise
that
is
resolved
when
a
new
ImageBitmap
is
created.
If
no
ImageBitmap
object
can
be
constructed,
for
example
because
the
provided
image
data
is
not
actually
an
image,
then
the
promise
is
rejected
instead.
If sx , sy , sw , and sh arguments are provided, the source image is cropped to the given pixels, with any pixels missing in the original replaced by transparent black . These coordinates are in the source image's pixel coordinate space, not in CSS pixels .
If
options
is
provided,
the
ImageBitmap
object's
bitmap
data
is
modified
according
to
options
.
For
example,
if
the
premultiplyAlpha
option
is
set
to
"
premultiply
",
the
bitmap
data
's
color
channels
are
premultiplied
by
its
alpha
channel.
Rejects
the
promise
with
an
"
InvalidStateError
"
DOMException
if
the
source
image
is
not
in
a
valid
state
(e.g.,
an
img
element
that
hasn't
loaded
successfully,
an
ImageBitmap
object
whose
[[Detached]]
internal
slot
value
is
true,
an
ImageData
object
whose
data
attribute
value's
[[ViewedArrayBuffer]]
internal
slot
is
detached,
or
a
Blob
whose
data
cannot
be
interpreted
as
a
bitmap
image).
Rejects
the
promise
with
a
"
SecurityError
"
DOMException
if
the
script
is
not
allowed
to
access
the
image
data
of
the
source
image
(e.g.
a
video
that
is
CORS-cross-origin
,
or
a
canvas
being
drawn
on
by
a
script
in
a
worker
from
another
origin
).
close
()
Releases imageBitmap 's underlying bitmap data .
width
Returns the intrinsic width of the image, in CSS pixels .
height
Returns the intrinsic height of the image, in CSS pixels .
An
ImageBitmap
object
whose
[[Detached]]
internal
slot
value
is
false
always
has
associated
bitmap
data
,
with
a
width
and
a
height.
However,
it
is
possible
for
this
data
to
be
corrupted.
If
an
ImageBitmap
object's
media
data
can
be
decoded
without
errors,
it
is
said
to
be
fully
decodable
.
An
ImageBitmap
object's
bitmap
has
an
origin-clean
flag,
which
indicates
whether
the
bitmap
is
tainted
by
content
from
a
different
origin
.
The
flag
is
initially
set
to
true
and
may
be
changed
to
false
by
the
steps
of
createImageBitmap()
.
ImageBitmap
objects
are
serializable
objects
and
transferable
objects
.
Their serialization steps , given value and serialized , are:
Set serialized .[[BitmapData]] to a copy of value 's bitmap data .
Set serialized .[[OriginClean]] to true if value 's origin-clean flag is set, and false otherwise.
Their deserialization steps , given serialized and value , are:
Set value 's bitmap data to serialized .[[BitmapData]].
If serialized .[[OriginClean]] is true, set value 's origin-clean flag.
Their transfer steps , given value and dataHolder , are:
Set dataHolder .[[BitmapData]] to value 's bitmap data .
Set dataHolder .[[OriginClean]] to true if value 's origin-clean flag is set, and false otherwise.
Unset value 's bitmap data .
Their transfer-receiving steps , given dataHolder and value , are:
Set value 's bitmap data to dataHolder .[[BitmapData]].
If dataHolder .[[OriginClean]] is true, set value 's origin-clean flag.
The
createImageBitmap(
image
,
options
)
and
createImageBitmap(
image
sx
,
sy
,
sw
,
sh
,
options
)
methods,
when
invoked,
must
run
these
steps:
Support: createimagebitmap Chrome for Android 67+ Chrome 59+ iOS Safari None UC Browser for Android 11.8+ Firefox 42+ IE None Opera Mini None Safari None Edge None Samsung Internet 6.2+ Opera 46+ Android Browser 67+
Source: caniuse.com
Let p be a new promise.
If
either
sw
or
sh
is
given
and
is
0,
then
return
p
rejected
with
a
RangeError
.
If
either
options
's
resizeWidth
or
options
's
resizeHeight
is
present
and
is
0,
then
return
p
rejected
with
an
"
InvalidStateError
"
DOMException
.
Check
the
usability
of
the
image
argument
.
If
this
throws
an
exception
or
returns
bad
,
then
return
p
rejected
with
an
"
InvalidStateError
"
DOMException
.
Let
imageBitmap
be
a
new
ImageBitmap
object.
Switch on image :
img
image
If
image
's
media
data
has
no
intrinsic
dimensions
(e.g.,
it's
a
vector
graphic
with
no
specified
content
size)
and
either
options
's
resizeWidth
or
options
's
resizeHeight
is
not
present,
then
return
p
rejected
with
an
"
InvalidStateError
"
DOMException
.
If
image
's
media
data
has
no
intrinsic
dimensions
(e.g.,
it's
a
vector
graphics
with
no
specified
content
size),
it
should
be
rendered
to
a
bitmap
of
the
size
specified
by
the
resizeWidth
and
the
resizeHeight
options.
Set imageBitmap 's bitmap data to a copy of image 's media data, cropped to the source rectangle with formatting . If this is an animated image, imageBitmap 's bitmap data must only be taken from the default image of the animation (the one that the format defines is to be used when animation is not supported or is disabled), or, if there is no such image, the first frame of the animation.
If the origin of image 's image is not same origin with entry settings object 's origin , then set the origin-clean flag of imageBitmap 's bitmap to false.
Run this step in parallel :
Resolve p with imageBitmap .
video
If
image
's
networkState
attribute
is
NETWORK_EMPTY
,
then
return
p
rejected
with
an
"
InvalidStateError
"
DOMException
.
Set imageBitmap 's bitmap data to a copy of the frame at the current playback position , at the media resource 's intrinsic width and intrinsic height (i.e., after any aspect-ratio correction has been applied), cropped to the source rectangle with formatting .
If the origin of image 's video is not same origin with entry settings object 's origin , then set the origin-clean flag of imageBitmap 's bitmap to false.
Run this step in parallel :
Resolve p with imageBitmap .
canvas
Set imageBitmap 's bitmap data to a copy of image 's bitmap data , cropped to the source rectangle with formatting .
Set the origin-clean flag of the imageBitmap 's bitmap to the same value as the origin-clean flag of image 's bitmap.
Run this step in parallel :
Resolve p with imageBitmap .
Blob
Run these step in parallel :
Let
imageData
be
the
result
of
reading
image
's
data.
If
an
error
occurs
during
reading
of
the
object
,
then
reject
p
with
an
"
InvalidStateError
"
DOMException
and
abort
these
steps.
Apply
the
image
sniffing
rules
to
determine
the
file
format
of
imageData
,
with
MIME
type
of
image
(as
given
by
image
's
type
attribute)
giving
the
official
type.
If
imageData
is
not
in
a
supported
image
file
format
(e.g.,
it's
not
an
image
at
all),
or
if
imageData
is
corrupted
in
some
fatal
way
such
that
the
image
dimensions
cannot
be
obtained
(e.g.,
a
vector
graphic
with
no
intrinsic
size),
then
reject
p
with
an
"
InvalidStateError
"
DOMException
and
abort
these
steps.
Set imageBitmap 's bitmap data to imageData , cropped to the source rectangle with formatting . If this is an animated image, imageBitmap 's bitmap data must only be taken from the default image of the animation (the one that the format defines is to be used when animation is not supported or is disabled), or, if there is no such image, the first frame of the animation.
Resolve p with imageBitmap .
ImageData
Let
buffer
be
image
's
data
attribute
value's
[[ViewedArrayBuffer]]
internal
slot.
If
IsDetachedBuffer
(
buffer
)
is
true,
then
return
p
rejected
with
an
"
InvalidStateError
"
DOMException
.
Set imageBitmap 's bitmap data to image 's image data, cropped to the source rectangle with formatting .
Run this step in parallel :
Resolve p with imageBitmap .
ImageBitmap
Set imageBitmap 's bitmap data to a copy of image 's bitmap data , cropped to the source rectangle with formatting .
Set the origin-clean flag of imageBitmap 's bitmap to the same value as the origin-clean flag of image 's bitmap.
Run this step in parallel :
Resolve p with imageBitmap .
Return p .
When the steps above require that the user agent crop bitmap data to the source rectangle with formatting , the user agent must run the following steps:
Let input be the bitmap data being transformed.
If sx , sy , sw and sh are specified, let sourceRectangle be a rectangle whose corners are the four points ( sx , sy ), ( sx + sw , sy ),( sx + sw , sy + sh ), ( sx , sy + sh ). Otherwise let sourceRectangle be a rectangle whose corners are the four points (0,0), (width of input , 0), (width of input , height of input ), (0, height of input ).
If either sw or sh are negative, then the top-left corner of this rectangle will be to the left or above the ( sx , sy ) point.
Clip sourceRectangle to the dimensions of input .
Let outputWidth be determined as follows:
resizeWidth
member
of
options
is
specified
resizeWidth
member
of
options
resizeWidth
member
of
options
is
not
specified,
but
the
resizeHeight
member
is
specified
resizeHeight
member
of
options
,
divided
by
the
height
of
sourceRectangle
,
rounded
up
to
the
nearest
integer
resizeWidth
nor
resizeHeight
are
specified
Let outputHeight be determined as follows:
resizeHeight
member
of
options
is
specified
resizeHeight
member
of
options
resizeHeight
member
of
options
is
not
specified,
but
the
resizeWidth
member
is
specified
resizeWidth
member
of
options
,
divided
by
the
width
of
sourceRectangle
,
rounded
up
to
the
nearest
integer
resizeWidth
nor
resizeHeight
are
specified
Place input on an infinite transparent black grid plane, positioned so that its top left corner is at the origin of the plane, with the x -coordinate increasing to the right, and the y -coordinate increasing down, and with each pixel in the input image data occupying a cell on the plane's grid.
Let output be the rectangle on the plane denoted by sourceRectangle .
Scale
output
to
the
size
specified
by
outputWidth
and
outputHeight
.
The
user
agent
should
use
the
value
of
the
resizeQuality
option
to
guide
the
choice
of
scaling
algorithm.
If
the
value
of
the
imageOrientation
member
of
options
is
"
flipY
",
output
must
be
flipped
vertically,
disregarding
any
image
orientation
metadata
of
the
source
(such
as
EXIF
metadata),
if
any.
[EXIF]
If
the
value
is
"
none
",
no
extra
step
is
required.
If
image
is
an
img
element
or
a
Blob
object,
let
val
be
the
value
of
the
colorSpaceConversion
member
of
options
,
and
then
run
these
substeps:
If
val
is
"
default
",
the
color
space
conversion
behavior
is
implementation-specific,
and
should
be
chosen
according
to
the
color
space
that
the
implementation
uses
for
drawing
images
onto
the
canvas.
If
val
is
"
none
",
output
must
be
decoded
without
performing
any
color
space
conversions.
This
means
that
the
image
decoding
algorithm
must
ignore
color
profile
metadata
embedded
in
the
source
data
as
well
as
the
display
device
color
profile.
The native color space of canvas is currently unspecified, but this is expected to change in the future.
Let
val
be
the
value
of
premultiplyAlpha
member
of
options
,
and
then
run
these
substeps:
If
val
is
"
default
",
the
alpha
premultiplication
behavior
is
implementation-specific,
and
should
be
chosen
according
to
implementation
deems
optimal
for
drawing
images
onto
the
canvas.
If
val
is
"
premultiply
",
the
output
that
is
not
premultiplied
by
alpha
must
have
its
color
components
multiplied
by
alpha
and
that
is
premultiplied
by
alpha
must
be
left
untouched.
If
val
is
"
none
",
the
output
that
is
not
premultiplied
by
alpha
must
be
left
untouched
and
that
is
premultiplied
by
alpha
must
have
its
color
components
divided
by
alpha.
Return output .
When
the
close()
method
is
called,
the
user
agent
must
run
these
steps:
Set
this
ImageBitmap
object's
[[Detached]]
internal
slot
value
to
true.
Unset
this
ImageBitmap
object's
bitmap
data
.
The
width
attribute's
getter
must
run
these
steps:
If
this
ImageBitmap
object's
[[Detached]]
internal
slot's
value
is
true,
then
return
0.
Return
this
ImageBitmap
object's
width,
in
CSS
pixels
.
The
height
attribute's
getter
must
run
these
steps:
If
this
ImageBitmap
object's
[[Detached]]
internal
slot's
value
is
true,
then
return
0.
Return
this
ImageBitmap
object's
height,
in
CSS
pixels
.
The ResizeQuality enumeration is used to express a preference for the interpolation quality to use when scaling images.
The
"
pixelated
"
value
indicates
a
preference
to
scale
the
image
that
maximizes
the
appearance.
Scaling
algorithms
that
"smooth"
colors
are
acceptable,
such
as
bilinear
interpolation.
The
"
low
"
value
indicates
a
preference
for
a
low
level
of
image
interpolation
quality.
Low-quality
image
interpolation
may
be
more
computationally
efficient
than
higher
settings.
The
"
medium
"
value
indicates
a
preference
for
a
medium
level
of
image
interpolation
quality.
The
"
high
"
value
indicates
a
preference
for
a
high
level
of
image
interpolation
quality.
High-quality
image
interpolation
may
be
more
computationally
expensive
than
lower
settings.
Bilinear scaling is an example of a relatively fast, lower-quality image-smoothing algorithm. Bicubic or Lanczos scaling are examples of image-scaling algorithms that produce higher-quality output. This specification does not mandate that specific interpolation algorithms be used unless the value is " pixelated ".
Using this API, a sprite sheet can be precut and prepared:
var sprites = {};
function loadMySprites() {
var image = new Image();
image.src = 'mysprites.png';
var resolver;
var promise = new Promise(function (arg) { resolver = arg });
image.onload = function () {
resolver(Promise.all([
createImageBitmap(image, 0, 0, 40, 40).then(function (image) { sprites.person = image }),
createImageBitmap(image, 40, 0, 40, 40).then(function (image) { sprites.grass = image }),
createImageBitmap(image, 80, 0, 40, 40).then(function (image) { sprites.tree = image }),
createImageBitmap(image, 0, 40, 40, 40).then(function (image) { sprites.hut = image }),
createImageBitmap(image, 40, 40, 40, 40).then(function (image) { sprites.apple = image }),
createImageBitmap(image, 80, 40, 40, 40).then(function (image) { sprites.snake = image })
]));
};
return promise;
}
function runDemo() {
var canvas = document.querySelector('canvas#demo');
var context = canvas.getContext('2d');
context.drawImage(sprites.tree, 30, 10);
context.drawImage(sprites.snake, 70, 10);
}
loadMySprites().then(runDemo);
Support: requestanimationframe Chrome for Android 67+ Chrome 24+ iOS Safari 7.0+ UC Browser for Android 11.8+ Firefox 23+ IE 10+ Opera Mini None Safari 6.1+ Edge 12+ Samsung Internet 4+ Opera 15+ Android Browser 4.4+
Source: caniuse.com
Each
Document
has
a
list
of
animation
frame
callbacks
,
which
must
be
initially
empty,
and
an
animation
frame
callback
identifier
,
which
is
a
number
which
must
initially
be
zero.
When
the
requestAnimationFrame()
method
is
called,
the
user
agent
must
run
the
following
steps:
Let
document
be
this
Window
object's
associated
Document
.
Increment document 's animation frame callback identifier by one.
Append the method's argument to document 's list of animation frame callbacks , associated with document 's animation frame callback identifier 's current value.
Return document 's animation frame callback identifier 's current value.
When
the
cancelAnimationFrame()
method
is
called,
the
user
agent
must
run
the
following
steps:
Let
document
be
this
Window
object's
associated
Document
.
Find the entry in document 's list of animation frame callbacks that is associated with the value given by the method's argument.
If there is such an entry, remove it from document 's list of animation frame callbacks .
When
the
user
agent
is
to
run
the
animation
frame
callbacks
for
a
Document
doc
with
a
timestamp
now
,
it
must
run
the
following
steps:
Let callbacks be a list of the entries in doc 's list of animation frame callbacks , in the order in which they were added to the list.
Set doc 's list of animation frame callbacks to the empty list.
For each entry in callbacks , in order: invoke the callback , passing now as the only argument, and if an exception is thrown, report the exception . [WEBIDL]