Blame - README.md - angle/angle

blob: 50e45a54a10771db3adca8634097d5fb84fb2417 [file] [log] [blame] [view]

anatoly techtonik	093a4c3	2016-05-29 09:00:06	[diff] [blame]	1	# ANGLE - Almost Native Graphics Layer Engine
				2
Jamie Madill	950ee3c	2016-08-10 19:46:07	[diff] [blame]	3	The goal of ANGLE is to allow users of multiple operating systems to seamlessly run WebGL and other
				4	OpenGL ES content by translating OpenGL ES API calls to one of the hardware-supported APIs available
Shahbaz Youssefi	475c527	2020-02-20 03:06:42	[diff] [blame]	5	for that platform. ANGLE currently provides translation from OpenGL ES 2.0, 3.0 and 3.1 to Vulkan,
				6	desktop OpenGL, OpenGL ES, Direct3D 9, and Direct3D 11. Future plans include ES 3.2, translation to
				7	Metal and MacOS, Chrome OS, and Fuchsia support.
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	8
Jamie Madill	950ee3c	2016-08-10 19:46:07	[diff] [blame]	9	### Level of OpenGL ES support via backing renderers
Shannon Woods	fe80aba	2015-11-06 03:11:43	[diff] [blame]	10
Yuxin Hu	f3af255	2023-10-24 17:21:29	[diff] [blame]	11	\| \| Direct3D 9 \| Direct3D 11 \| Desktop GL \| GL ES \| Vulkan \| Metal \|
				12	\|----------------\|:-------------:\|:----------------:\|:--------------:\|:-------------:\|:--------:\|:-------------:\|
				13	\| OpenGL ES 2.0 \| complete \| complete \| complete \| complete \| complete \| complete \|
				14	\| OpenGL ES 3.0 \| \| complete \| complete \| complete \| complete \| complete \|
				15	\| OpenGL ES 3.1 \| \| [incomplete][ES31OnD3D] \| complete \| complete \| complete \| \|
				16	\| OpenGL ES 3.2 \| \| \| in progress \| in progress \| complete \| \|
Shannon Woods	4ed53a5	2015-11-30 20:53:52	[diff] [blame]	17
Shahbaz Youssefi	a59430b	2023-01-11 19:49:14	[diff] [blame]	18	Additionally, OpenGL ES 1.1 is implemented in the front-end using OpenGL ES 3.0 features. This
				19	version of the specification is thus supported on all platforms specified above that support OpenGL
				20	ES 3.0 with [known issues][ES1].
				21
				22	[ES31OnD3D]: doc/ES31StatusOnD3D11.md
				23	[ES1]: doc/ES1Status.md
				24
Jamie Madill	950ee3c	2016-08-10 19:46:07	[diff] [blame]	25	### Platform support via backing renderers
Shannon Woods	fe80aba	2015-11-06 03:11:43	[diff] [blame]	26
Geoff Lang	9aadc7a	2023-07-13 15:44:51	[diff] [blame]	27	\| \| Direct3D 9 \| Direct3D 11 \| Desktop GL \| GL ES \| Vulkan \| Metal \|
				28	\|-------------:\|:--------------:\|:--------------:\|:-------------:\|:-----------:\|:-----------:\|:--------------------:\|
				29	\| Windows \| complete \| complete \| complete \| complete \| complete \| \|
				30	\| Linux \| \| \| complete \| \| complete \| \|
				31	\| Mac OS X \| \| \| complete \| \| \| complete [1] \|
				32	\| iOS \| \| \| \| \| \| complete [2] \|
				33	\| Chrome OS \| \| \| \| complete \| planned \| \|
				34	\| Android \| \| \| \| complete \| complete \| \|
Geoff Lang	9aadc7a	2023-07-13 15:44:51	[diff] [blame]	35	\| Fuchsia \| \| \| \| \| complete \| \|
				36
				37	[1] Metal is supported on macOS 10.14+
				38
				39	[2] Metal is supported on iOS 12+
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	40
Tim Van Patten	97d54a0	2020-07-09 20:33:26	[diff] [blame]	41	ANGLE v1.0.772 was certified compliant by passing the OpenGL ES 2.0.3 conformance tests in October 2011.
				42
				43	ANGLE has received the following certifications with the Vulkan backend:
				44	* OpenGL ES 2.0: ANGLE 2.1.0.d46e2fb1e341 (Nov, 2019)
				45	* OpenGL ES 3.0: ANGLE 2.1.0.f18ff947360d (Feb, 2020)
				46	* OpenGL ES 3.1: ANGLE 2.1.0.f5dace0f1e57 (Jul, 2020)
Yuxin Hu	f3af255	2023-10-24 17:21:29	[diff] [blame]	47	* OpenGL ES 3.2: ANGLE 2.1.2.21688.59f158c1695f (Sept, 2023)
Tim Van Patten	97d54a0	2020-07-09 20:33:26	[diff] [blame]	48
Mohan Maiya	d867ddb	2022-03-16 16:25:03	[diff] [blame]	49	ANGLE also provides an implementation of the EGL 1.5 specification.
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	50
Jamie Madill	950ee3c	2016-08-10 19:46:07	[diff] [blame]	51	ANGLE is used as the default WebGL backend for both Google Chrome and Mozilla Firefox on Windows
				52	platforms. Chrome uses ANGLE for all graphics rendering on Windows, including the accelerated
				53	Canvas2D implementation and the Native Client sandbox environment.
				54
				55	Portions of the ANGLE shader compiler are used as a shader validator and translator by WebGL
				56	implementations across multiple platforms. It is used on Mac OS X, Linux, and in mobile variants of
				57	the browsers. Having one shader validator helps to ensure that a consistent set of GLSL ES shaders
				58	are accepted across browsers and platforms. The shader translator can be used to translate shaders
				59	to other shading languages, and to optionally apply shader modifications to work around bugs or
Shahbaz Youssefi	475c527	2020-02-20 03:06:42	[diff] [blame]	60	quirks in the native graphics drivers. The translator targets Desktop GLSL, Vulkan GLSL, Direct3D
				61	HLSL, and even ESSL for native GLES2 platforms.
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	62
Austin Annestrand	975e941	2024-06-13 22:22:11	[diff] [blame]	63	### OpenCL Implementation
				64
				65	In addition to OpenGL ES, ANGLE also provides an optional `OpenCL` runtime built into the same
				66	output GLES lib.
				67
				68	This work/effort is currently work-in-progress/experimental.
				69
				70	This work provides the same benefits as the OpenGL implementation, having OpenCL APIs be
				71	translated to other HW-supported APIs available on that platform.
				72
				73	### Level of OpenCL support via backing renderers
				74
				75	\| \| Vulkan \| OpenCL \|
				76	\|-------------\|:-----------:\|:-----------:\|
				77	\| OpenCL 1.0 \| in progress \| in progress \|
				78	\| OpenCL 1.1 \| in progress \| in progress \|
				79	\| OpenCL 1.2 \| in progress \| in progress \|
				80	\| OpenCL 3.0 \| in progress \| in progress \|
				81
				82	Each supported backing renderer above ends up being an OpenCL `Platform` for the user to choose from.
				83
				84	The `OpenCL` backend is a "passthrough" implementation which does not perform any API translation
				85	at all, instead forwarding API calls to other OpenCL driver(s)/implementation(s).
				86
				87	OpenCL also has an online compiler component to it that is used to compile `OpenCL C` source code at runtime
				88	(similarly to GLES and GLSL). Depending on the chosen backend(s), compiler implementations may vary. Below is
				89	a list of renderers and what OpenCL C compiler implementation is used for each:
				90
				91	- `Vulkan` : [clspv](https://github.com/google/clspv/tree/main)
				92	- `OpenCL` : Compiler is part of the native driver
				93
anatoly techtonik	093a4c3	2016-05-29 09:00:06	[diff] [blame]	94	## Sources
Shannon Woods	4ed53a5	2015-11-30 20:53:52	[diff] [blame]	95
anatoly techtonik	093a4c3	2016-05-29 09:00:06	[diff] [blame]	96	ANGLE repository is hosted by Chromium project and can be
				97	[browsed online](https://chromium.googlesource.com/angle/angle) or cloned with
				98
				99	git clone https://chromium.googlesource.com/angle/angle
				100
				101
				102	## Building
				103
Frank Henigman	a7f97a2	2018-08-21 04:04:05	[diff] [blame]	104	View the [Dev setup instructions](doc/DevSetup.md).
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	105
anatoly techtonik	093a4c3	2016-05-29 09:00:06	[diff] [blame]	106	## Contributing
				107
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	108	* Join our [Google group](https://groups.google.com/group/angleproject) to keep up to date.
YuxinHu	bf74475	2021-10-04 23:57:15	[diff] [blame]	109	* Join us on [Slack](https://chromium.slack.com) in the #angle channel. You can
Ash Burn	ac9b270	2021-12-09 23:19:33	[diff] [blame]	110	follow the instructions on the [Chromium developer page](https://www.chromium.org/developers/slack)
YuxinHu	bf74475	2021-10-04 23:57:15	[diff] [blame]	111	for the steps to join the Slack channel. For Googlers, please follow the
				112	instructions on this [document](https://docs.google.com/document/d/1wWmRm-heDDBIkNJnureDiRO7kqcRouY2lSXlO6N2z6M/edit?usp=sharing)
				113	to use your google or chromium email to join the Slack channel.
Jamie Madill	cff54d6	2018-05-18 12:39:34	[diff] [blame]	114	* [File bugs](http://anglebug.com/new) in the [issue tracker](https://bugs.chromium.org/p/angleproject/issues/list) (preferably with an isolated test-case).
anatoly techtonik	093a4c3	2016-05-29 09:00:06	[diff] [blame]	115	* [Choose an ANGLE branch](doc/ChoosingANGLEBranch.md) to track in your own project.
				116
anatoly techtonik	c3c1409	2016-06-03 06:49:02	[diff] [blame]	117
				118	* Read ANGLE development [documentation](doc).
Frank Henigman	c677795	2017-11-27 05:15:54	[diff] [blame]	119	* Look at [pending](https://chromium-review.googlesource.com/q/project:angle/angle+status:open)
				120	and [merged](https://chromium-review.googlesource.com/q/project:angle/angle+status:merged) changes.
anatoly techtonik	c3c1409	2016-06-03 06:49:02	[diff] [blame]	121	* Become a [code contributor](doc/ContributingCode.md).
				122	* Use ANGLE's [coding standard](doc/CodingStandard.md).
				123	* Learn how to [build ANGLE for Chromium development](doc/BuildingAngleForChromiumDevelopment.md).
				124	* Get help on [debugging ANGLE](doc/DebuggingTips.md).
Shahbaz Youssefi	b7b46ee	2024-08-05 14:22:48	[diff] [blame]	125	* Go through [ANGLE's orientation](doc/Orientation.md) and sift through [issues](https://issues.angleproject.org/). If you decide to take on any task, write a comment so you can get in touch with us, and more importantly, set yourself as the "owner" of the bug. This avoids having multiple people accidentally working on the same issue.
anatoly techtonik	c3c1409	2016-06-03 06:49:02	[diff] [blame]	126
				127
Geoff Lang	a59b8ba	2014-08-27 15:47:14	[diff] [blame]	128	* Read about WebGL on the [Khronos WebGL Wiki](http://khronos.org/webgl/wiki/Main_Page).
Shahbaz Youssefi	b7b46ee	2024-08-05 14:22:48	[diff] [blame]	129	* Learn about the internals of ANGLE:
				130	* [Overview](https://docs.google.com/presentation/d/1qal4GgddwlUw-TPaXRYeTWLXUoaemgggBuTfg6_rwjU) with a focus on the Vulkan backend (2022)
				131	* A [short presentation](https://youtu.be/QrIKdjmpmaA) on the Vulkan back-end (2018).
				132	* Historical [presentation](https://docs.google.com/presentation/d/1CucIsdGVDmdTWRUbg68IxLE5jXwCb2y1E9YVhQo0thg/pub?start=false&loop=false) on the evolution of ANGLE and its use in Chromium
				133	* Historical [presentation](https://drive.google.com/file/d/0Bw29oYeC09QbbHoxNE5EUFh0RGs/view?usp=sharing&resourcekey=0-CNvGnQGgFSvbXgX--Y_Iyg) with a focus on D3D
				134	* The details of the initial implementation of ANGLE in the [OpenGL Insights chapter on ANGLE](http://www.seas.upenn.edu/~pcozzi/OpenGLInsights/OpenGLInsights-ANGLE.pdf) (these details are severely out-of-date, and this reference is listed here for historical reference only)
Jamie Madill	2682b5a	2019-10-07 19:13:23	[diff] [blame]	135	* Read design docs on the [Vulkan back-end](src/libANGLE/renderer/vulkan/README.md)
Jamie Madill	457588e	2020-03-16 18:11:33	[diff] [blame]	136	* Read about ANGLE's [testing infrastructure](infra/README.md)
Jamie Madill	35708f9	2021-09-30 15:54:34	[diff] [blame]	137	* View information on ANGLE's [supported extensions](doc/ExtensionSupport.md)
Shannon Woods	fe80aba	2015-11-06 03:11:43	[diff] [blame]	138	* If you use ANGLE in your own project, we'd love to hear about it!