diff --git a/.github/workflows/build-debian-multiarch.yml b/.github/workflows/build-debian-multiarch.yml index fbf49a96f4..cf57642085 100644 --- a/.github/workflows/build-debian-multiarch.yml +++ b/.github/workflows/build-debian-multiarch.yml @@ -47,7 +47,7 @@ jobs: arch: [s390x, ppc64le] steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Build sources and run tests uses: uraimo/run-on-arch-action@v2.5.0 diff --git a/.github/workflows/build-emsdk.yml b/.github/workflows/build-emsdk.yml index ec6cbfffce..e2b7f1f3e2 100644 --- a/.github/workflows/build-emsdk.yml +++ b/.github/workflows/build-emsdk.yml @@ -47,11 +47,11 @@ jobs: WHEELHOUSE_CYTHON: /tmp/wheelhouse/cython steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Cache Cython id: cache-cython - uses: actions/cache@v3 + uses: actions/cache@v3.3.1 with: path: ${{ env.WHEELHOUSE_CYTHON }} key: wasm-ubuntu-cython-${{ env.LATEST_CYTHON_COMMIT }}-path-${{ env.WHEELHOUSE_CYTHON }} diff --git a/.github/workflows/build-macos.yml b/.github/workflows/build-macos.yml index 74a9b4e9a9..0a16494c8b 100644 --- a/.github/workflows/build-macos.yml +++ b/.github/workflows/build-macos.yml @@ -45,16 +45,17 @@ jobs: macarch: [arm64, x86_64] steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Test for Mac Deps cache hit id: macdep-cache - uses: actions/cache@v3.0.2 + uses: actions/cache@v3.3.1 with: path: ${{ github.workspace }}/pygame_mac_deps_${{ matrix.macarch }} # The hash of all files in buildconfig manylinux-build and macdependencies is # the key to the cache. If anything changes here, the deps are built again key: macdep-${{ hashFiles('buildconfig/manylinux-build/**') }}-${{ hashFiles('buildconfig/macdependencies/*.sh') }}-${{ matrix.macarch }} + lookup-only: true # build mac deps on cache miss - name: Build Mac Deps @@ -116,6 +117,7 @@ jobs: } env: + MAC_ARCH: ${{ matrix.macarch }} # load pip config from this file. Define this in 'CIBW_ENVIRONMENT' # because this should not affect cibuildwheel machinery # also define environment variables needed for testing @@ -129,7 +131,6 @@ jobs: # Setup MacOS dependencies CIBW_BEFORE_ALL: | - export MAC_ARCH="${{ matrix.macarch }}" brew install pkg-config cd buildconfig/macdependencies cp -r ${{ github.workspace }}/pygame_mac_deps_${{ matrix.macarch }} ${{ github.workspace }}/pygame_mac_deps @@ -149,23 +150,24 @@ jobs: CIBW_BUILD_VERBOSITY: 2 steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: pip cache - uses: actions/cache@v3.0.2 + uses: actions/cache@v3.3.1 with: path: ~/Library/Caches/pip # This cache path is only right on mac key: pip-cache-${{ matrix.name }} - name: Fetch Mac deps id: macdep-cache - uses: actions/cache@v3.0.2 + uses: actions/cache@v3.3.1 with: path: ${{ github.workspace }}/pygame_mac_deps_${{ matrix.macarch }} key: macdep-${{ hashFiles('buildconfig/manylinux-build/**') }}-${{ hashFiles('buildconfig/macdependencies/*.sh') }}-${{ matrix.macarch }} + fail-on-cache-miss: true - name: Build and test wheels - uses: pypa/cibuildwheel@v2.12.3 + uses: pypa/cibuildwheel@v2.13.1 - uses: actions/upload-artifact@v3 with: diff --git a/.github/workflows/build-manylinux.yml b/.github/workflows/build-manylinux.yml index fab5b69ba8..38d91dfdf2 100644 --- a/.github/workflows/build-manylinux.yml +++ b/.github/workflows/build-manylinux.yml @@ -79,10 +79,10 @@ jobs: CIBW_BUILD_VERBOSITY: 2 steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Log in to the Container registry - uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a + uses: docker/login-action@465a07811f14bebb1938fbed4728c6a1ff8901fc with: registry: ghcr.io username: ${{ github.actor }} @@ -95,14 +95,14 @@ jobs: - name: Extract metadata (tags, labels) for Docker id: meta - uses: docker/metadata-action@c4ee3adeed93b1fa6a762f209fb01608c1a22f1e + uses: docker/metadata-action@818d4b7b91585d195f67373fd9cb0332e31a7175 with: images: ghcr.io/${{ github.repository }}_${{ matrix.arch }} tags: type=raw,value=${{ hashFiles('buildconfig/manylinux-build/**') }} - name: Build and push Docker image if: steps.inspect.outcome == 'failure' - uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 + uses: docker/build-push-action@2eb1c1961a95fc15694676618e422e8ba1d63825 with: context: ${{ github.workspace }}/buildconfig/manylinux-build/docker_base file: ${{ github.workspace }}/buildconfig/manylinux-build/docker_base/Dockerfile-${{ matrix.arch }} @@ -118,7 +118,7 @@ jobs: CIBW_MANYLINUX_I686_IMAGE: ghcr.io/${{ github.repository }}_i686:${{ steps.meta.outputs.version }} CIBW_MANYLINUX_PYPY_I686_IMAGE: ghcr.io/${{ github.repository }}_i686:${{ steps.meta.outputs.version }} - uses: pypa/cibuildwheel@v2.12.3 + uses: pypa/cibuildwheel@v2.13.1 # We upload the generated files under github actions assets - name: Upload dist diff --git a/.github/workflows/build-ubuntu-sdist.yml b/.github/workflows/build-ubuntu-sdist.yml index 0f80b4843b..e5bc7cad4b 100644 --- a/.github/workflows/build-ubuntu-sdist.yml +++ b/.github/workflows/build-ubuntu-sdist.yml @@ -51,7 +51,7 @@ jobs: os: [ubuntu-20.04, ubuntu-22.04] steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Install deps # install numpy from pip and not apt because the one from pip is newer, diff --git a/.github/workflows/build-windows.yml b/.github/workflows/build-windows.yml index 250cd35c28..48704681df 100644 --- a/.github/workflows/build-windows.yml +++ b/.github/workflows/build-windows.yml @@ -146,7 +146,7 @@ jobs: CIBW_BUILD_VERBOSITY: 2 steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - uses: TheMrMilchmann/setup-msvc-dev@v2 # this lets us use the developer command prompt on windows with: diff --git a/.github/workflows/cppcheck.yml b/.github/workflows/cppcheck.yml index 711401359b..cfce2f69ff 100644 --- a/.github/workflows/cppcheck.yml +++ b/.github/workflows/cppcheck.yml @@ -22,7 +22,7 @@ jobs: runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Install deps run: | diff --git a/.github/workflows/format-lint.yml b/.github/workflows/format-lint.yml index 05eea364e4..c79acaf2c7 100644 --- a/.github/workflows/format-lint.yml +++ b/.github/workflows/format-lint.yml @@ -29,7 +29,7 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Install deps run: python3 -m pip install pylint black clang-format sphinx diff --git a/.github/workflows/release-gh-draft.yml b/.github/workflows/release-gh-draft.yml index f17af020eb..fcecb4976f 100644 --- a/.github/workflows/release-gh-draft.yml +++ b/.github/workflows/release-gh-draft.yml @@ -21,7 +21,7 @@ jobs: needs: [manylinux, macos, windows, sdist] runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Download all artifacts uses: actions/download-artifact@v3 diff --git a/.github/workflows/release-pypi.yml b/.github/workflows/release-pypi.yml index a2b37ea970..6442134ca5 100644 --- a/.github/workflows/release-pypi.yml +++ b/.github/workflows/release-pypi.yml @@ -8,7 +8,7 @@ jobs: publish: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3.5.2 + - uses: actions/checkout@v3.5.3 - name: Pull all release assets uses: robinraju/release-downloader@v1.8 diff --git a/README.rst b/README.rst index ccea6c95cb..959f55b4e9 100644 --- a/README.rst +++ b/README.rst @@ -7,7 +7,7 @@ |PyPiVersion| |PyPiLicense| |Python3| |GithubCommits| |BlackFormatBadge| -**English** `简体中文`_ `Français`_ +**English** `简体中文`_ `Français`_ `فارسی`_ --------------------------------------------------------------------------------------------------- Pygame_ is a free and open-source cross-platform library @@ -182,8 +182,8 @@ See docs/licenses for licenses of dependencies. .. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg?v=1 -.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.2.1.svg - :target: https://github.com/pygame-community/pygame-ce/compare/2.2.1...main +.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.3.0.svg + :target: https://github.com/pygame-community/pygame-ce/compare/2.3.0...main .. |DocsStatus| image:: https://img.shields.io/website?down_message=offline&label=docs&up_message=online&url=https%3A%2F%2Fpyga.me%2Fdocs%2F :target: https://pyga.me/docs/ @@ -199,4 +199,5 @@ See docs/licenses for licenses of dependencies. .. _GNU LGPL version 2.1: https://www.gnu.org/copyleft/lesser.html .. _简体中文: ./docs/readmes/README.zh-cn.rst -.. _Français: ./docs/readmes/README.fr.rst \ No newline at end of file +.. _Français: ./docs/readmes/README.fr.rst +.. _فارسی: ./docs/readmes/README.fa.rst \ No newline at end of file diff --git a/buildconfig/Setup.Android.SDL2.in b/buildconfig/Setup.Android.SDL2.in index 8a461cc5d7..2103c45763 100644 --- a/buildconfig/Setup.Android.SDL2.in +++ b/buildconfig/Setup.Android.SDL2.in @@ -27,7 +27,7 @@ _sdl2.audio src_c/_sdl2/audio.c $(SDL) $(DEBUG) -Isrc_c _sdl2.video src_c/_sdl2/video.c src_c/pgcompat.c $(SDL) $(DEBUG) -Isrc_c _sdl2.mixer src_c/_sdl2/mixer.c $(SDL) $(MIXER) $(DEBUG) -Isrc_c _sdl2.touch src_c/_sdl2/touch.c $(SDL) $(DEBUG) -Isrc_c -_sdl2.controller src_c/_sdl2/controller.c $(SDL) $(DEBUG) -Isrc_c +_sdl2.controller_old src_c/_sdl2/controller_old.c $(SDL) $(DEBUG) -Isrc_c GFX = src_c/SDL_gfx/SDL_gfxPrimitives.c #GFX = src_c/SDL_gfx/SDL_gfxBlitFunc.c src_c/SDL_gfx/SDL_gfxPrimitives.c @@ -51,7 +51,7 @@ key src_c/key.c $(SDL) $(DEBUG) mouse src_c/mouse.c $(SDL) $(DEBUG) rect src_c/rect.c src_c/pgcompat_rect.c $(SDL) $(DEBUG) rwobject src_c/rwobject.c $(SDL) $(DEBUG) -surface src_c/surface.c src_c/alphablit.c src_c/surface_fill.c $(SDL) $(DEBUG) +surface src_c/simd_blitters_sse2.c src_c/simd_blitters_avx2.c src_c/surface.c src_c/alphablit.c src_c/surface_fill.c $(SDL) $(DEBUG) surflock src_c/surflock.c $(SDL) $(DEBUG) time src_c/time.c $(SDL) $(DEBUG) joystick src_c/joystick.c $(SDL) $(DEBUG) @@ -64,3 +64,4 @@ pixelarray src_c/pixelarray.c $(SDL) $(DEBUG) math src_c/math.c $(SDL) $(DEBUG) pixelcopy src_c/pixelcopy.c $(SDL) $(DEBUG) newbuffer src_c/newbuffer.c $(SDL) $(DEBUG) +_window src_c/window.c $(SDL) $(DEBUG) diff --git a/buildconfig/Setup.Emscripten.SDL2.in b/buildconfig/Setup.Emscripten.SDL2.in index 99fc298805..03d3f1bcdc 100644 --- a/buildconfig/Setup.Emscripten.SDL2.in +++ b/buildconfig/Setup.Emscripten.SDL2.in @@ -61,6 +61,7 @@ surflock src_c/void.c rect src_c/void.c rwobject src_c/void.c system src_c/void.c +_window src_c/void.c #_sdl2.controller src_c/_sdl2/controller.c $(SDL) $(DEBUG) -Isrc_c _sdl2.controller_old src_c/void.c diff --git a/buildconfig/Setup.SDL2.in b/buildconfig/Setup.SDL2.in index 569b8c1a5b..36e4b9ac03 100644 --- a/buildconfig/Setup.SDL2.in +++ b/buildconfig/Setup.SDL2.in @@ -75,3 +75,4 @@ math src_c/math.c $(SDL) $(DEBUG) pixelcopy src_c/pixelcopy.c $(SDL) $(DEBUG) newbuffer src_c/newbuffer.c $(SDL) $(DEBUG) system src_c/system.c $(SDL) $(DEBUG) +_window src_c/window.c $(SDL) $(DEBUG) diff --git a/buildconfig/manylinux-build/README.rst b/buildconfig/manylinux-build/README.rst index 6c382a4597..5b49b43315 100644 --- a/buildconfig/manylinux-build/README.rst +++ b/buildconfig/manylinux-build/README.rst @@ -12,7 +12,7 @@ build on an old Linux distribution in a docker container. manylinux is an older linux with a fairly compatible ABI, so you can make linux binary wheels that run on many different linux distros. -* https://github.com/pygame/pygame/issues/295 +* https://github.com/pygame-community/pygame-ce/issues/310 * https://github.com/pypa/auditwheel * https://github.com/pypa/manylinux * https://hub.docker.com/u/pygame/ diff --git a/buildconfig/stubs/gen_stubs.py b/buildconfig/stubs/gen_stubs.py index f8672ac7e7..d4251a4149 100644 --- a/buildconfig/stubs/gen_stubs.py +++ b/buildconfig/stubs/gen_stubs.py @@ -67,7 +67,7 @@ "font": ["Font"], "mixer": ["Channel"], "time": ["Clock"], - "joystick": ["Joystick"] + "joystick": ["Joystick"], } # pygame modules from which __init__.py does the equivalent of diff --git a/buildconfig/stubs/pygame/__init__.pyi b/buildconfig/stubs/pygame/__init__.pyi index db5ff9325d..b6dcf64ca5 100644 --- a/buildconfig/stubs/pygame/__init__.pyi +++ b/buildconfig/stubs/pygame/__init__.pyi @@ -639,6 +639,8 @@ from .constants import ( WINDOWMAXIMIZED as WINDOWMAXIMIZED, WINDOWMINIMIZED as WINDOWMINIMIZED, WINDOWMOVED as WINDOWMOVED, + WINDOWPOS_CENTERED as WINDOWPOS_CENTERED, + WINDOWPOS_UNDEFINED as WINDOWPOS_UNDEFINED, WINDOWRESIZED as WINDOWRESIZED, WINDOWRESTORED as WINDOWRESTORED, WINDOWSHOWN as WINDOWSHOWN, diff --git a/buildconfig/stubs/pygame/_sdl2/video.pyi b/buildconfig/stubs/pygame/_sdl2/video.pyi index bd0d959dec..64a4572148 100644 --- a/buildconfig/stubs/pygame/_sdl2/video.pyi +++ b/buildconfig/stubs/pygame/_sdl2/video.pyi @@ -1,4 +1,4 @@ -from typing import Any, Generator, Iterable, Optional, Tuple, Union +from typing import Any, Generator, Iterable, Optional, Tuple, Union, final from pygame.color import Color from pygame.rect import Rect @@ -38,11 +38,12 @@ def messagebox( escape_button: int = 0, ) -> int: ... +@final class Window: DEFAULT_SIZE: Tuple[Literal[640], Literal[480]] def __init__( self, - title: str = "pygame", + title: str = "pygame window", size: Iterable[int] = (640, 480), position: Optional[Iterable[int]] = None, fullscreen: bool = False, @@ -73,6 +74,8 @@ class Window: display_index: int def set_modal_for(self, Window) -> None: ... +_Window = Window + class Texture: def __init__( self, @@ -133,7 +136,7 @@ class Texture: class Image: def __init__( self, - textureOrImage: Union[Texture, Image], + texture_or_image: Union[Texture, Image], srcrect: Optional[RectValue] = None, ) -> None: ... def get_rect(self, **kwargs: Any) -> Rect: ... @@ -153,14 +156,14 @@ class Image: class Renderer: def __init__( self, - window: Window, + window: Union[Window,_Window], index: int = -1, accelerated: int = -1, vsync: bool = False, target_texture: bool = False, ) -> None: ... @classmethod - def from_window(cls, window: Window) -> Renderer: ... + def from_window(cls, window: Union[Window,_Window]) -> Renderer: ... draw_blend_mode: int draw_color: Color def clear(self) -> None: ... diff --git a/buildconfig/stubs/pygame/_sdl2/window.pyi b/buildconfig/stubs/pygame/_sdl2/window.pyi new file mode 100644 index 0000000000..23b997ea88 --- /dev/null +++ b/buildconfig/stubs/pygame/_sdl2/window.pyi @@ -0,0 +1 @@ +from pygame._sdl2.video import _Window as Window diff --git a/buildconfig/stubs/pygame/_window.pyi b/buildconfig/stubs/pygame/_window.pyi new file mode 100644 index 0000000000..da24050083 --- /dev/null +++ b/buildconfig/stubs/pygame/_window.pyi @@ -0,0 +1,38 @@ +from typing import Iterable, Optional, Tuple, Union, final +from pygame.surface import Surface +from ._common import RectValue +from pygame.locals import WINDOWPOS_UNDEFINED + +def get_grabbed_window() -> Optional[Window]: ... +@final +class Window: + def __init__( + self, + title: str = "pygame window", + size: Iterable[int] = (640, 480), + position: Union[int, Iterable[int]] = WINDOWPOS_UNDEFINED, + **flags: bool + ) -> None: ... + def destroy(self) -> None: ... + def set_windowed(self) -> None: ... + def set_fullscreen(self, desktop: bool = False) -> None: ... + def focus(self, input_only: bool = False) -> None: ... + def hide(self) -> None: ... + def show(self) -> None: ... + def restore(self) -> None: ... + def maximize(self) -> None: ... + def minimize(self) -> None: ... + def set_modal_for(self, parent: Window) -> None: ... + def set_icon(self, icon: Surface) -> None: ... + grab: bool + title: str + resizable: bool + borderless: bool + relative_mouse: bool + id: int + size: Iterable[int] + position: Union[int, Iterable[int]] + opacity: float + display_index: int + @classmethod + def from_display_module(cls) -> Window: ... diff --git a/buildconfig/stubs/pygame/constants.pyi b/buildconfig/stubs/pygame/constants.pyi index 82da356874..8af12d299c 100644 --- a/buildconfig/stubs/pygame/constants.pyi +++ b/buildconfig/stubs/pygame/constants.pyi @@ -561,6 +561,8 @@ WINDOWLEAVE: int WINDOWMAXIMIZED: int WINDOWMINIMIZED: int WINDOWMOVED: int +WINDOWPOS_CENTERED: int +WINDOWPOS_UNDEFINED: int WINDOWRESIZED: int WINDOWRESTORED: int WINDOWSHOWN: int diff --git a/buildconfig/stubs/pygame/locals.pyi b/buildconfig/stubs/pygame/locals.pyi index d51f06de24..07f050273f 100644 --- a/buildconfig/stubs/pygame/locals.pyi +++ b/buildconfig/stubs/pygame/locals.pyi @@ -563,6 +563,8 @@ WINDOWLEAVE: int WINDOWMAXIMIZED: int WINDOWMINIMIZED: int WINDOWMOVED: int +WINDOWPOS_CENTERED: int +WINDOWPOS_UNDEFINED: int WINDOWRESIZED: int WINDOWRESTORED: int WINDOWSHOWN: int diff --git a/buildconfig/stubs/pygame/mixer.pyi b/buildconfig/stubs/pygame/mixer.pyi index 5b0e13a3e5..1ffb7937f0 100644 --- a/buildconfig/stubs/pygame/mixer.pyi +++ b/buildconfig/stubs/pygame/mixer.pyi @@ -83,6 +83,7 @@ class Channel: def unpause(self) -> None: ... def fadeout(self, time: int) -> None: ... def queue(self, sound: Sound) -> None: ... + def set_source_location(self, angle:float, distance:float) -> None: ... @overload def set_volume(self, value: float) -> None: ... @overload diff --git a/buildconfig/stubs/pygame/pixelarray.pyi b/buildconfig/stubs/pygame/pixelarray.pyi index a4c3e9df86..7967afe078 100644 --- a/buildconfig/stubs/pygame/pixelarray.pyi +++ b/buildconfig/stubs/pygame/pixelarray.pyi @@ -1,4 +1,4 @@ -from typing import Any, Dict, Sequence, Tuple +from typing import Any, Dict, Sequence, Tuple, Union, overload from pygame.surface import Surface @@ -17,6 +17,20 @@ class PixelArray: def __init__(self, surface: Surface) -> None: ... def __enter__(self) -> PixelArray: ... def __exit__(self, *args, **kwargs) -> None: ... + # if indexing into a 2D PixelArray, a 1D PixelArray will be returned + # if indexing into a 1D PixelArray, an int will be returned + @overload + def __getitem__(self, index: int) -> Union[PixelArray, int]: ... + # complicated, but I'm pretty sure this is guaranteed to return a PixelArray or None + # will only return None if the slice start and end are the same + @overload + def __getitem__(self, index_range: slice) -> Union[PixelArray, None]: ... + # only valid for a 2D PixelArray + @overload + def __getitem__(self, indices: Tuple[int, int]) -> int: ... + # returns self + @overload + def __getitem__(self, ell: ellipsis) -> PixelArray: ... def make_surface(self) -> Surface: ... def replace( self, diff --git a/docs/README.md b/docs/README.md index 94953101a7..3b8a51f83f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,10 +8,9 @@ but the documentation can also be launched with `python -m pygame.docs` ### Generating the Documentation Steps: -- Have Python 3.7 or higher -- install Sphinx (`pip install Sphinx==3.5.4`) -- fork the pygame repository, download and navigate to it in the terminal -- run `python setup.py docs` +- Install Sphinx (`pip install Sphinx`) +- Fork the pygame-ce repository, download and navigate to it in the terminal +- Run `python setup.py docs` This will create a new folder under the `docs` folder. In `docs/generated`, you will find a local copy of the pygame documentation. @@ -80,4 +79,4 @@ CSS rules for the generated HTML come from from Sphinx's basic.css, which is autogenerated when Sphinx builds. This is an example of a -[Sphinx static template](https://www.sphinx-doc.org/en/master/development/theming.html#static-templates) \ No newline at end of file +[Sphinx static template](https://www.sphinx-doc.org/en/master/development/theming.html#static-templates) diff --git a/docs/reST/_static/dark-theme-icon.svg b/docs/reST/_static/dark-theme-icon.svg new file mode 100644 index 0000000000..bbf88682fe --- /dev/null +++ b/docs/reST/_static/dark-theme-icon.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/reST/_static/light-theme-icon.svg b/docs/reST/_static/light-theme-icon.svg new file mode 100644 index 0000000000..fcc61502cc --- /dev/null +++ b/docs/reST/_static/light-theme-icon.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/reST/_static/script.js b/docs/reST/_static/script.js new file mode 100644 index 0000000000..0986d830e1 --- /dev/null +++ b/docs/reST/_static/script.js @@ -0,0 +1,32 @@ + +const htmlElement = document.documentElement; + +if (localStorage.getItem('theme') === null) { + localStorage.setItem('theme', 'light-theme'); + htmlElement.classList.add('light-theme'); +} else { + htmlElement.classList.add(localStorage.getItem('theme')); +} + +// Execute once the DOM is loaded +document.addEventListener('DOMContentLoaded', () => { + const search_buttons = document.querySelectorAll('.searchbar-button'); + const search_submit = document.querySelector('.searchbar-submit'); + + // When the icon is clicked, submit the search form + search_buttons.forEach((button) => { + button.addEventListener('click', () => { + search_submit.click(); + }); + }); + + const theme_icons = document.querySelectorAll('.theme-icon'); + theme_icons.forEach((icon) => { + icon.addEventListener('click', () => { + const theme = icon.getAttribute('data-theme'); + htmlElement.classList.add('light-theme', 'dark-theme'); + htmlElement.classList.remove(theme); + localStorage.setItem('theme', htmlElement.classList[0]); + }); + }); +}); diff --git a/docs/reST/_static/searchbar-icon.svg b/docs/reST/_static/searchbar-icon.svg new file mode 100644 index 0000000000..653668d989 --- /dev/null +++ b/docs/reST/_static/searchbar-icon.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/reST/c_api.rst b/docs/reST/c_api.rst index 734289f0ad..f83223722d 100644 --- a/docs/reST/c_api.rst +++ b/docs/reST/c_api.rst @@ -12,12 +12,14 @@ pygame C API c_api/display.rst c_api/event.rst c_api/freetype.rst + c_api/joystick.rst c_api/mixer.rst c_api/rect.rst c_api/rwobject.rst c_api/surface.rst c_api/surflock.rst c_api/version.rst + c_api/window.rst src_c/include/ contains header files for applications diff --git a/docs/reST/c_api/joystick.rst b/docs/reST/c_api/joystick.rst new file mode 100644 index 0000000000..507a00b2f7 --- /dev/null +++ b/docs/reST/c_api/joystick.rst @@ -0,0 +1,29 @@ +.. include:: ../common.txt + +.. highlight:: c + +****************************************** + API exported by pygame.joystick +****************************************** + +src_c/joystick.c +================ + +The extension module :py:mod:`pygame.joystick`. + +Header file: src_c/include/pygame.h + +.. c:var:: PyTypeObject *pgJoystick_Type + + The Pygame joystick object type :py:class:`pygame.Joystick`. + +.. c:function:: PyObject* pgJoystick_New(int id) + + Return a new :py:class:`pygame.Joystick` instance. + On failure, raise a Python exception and return ``NULL``. + +.. c:function:: int pgJoystick_GetDeviceIndexByInstanceID(int instance_id) + + Get the device index of a joystick by a instance id. + Return a device index. + On failure, it returns -1. diff --git a/docs/reST/c_api/window.rst b/docs/reST/c_api/window.rst new file mode 100644 index 0000000000..4ab8f083a2 --- /dev/null +++ b/docs/reST/c_api/window.rst @@ -0,0 +1,30 @@ +.. include:: ../common.txt + +.. highlight:: c + +************************************************ + Class Window API exported by pygame.window +************************************************ + +src_c/window.c +=============== + +This extension module defines Python type :py:class:`pygame.Window`. + +Header file: src_c/include/pygame.h + + +.. c:type:: pgWindowObject + + A :py:class:`pygame.window.Window` instance. + +.. c:var:: PyTypeObject *pgWindow_Type + + The :py:class:`pygame.window.Window` Python type. + +.. c:function:: int pgWindow_Check(PyObject *x) + + Return true if *x* is a :py:class:`pygame.window.Window` instance + + Will return false if *x* is not a subclass of `Window`. + This is a macro. No check is made that *x* is not *NULL*. diff --git a/docs/reST/conf.py b/docs/reST/conf.py index ca3af4fd75..afb4af8541 100644 --- a/docs/reST/conf.py +++ b/docs/reST/conf.py @@ -39,17 +39,17 @@ master_doc = 'index' # General information about the project. -project = 'pygame' -copyright = '2000-2022, pygame developers' +project = 'pygame-ce' +copyright = '2000-2022, pygame developers, 2023 pygame-ce developers' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2.3.0' +version = '2.3.1' # The full version, including alpha/beta/rc tags. -release = '2.3.0.dev3' +release = '2.3.1.dev1' # Format strings for the version directives versionadded_format = 'New in pygame-ce %s' diff --git a/docs/reST/ext/boilerplate.py b/docs/reST/ext/boilerplate.py index 526033a74a..ad5089d5ed 100644 --- a/docs/reST/ext/boilerplate.py +++ b/docs/reST/ext/boilerplate.py @@ -45,6 +45,9 @@ def setup(app): # This extension uses indexer collected tables. app.setup_extension("ext.indexer") + # Add js files for theme changing in docs. + app.add_js_file("script.js") + # Documents to leave untransformed by boilerplate app.add_config_value("boilerplate_skip_transform", [], "") diff --git a/docs/reST/index.rst b/docs/reST/index.rst index df4d903286..444578d036 100644 --- a/docs/reST/index.rst +++ b/docs/reST/index.rst @@ -1,5 +1,5 @@ -Pygame Front Page -================= +Pygame-ce Front Page +==================== .. toctree:: :maxdepth: 2 @@ -18,9 +18,10 @@ Pygame Front Page Quick start ----------- -Welcome to pygame! Once you've got pygame installed (:code:`pip install pygame-ce` or -:code:`pip3 install pygame-ce` for most people), the next question is how to get a game -loop running. Pygame, unlike some other libraries, gives you full control of program +Welcome to pygame-ce! Once you've got pygame-ce installed +(:code:`pip install pygame-ce` or :code:`pip3 install pygame-ce` for most +people), the next question is how to get a game loop running. Pygame-ce, +unlike some other libraries, gives you full control of program execution. That freedom means it is easy to mess up in your initial steps. Here is a good example of a basic setup (opens the window, updates the screen, and handles events)-- diff --git a/docs/reST/ref/camera.rst b/docs/reST/ref/camera.rst index 2cfefdc3da..65e0c17f07 100644 --- a/docs/reST/ref/camera.rst +++ b/docs/reST/ref/camera.rst @@ -13,6 +13,7 @@ with wider platform support available via an integrated OpenCV backend. .. versionaddedold:: 2.0.2 Windows native camera support .. versionaddedold:: 2.0.3 New OpenCV backends +.. versionchanged:: 2.3.0 Removed deprecated vidcapture backend EXPERIMENTAL!: This API may change or disappear in later pygame releases. If you use this, your code will very likely break with the next pygame release. @@ -78,14 +79,12 @@ The Bayer to ``RGB`` function is based on: _camera (V4L2) Linux Builtin OpenCV Any Uses `opencv-python` module, can't enumerate cameras OpenCV-Mac Mac Same as OpenCV, but has camera enumeration - VideoCapture Windows Uses abandoned `VideoCapture` module, can't enumerate - cameras, may be removed in the future There are two main differences among backends. The _camera backends are built in to pygame itself, and require no third - party imports. All the other backends do. For the OpenCV and VideoCapture - backends, those modules need to be installed on your system. + party imports. All the other backends do. For the OpenCV backend, + the module will need to be installed on your system. The other big difference is "camera enumeration." Some backends don't have a way to list out camera names, or even the number of cameras on the @@ -132,7 +131,7 @@ The Bayer to ``RGB`` function is based on: | :sg:`Camera(device, (width, height), format) -> Camera` Loads a camera. On Linux, the device is typically something like - "/dev/video0". Default width and height are 640 by 480. + "/dev/video0". Default width and height are 640 by 480. Format is the desired colorspace of the output. This is useful for computer vision purposes. The default is ``RGB``. The following are supported: diff --git a/docs/reST/ref/code_examples/cursors_module_example.py b/docs/reST/ref/code_examples/cursors_module_example.py index 95fa6a4ead..71f67b723f 100644 --- a/docs/reST/ref/code_examples/cursors_module_example.py +++ b/docs/reST/ref/code_examples/cursors_module_example.py @@ -1,44 +1,44 @@ # pygame setup -import pygame as pg +import pygame -pg.init() -screen = pg.display.set_mode([600, 400]) -pg.display.set_caption("Example code for the cursors module") +pygame.init() +screen = pygame.display.set_mode([600, 400]) +pygame.display.set_caption("Example code for the cursors module") # create a system cursor -system = pg.cursors.Cursor(pg.SYSTEM_CURSOR_NO) +system = pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_NO) # create bitmap cursors -bitmap_1 = pg.cursors.Cursor(*pg.cursors.arrow) -bitmap_2 = pg.cursors.Cursor( - (24, 24), (0, 0), *pg.cursors.compile(pg.cursors.thickarrow_strings) +bitmap_1 = pygame.cursors.Cursor(*pygame.cursors.arrow) +bitmap_2 = pygame.cursors.Cursor( + (24, 24), (0, 0), *pygame.cursors.compile(pygame.cursors.thickarrow_strings) ) # create a color cursor -surf = pg.Surface((40, 40)) # you could also load an image +surf = pygame.Surface((40, 40)) # you could also load an image surf.fill((120, 50, 50)) # and use that as your surface -color = pg.cursors.Cursor((20, 20), surf) +color = pygame.cursors.Cursor((20, 20), surf) cursors = [system, bitmap_1, bitmap_2, color] cursor_index = 0 -pg.mouse.set_cursor(cursors[cursor_index]) +pygame.mouse.set_cursor(cursors[cursor_index]) -clock = pg.time.Clock() +clock = pygame.time.Clock() going = True while going: clock.tick(60) screen.fill((0, 75, 30)) - pg.display.flip() + pygame.display.flip() - for event in pg.event.get(): - if event.type == pg.QUIT or (event.type == pg.KEYDOWN and event.key == pg.K_ESCAPE): + for event in pygame.event.get(): + if event.type == pygame.QUIT or (event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE): going = False # if the mouse is clicked it will switch to a new cursor - if event.type == pg.MOUSEBUTTONDOWN: + if event.type == pygame.MOUSEBUTTONDOWN: cursor_index += 1 cursor_index %= len(cursors) - pg.mouse.set_cursor(cursors[cursor_index]) + pygame.mouse.set_cursor(cursors[cursor_index]) -pg.quit() +pygame.quit() diff --git a/docs/reST/ref/display.rst b/docs/reST/ref/display.rst index 41e7e2dbb0..a6f643ff83 100644 --- a/docs/reST/ref/display.rst +++ b/docs/reST/ref/display.rst @@ -129,11 +129,10 @@ required). The Surface that gets returned can be drawn to like a regular Surface but changes will eventually be seen on the monitor. - If no size is passed or is set to ``(0, 0)`` and pygame uses ``SDL`` - version 1.2.10 or above, the created Surface will have the same size as the - current screen resolution. If only the width or height are set to ``0``, the - Surface will have the same width or height as the screen resolution. Using a - ``SDL`` version prior to 1.2.10 will raise an exception. + If no size is passed or is set to ``(0, 0)``, the created Surface will have + the same size as the current screen resolution. If only the width or height + are set to ``0``, the Surface will have the same width or height as the + screen resolution. It is usually best to not pass the depth argument. It will default to the best and fastest color depth for the system. If your game requires a @@ -581,7 +580,7 @@ required). .. Note:: :func:`toggle_fullscreen` doesn't work on Windows unless the window size is in :func:`pygame.display.list_modes()` or the window is created with the flag ``pygame.SCALED``. - See `issue #2380 `_. + See `issue #1221 `_. .. ## pygame.display.toggle_fullscreen ## diff --git a/docs/reST/ref/font.rst b/docs/reST/ref/font.rst index 3b5cf1af37..4979349b6c 100644 --- a/docs/reST/ref/font.rst +++ b/docs/reST/ref/font.rst @@ -57,6 +57,8 @@ solves no longer exists, it will likely be removed in the future. It is safe to call this function even if font is currently not initialized. + Previously created font objects will be invalid after the font module is quit. + .. ## pygame.font.quit ## .. function:: get_init diff --git a/docs/reST/ref/mixer.rst b/docs/reST/ref/mixer.rst index 0a97e0f479..92a0c3a474 100644 --- a/docs/reST/ref/mixer.rst +++ b/docs/reST/ref/mixer.rst @@ -480,6 +480,21 @@ change the default buffer by calling :func:`pygame.mixer.pre_init` before .. ## Channel.fadeout ## + .. method:: set_source_location + + | :sl:`set the position of a playing channel` + | :sg:`set_source_location(angle,distance) -> None` + + Set the position (angle, distance) of a playing channel. + + `angle`: Angle is in degrees. + + `distance`: Range from 0 to 255. + + .. versionadded:: 2.3.0 + + .. ## Channel.set_source_location ## + .. method:: set_volume | :sl:`set the volume of a playing channel` diff --git a/docs/reST/ref/music.rst b/docs/reST/ref/music.rst index 037ee6ee18..b400d8f639 100644 --- a/docs/reST/ref/music.rst +++ b/docs/reST/ref/music.rst @@ -198,10 +198,10 @@ MP3 in most cases. file, first call :func:`rewind`. Other file formats are unsupported. Newer versions of SDL_mixer have - better positioning support than earlier ones. An SDLError is raised if a - particular format does not support positioning. + better positioning support than earlier ones. A :exc:`pygame.error` is + raised if a particular format does not support positioning. - Function :func:`set_pos` calls underlining SDL_mixer function + Function :func:`set_pos` calls underlying SDL_mixer function ``Mix_SetMusicPosition``. .. versionaddedold:: 1.9.2 diff --git a/docs/reST/ref/pygame.rst b/docs/reST/ref/pygame.rst index 5701646c52..2d7c0359c3 100644 --- a/docs/reST/ref/pygame.rst +++ b/docs/reST/ref/pygame.rst @@ -429,7 +429,7 @@ do this. Must be set before importing pygame. :: PYGAME_CAMERA - - Set to "opencv" or "vidcapture" + Set to "opencv" Forces the library backend used in the camera module, overriding the platform defaults. Must diff --git a/docs/reST/ref/sdl2_video.rst b/docs/reST/ref/sdl2_video.rst index 2d365c58e4..24cd4e70d0 100644 --- a/docs/reST/ref/sdl2_video.rst +++ b/docs/reST/ref/sdl2_video.rst @@ -8,352 +8,733 @@ .. warning:: This module isn't ready for prime time yet, it's still in development. - These docs are primarily meant to help the pygame developers and super-early adopters - who are in communication with the developers. This API will change. + These docs are primarily meant to help the pygame developers and + super-early adopters who are in communication with the developers. + This API will change. | :sl:`Experimental pygame module for porting new SDL video systems` +.. function:: messagebox + + | :sl:`Create a native GUI message box` + | :sg:`messagebox(title, message, window=None, info=False, warn=False, buttons=('OK',), return_button=0, escape_button=0)` + + :param str title: A title string, or ``None`` to omit a title. + :param str message: A message string. + :param bool info: If ``True``, display an info message. + :param bool warn: If ``True``, display a warning message. + :param bool error: If ``True``, display an error message. + :param tuple buttons: An optional sequence of button name strings to show to the user. + :param int return_button: Button index to use if the return key is hit (``-1`` for none). + :param int escape_button: Button index to use if the escape key is hit (``-1`` for none). + :return: The index of the button that was pushed. + +.. class:: RendererDriverInfo + + | :sl:`pygame object encapsulating Renderer driver information` + + Attributes: + + :: + + name + flags + num_texture_formats + max_texture_width + max_texture_height + +.. function:: get_drivers + + | :sl:`Yield info about the rendering drivers available for Renderer objects` + | :sg:`get_drivers() -> Iterator[RendererDriverInfo]` + +.. function:: get_grabbed_window + + | :sl:`Get the window with input grab enabled` + | :sg:`get_grabbed_window() -> Window or None` + + Gets the :class:`Window` with input grab enabled, if input is grabbed, + otherwise ``None`` is returned. + + .. class:: Window | :sl:`pygame object that represents a window` - | :sg:`Window(title="pygame", size=(640, 480), position=None, fullscreen=False, fullscreen_desktop=False, keywords) -> Window` + | :sg:`Window(title='pygame window', size=(640, 480), position=None, fullscreen=False, fullscreen_desktop=False, **kwargs) -> Window` + + Creates a window. + + :param str title: The title of the window. + :param (int, int) size: The size of the window, in screen coordinates. + :param (int, int) or int position: A tuple specifying the window position, or + ``WINDOWPOS_CENTERED``, or ``WINDOWPOS_UNDEFINED``. + :param bool fullscreen: Create a fullscreen window using the window size as + the resolution (videomode change). + :param bool fullscreen_desktop: Create a fullscreen window using the current + desktop resolution. + :param bool opengl: Create a window with support for an OpenGL context. You + will still need to create an OpenGL context separately. + :param bool vulkan: Create a window with support for a Vulkan instance. + :param bool hidden: Create a hidden window. + :param bool borderless: Create a window without borders. + :param bool resizable: Create a resizable window. + :param bool minimized: Create a mimized window. + :param bool maximized: Create a maximized window. + :param bool input_grabbed: Create a window with a grabbed input focus. + :param bool input_focus: Create a window with input focus. + :param bool mouse_focus: Create a window with mouse focus. + :param bool foreign: Marks a window not created by SDL. + :param bool allow_highdpi: Create a window in high-DPI mode if supported + (>= SDL 2.0.1). + :param bool mouse_capture: Create a window that has the mouse captured + (unrelated to INPUT_GRABBED, >= SDL 2.0.4). + :param bool always_on_top: Create a window that is always on top + (X11 only, >= SDL 2.0.5). + :param bool skip_taskbar: Create a window that should not be added to the + taskbar (X11 only, >= SDL 2.0.5). + :param bool utility: Create a window that should be treated as a utility + window (X11 only, >= SDL 2.0.5). + :param bool tooltip: Create a window that should be treated as a tooltip + (X11 only, >= SDL 2.0.5). + :param bool popup_menu: Create a window that should be treated as a popup menu + (X11 only, >= SDL 2.0.5). - .. classmethod:: from_display_module - - | :sl:`Creates window using window created by pygame.display.set_mode().` - | :sg:`from_display_module() -> Window` .. attribute:: grab - | :sl:`Gets or sets whether the mouse is confined to the window.` + | :sl:`Get or set the window's input grab state` | :sg:`grab -> bool` + Gets or sets the window's input grab state. + When input is grabbed, the mouse is confined to the window. + If the caller enables a grab while another window is currently grabbed, + the other window loses its grab in favor of the caller's window. + .. attribute:: relative_mouse - | :sl:`Gets or sets the window's relative mouse motion state.` + | :sl:`Get or set the window's relative mouse mode state` | :sg:`relative_mouse -> bool` + Gets or sets the window's relative mouse mode state. + SDL2 docs: *"While the mouse is in relative mode, the cursor is hidden, + the mouse position is constrained to the window, and SDL will report + continuous relative mouse motion even if the mouse is at the edge of the + window.* + + *This function will flush any pending mouse motion."* + + Calling :func:`pygame.mouse.set_visible` with argument + ``True`` will exit relative mouse mode. + + .. attribute:: title + + | :sl:`Get or set the window title` + | :sg:`title -> str` + + Gets or sets the window title. An empty string means that no title is set. + + .. attribute:: resizable + + | :sl:`Get or set whether the window is resizable` + | :sg:`resizable -> bool` + + .. attribute:: borderless + + | :sl:`Get or set whether the window is borderless` + | :sg:`borderless -> bool` + + Gets or sets whether the window is borderless. + + .. note:: You can't change the border state of a fullscreen window. + .. attribute:: id + + | :sl:`Get the unique window ID (**read-only**)` + | :sg:`id -> int` + + .. attribute:: size + + | :sl:`Get or set the window size in pixels` + | :sg:`size -> (int, int)` + + .. attribute:: position + + | :sl:`Get or set the window position in screen coordinates` + | :sg:`position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED` + + .. attribute:: opacity + + | :sl:`Get or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque)` + | :sg:`opacity -> float` + + .. attribute:: display_index + + | :sl:`Get the index of the display that owns the window (**read-only**)` + | :sg:`get_display_index -> int` + + .. classmethod:: from_display_module + + | :sl:`Create a Window object using window data from display module` + | :sg:`from_display_module() -> Window` + + Create a Window object that uses the same window data from the :mod:`pygame.display` module, created upon calling + :func:`pygame.display.set_mode`. + .. method:: set_windowed - | :sl:`Enable windowed mode (exit fullscreen).` + | :sl:`Enable windowed mode (exit fullscreen)` | :sg:`set_windowed() -> None` + .. seealso:: :func:`set_fullscreen` + .. method:: set_fullscreen - | :sl:`Enter fullscreen.` + | :sl:`Enter fullscreen` | :sg:`set_fullscreen(desktop=False) -> None` - .. attribute:: title + :param bool desktop: If ``True``, use the current desktop resolution. + If ``False``, change the fullscreen resolution to the window size. - | :sl:`Gets or sets whether the window title.` - | :sg:`title -> string` + .. seealso:: :meth:`set_windowed`. .. method:: destroy - | :sl:`Destroys the window.` + | :sl:`Destroy the window` | :sg:`destroy() -> None` + Destroys the internal window data of this Window object. This method is + called automatically when this Window object is garbage collected, so + there usually aren't any reasons to call it manually. + + Other methods that try to manipulate that window data will raise an error. + .. method:: hide - | :sl:`Hide the window.` + | :sl:`Hide the window` | :sg:`hide() -> None` .. method:: show - | :sl:`Show the window.` + | :sl:`Show the window` | :sg:`show() -> None` .. method:: focus - | :sl:`Raise the window above other windows and set the input focus. The "input_only" argument is only supported on X11.` + | :sl:`Set the window to be focused` | :sg:`focus(input_only=False) -> None` + Raises the window above other windows and sets the input focus. + + :param bool input_only: if ``True``, the window will be given input focus + but may be completely obscured by other windows. + Only supported on X11. + .. method:: restore - | :sl:`Restore the size and position of a minimized or maximized window.` + | :sl:`Restore the size and position of a minimized or maximized window` | :sg:`restore() -> None` .. method:: maximize - | :sl:`Maximize the window.` + | :sl:`Maximize the window` | :sg:`maximize() -> None` - .. method:: minimize + .. method:: minimize - | :sl:`Minimize the window.` + | :sl:`Minimize the window` | :sg:`maximize() -> None` - .. attribute:: resizable - - | :sl:`Gets and sets whether the window is resizable.` - | :sg:`resizable -> bool` - - .. attribute:: borderless - - | :sl:`Add or remove the border from the window.` - | :sg:`borderless -> bool` - .. method:: set_icon - | :sl:`Set the icon for the window.` + | :sl:`Set the window icon` | :sg:`set_icon(surface) -> None` - .. attribute:: id - - | :sl:`Get the unique window ID. *Read-only*` - | :sg:`id -> int` - - .. attribute:: size - - | :sl:`Gets and sets the window size.` - | :sg:`size -> (int, int)` - - .. attribute:: position - - | :sl:`Gets and sets the window position.` - | :sg:`position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED` + Sets the window icon. - .. attribute:: opacity + :param Surface surface: A Surface to use as the icon. - | :sl:`Gets and sets the window opacity. Between 0.0 (fully transparent) and 1.0 (fully opaque).` - | :sg:`opacity -> float` - - .. attribute:: display_index + .. method:: set_modal_for - | :sl:`Get the index of the display that owns the window. *Read-only*` - | :sg:`display_index -> int` + | :sl:`Set the window as a modal for a parent window` + | :sg:`set_modal_for(parent) -> None` - .. method:: set_modal_for + :param Window parent: The parent window. + + .. note:: This function is only supported on X11. - | :sl:`Set the window as a modal for a parent window. This function is only supported on X11.` - | :sg:`set_modal_for(Window) -> None` .. class:: Texture - | :sl:`pygame object that representing a Texture.` + | :sl:`pygame object that represents a texture` | :sg:`Texture(renderer, size, depth=0, static=False, streaming=False, target=False, scale_quality=None) -> Texture` - .. staticmethod:: from_surface - - | :sl:`Create a texture from an existing surface.` - | :sg:`from_surface(renderer, surface) -> Texture` - + Creates an empty texture. + + :param Renderer renderer: The rendering context for the texture. + :param tuple size: The width and height for the texture. + :param int depth: The pixel format (``0`` to use the default). + :param bool static: Initialize the texture as static + (changes rarely, not lockable). + :param bool streaming: Initialize the texture as streaming + (changes frequently, lockable). + :param bool target: Initialize the texture as target + (can be used as a rendering target). + :param int scale_quality: Set the texture scale quality. Can be ``0`` + (nearest pixel sampling), ``1`` + (linear filtering, supported by OpenGL and Direct3D) + and ``2`` (anisotropic filtering, supported by Direct3D). + + One of ``static``, ``streaming``, or ``target`` can be set + to ``True``. If all are ``False``, then ``static`` is used. + + + :class:`Texture` objects provide a platform-agnostic API for working with GPU textures. + They are stored in GPU video memory (VRAM), and are therefore very fast to + rotate and resize when drawn onto a :class:`Renderer` + (an object that manages a rendering context inside a :class:`Window`) on most GPUs. + + Since textures are stored in GPU video memory, they aren't as easy to modify + as the image data of :class:`pygame.Surface` objects, which reside in RAM. + + Textures can be modified in 2 ways: + + * By drawing other textures onto them, achieved by marking them as "target" textures and setting them as the rendering target of their Renderer object (if properly configured and supported). + + * By updating them with a Surface. + + .. note:: + A :class:`pygame.Surface`-to-:class:`Texture` update is generally + considered a slow operation, as it requires image data to be uploaded from + RAM to VRAM, which can have a notable overhead cost. + .. attribute:: renderer - | :sl:`Gets the renderer associated with the Texture. *Read-only*` + | :sl:`Get the renderer associated with the texture (**read-only**)` | :sg:`renderer -> Renderer` .. attribute:: width - | :sl:`Gets the width of the Texture. *Read-only*` + | :sl:`Get the width of the texture (**read-only**)` | :sg:`width -> int` .. attribute:: height - | :sl:`Gets the height of the Texture. *Read-only*` + | :sl:`Get the height of the texture (**read-only**)` | :sg:`height -> int` .. attribute:: alpha - | :sl:`Gets and sets an additional alpha value multiplied into render copy operations.` + | :sl:`Get or set the additional alpha value multiplied into draw operations` | :sg:`alpha -> int` .. attribute:: blend_mode - | :sl:`Gets and sets the blend mode for the Texture.` + | :sl:`Get or set the blend mode for texture drawing operations` | :sg:`blend_mode -> int` + Gets or sets the blend mode for the texture's drawing operations. + Valid blend modes are any of the ``BLENDMODE_*`` constants or a custom one. + .. attribute:: color - | :sl:`Gets and sets an additional color value multiplied into render copy operations.` - | :sg:`color -> color` + | :sl:`Get or set the additional color value multiplied into texture drawing operations` + | :sg:`color -> Color` + + .. staticmethod:: from_surface + + | :sl:`Create a texture from an existing surface` + | :sg:`from_surface(renderer, surface) -> Texture` + + :param Renderer renderer: Rendering context for the texture. + :param Surface surface: The surface to create a texture from. .. method:: get_rect - | :sl:`Get the rectangular area of the texture.` + | :sl:`Get the rectangular area of the texture` | :sg:`get_rect(**kwargs) -> Rect` + Like :meth:`pygame.Surface.get_rect`, this method returns a **new** + :class:`pygame.Rect` covering the entire texture. It will always + have a ``topleft`` of ``(0, 0)`` with a ``width`` and ``height`` the same size as the + texture. + .. method:: draw - | :sl:`Copy a portion of the texture to the rendering target.` + | :sl:`Copy a portion of the texture to the rendering target` | :sg:`draw(srcrect=None, dstrect=None, angle=0, origin=None, flip_x=False, flip_y=False) -> None` + :param srcrect: The source rectangle on the texture, or ``None`` for the + entire texture. + :param dstrect: The destination rectangle on the rendering target, or + ``None`` for the entire rendering target. The texture + will be stretched to fill ``dstrect``. + :param float angle: The angle (in degrees) to rotate dstrect around + (clockwise). + :param origin: The point around which dstrect will be rotated. + If ``None``, it will equal the center: + ``(dstrect.w/2, dstrect.h/2)``. + :param bool flip_x: Flip the drawn texture portion horizontally (x - axis). + :param bool flip_y: Flip the drawn texture portion vertically (y - axis). + .. method:: draw_triangle - | :sl:`Copy a triangle portion of the texture to the rendering target by vertices coordinates.` + | :sl:`Copy a triangle portion of the texture to the rendering target using the given coordinates` | :sg:`draw_triangle(p1_xy, p2_xy, p3_xy, p1_uv=(0.0, 0.0), p2_uv=(1.0, 1.0), p3_uv=(0.0, 1.0), p1_mod=(255, 255, 255, 255), p2_mod=(255, 255, 255, 255), p3_mod=(255, 255, 255, 255)) -> None` + :param p1_xy: The first vertex coordinate on the rendering target. + :param p2_xy: The second vertex coordinate on the rendering target. + :param p3_xy: The third vertex coordinate on the rendering target. + :param p1_uv: The first UV coordinate of the triangle portion. + :param p2_uv: The second UV coordinate of the triangle portion. + :param p3_uv: The third UV coordinate of the triangle portion. + :param p1_mod: The first vertex color modulation. + :param p2_mod: The second vertex color modulation. + :param p3_mod: The third vertex color modulation. + .. method:: draw_quad - | :sl:`Copy a quad portion of the texture to the rendering target by vertices coordinates.` + | :sl:`Copy a quad portion of the texture to the rendering target using the given coordinates` | :sg:`draw_quad(p1_xy, p2_xy, p3_xy, p4_xy, p1_uv=(0.0, 0.0), p2_uv=(1.0, 0.0), p3_uv=(1.0, 1.0), p4_uv=(0.0, 1.0), p1_mod=(255, 255, 255, 255), p2_mod=(255, 255, 255, 255), p3_mod=(255, 255, 255, 255), p4_mod=(255, 255, 255, 255)) -> None` + :param p1_xy: The first vertex coordinate on the rendering target. + :param p2_xy: The second vertex coordinate on the rendering target. + :param p3_xy: The third vertex coordinate on the rendering target. + :param p4_xy: The fourth vertex coordinate on the rendering target. + :param p1_uv: The first UV coordinate of the quad portion. + :param p2_uv: The second UV coordinate of the quad portion. + :param p3_uv: The third UV coordinate of the quad portion. + :param p4_uv: The fourth UV coordinate of the quad portion. + :param p1_mod: The first vertex color modulation. + :param p2_mod: The second vertex color modulation. + :param p3_mod: The third vertex color modulation. + :param p4_mod: The fourth vertex color modulation. + .. method:: update - | :sl:`Update the texture with a Surface. WARNING: Slow operation, use sparingly.` + | :sl:`Update the texture with Surface (slow operation, use sparingly)` | :sg:`update(surface, area=None) -> None` -.. class:: Image + :param Surface surface: The source surface. + :param area: The rectangular area of the texture to update. - | :sl:`Easy way to use a portion of a Texture without worrying about srcrect all the time.` - | :sg:`Image(textureOrImage, srcrect=None) -> Image` + .. note:: + This is a fairly slow function, intended for use with static textures + that do not change often. - .. method:: get_rect + If the texture is intended to be updated often, it is preferred to create + the texture as streaming and use the locking functions. - | :sl:`Get the rectangular area of the Image.` - | :sg:`get_rect() -> Rect` + While this function will work with streaming textures, for optimization + reasons you may not get the pixels back if you lock the texture afterward. - .. method:: draw - | :sl:`Copy a portion of the Image to the rendering target.` - | :sg:`draw(srcrect=None, dstrect=None) -> None` +.. class:: Image - .. attribute:: angle + | :sl:`pygame object that represents a portion of a texture` + | :sg:`Image(texture_or_image, srcrect=None) -> Image` - | :sl:`Gets and sets the angle the Image draws itself with.` - | :sg:`angle -> float` + Creates an Image. - .. attribute:: origin + :param Texture | Image texture_or_image: The Texture or an existing Image + object to create the Image from. + :param srcrect: The rectangular portion of the Texture or Image object + passed to ``texture_or_image``. + + An :class:`Image` object represents a portion of a :class:`Texture`. Specifically, + they can be used to store and manipulate arguments for :meth:`Texture.draw` + in a more user-friendly way. + + .. attribute:: angle - | :sl:`Gets and sets the origin. Origin=None means the Image will be rotated around its center.` - | :sg:`origin -> (float, float) or None.` + | :sl:`Get and set the angle the Image draws itself with` + | :sg:`angle -> float` .. attribute:: flip_x - | :sl:`Gets and sets whether the Image is flipped on the x axis.` + | :sl:`Get or set whether the Image is flipped on the x axis` | :sg:`flip_x -> bool` .. attribute:: flip_y - | :sl:`Gets and sets whether the Image is flipped on the y axis.` + | :sl:`Get or set whether the Image is flipped on the y axis` | :sg:`flip_y -> bool` .. attribute:: color - | :sl:`Gets and sets the Image color modifier.` + | :sl:`Get or set the Image color modifier` | :sg:`color -> Color` .. attribute:: alpha - | :sl:`Gets and sets the Image alpha modifier.` + | :sl:`Get or set the Image alpha modifier (0-255)` | :sg:`alpha -> float` .. attribute:: blend_mode - | :sl:`Gets and sets the blend mode for the Image.` + | :sl:`Get or set the blend mode for the Image` | :sg:`blend_mode -> int` .. attribute:: texture - | :sl:`Gets and sets the Texture the Image is based on.` + | :sl:`Get or set the Texture the Image is based on` | :sg:`texture -> Texture` .. attribute:: srcrect - | :sl:`Gets and sets the Rect the Image is based on.` + | :sl:`Get or set the Rect the Image is based on` | :sg:`srcrect -> Rect` + .. attribute:: origin + + | :sl:`Get or set the Image's origin of rotation` + | :sg:`origin -> (float, float) or None` + + Gets or sets the Image's origin of rotation, a 2D coordinate relative to + the topleft coordinate of the Image's rectangular area. + + An origin of ``None`` means no origin was set and the Image will be + rotated around its center. + + .. method:: get_rect + + | :sl:`Get the rectangular area of the Image` + | :sg:`get_rect() -> Rect` + + .. note:: + The returned :class:`Rect` object might contain position information + relative to the bounds of the :class:`Texture` or Image object it was + created from. + + .. method:: draw + + | :sl:`Copy a portion of the Image to the rendering target` + | :sg:`draw(srcrect=None, dstrect=None) -> None` + + :param srcrect: Source rectangle specifying a sub-Image, or ``None`` for the + entire Image. + :param dstrect: Destination rectangle or position on the render target, + or ``None`` for entire target. The Image is stretched to + fill dstrect. + + .. class:: Renderer - | :sl:`Create a 2D rendering context for a window.` + | :sl:`pygame object wrapping a 2D rendering context for a window` | :sg:`Renderer(window, index=-1, accelerated=-1, vsync=False, target_texture=False) -> Renderer` - .. classmethod:: from_window - - | :sl:`Easy way to create a Renderer.` - | :sg:`from_window(window) -> Renderer` + Creates a 2D rendering context for a window. + + :param Window window: The window onto which the rendering context should be + placed. + :param int index: The index of rendering driver to initialize, or ``-1`` to init + the first supporting the requested options. + :param int accelerated: If 1, the renderer uses hardware acceleration. + if 0, the renderer is a software fallback. + ``-1`` gives precedence to renderers using hardware + acceleration. + :param bool vsync: If ``True`` :meth:`Renderer.present` is synchronized with + the refresh rate. + :param bool target_texture: Whether the renderer should support setting + :class:`Texture` objects as target textures, to + enable drawing onto them. + + + :class:`Renderer` objects provide a cross-platform API for rendering 2D + graphics onto a :class:`Window`, by using either Metal (MacOS), OpenGL + (MacOS, Windows, Linux) or Direct3D (Windows) rendering drivers, depending + on what is set or is available on a system during their creation. + + They can be used to draw both :class:`Texture` objects and simple points, + lines and rectangles (which are colored based on :attr:`Renderer.draw_color`). + + If configured correctly and supported by an underlying rendering driver, Renderer + objects can have a :class:`Texture` object temporarily set as a target texture + (the Texture object must have been created with target texture usage support), + which allows those textures to be drawn onto. + + To present drawn content onto the window, :meth:`Renderer.present` should be + called. :meth:`Renderer.clear` should be called to clear any drawn content + with the set Renderer draw color. + + When things are drawn onto Renderer objects, an internal batching system is + used by default to batch those "draw calls" together, to have all of them be + processed in one go when :meth:`Renderer.present` is called. This is unlike + :class:`pygame.Surface` objects, on which modifications via blitting occur + immediately, but lends well to the behavior of GPUs, as draw calls can be + expensive on lower-end models. .. attribute:: draw_blend_mode - | :sl:`Gets and sets the blend mode used by the drawing functions.` + | :sl:`Get or set the blend mode used for primitive drawing operations` | :sg:`draw_blend_mode -> int` .. attribute:: draw_color - | :sl:`Gets and sets the color used by the drawing functions.` + | :sl:`Get or set the color used for primitive drawing operations` | :sg:`draw_color -> Color` + .. attribute:: logical_size + + | :sl:`Get or set the logical Renderer size (a device independent resolution for rendering)` + | :sg:`logical_size -> (int width, int height)` + + .. attribute:: scale + + | :sl:`Get the drawing scale for the current rendering target` + | :sg:`scale -> (float, float)` + + .. attribute:: target + + | :sl:`Get or set the current rendering target` + | :sg:`target -> Texture or None` + + Gets or sets the current rendering target. + A value of ``None`` means that no custom rendering target was set and the + Renderer's window will be used as the target. + + .. classmethod:: from_window + + | :sl:`Create a Renderer from an existing window` + | :sg:`from_window(window) -> Renderer` + .. method:: clear - | :sl:`Clear the current rendering target with the drawing color.` + | :sl:`Clear the current rendering target with the drawing color` | :sg:`clear() -> None` .. method:: present - | :sl:`Updates the screen with any new rendering since previous call.` - | :sg:`present() -> None` + | :sl:`Update the screen with any rendering performed since the previous call` + | :sg:`present() -> None` + + Presents the composed backbuffer to the screen. + Updates the screen with any rendering performed since the previous call. .. method:: get_viewport - | :sl:`Returns the drawing area on the target.` + | :sl:`Get the drawing area on the rendering target` | :sg:`get_viewport() -> Rect` .. method:: set_viewport - | :sl:`Set the drawing area on the target. If area is None, the entire target will be used.` + | :sl:`Set the drawing area on the rendering target` | :sg:`set_viewport(area) -> None` - .. attribute:: logical_size - - | :sl:`Gets and sets the logical size.` - | :sg:`logical_size -> (int width, int height)` + :param area: A :class:`pygame.Rect` or tuple representing the + drawing area on the target, or ``None`` to use the + entire area of the current rendering target. - .. attribute:: scale + .. method:: blit - | :sl:`Gets and sets the scale.` - | :sg:`scale -> (float x_scale, float y_scale)` + | :sl:`Draw textures using a Surface-like API` + | :sg:`blit(source, dest, area=None, special_flags=0)-> Rect` - .. attribute:: target + For compatibility purposes. Draws :class:`Texture` objects onto the + Renderer using a method signature similar to :meth:`pygame.Surface.blit`. - | :sl:`Gets and sets the render target. None represents the default target (the renderer).` - | :sg:`target -> Texture or None` + :param source: A :class:`Texture` or :class:`Image` to draw. + :param dest: The drawing destination on the rendering target. + :param area: The portion of the source texture or image to draw from. + :param special_flags: have no effect at this moment. - .. method:: blit - - | :sl:`For compatibility purposes. Textures created by different Renderers cannot be shared!` - | :sg:`blit(source, dest, area=None, special_flags=0)-> Rect` + .. note:: Textures created by different Renderers cannot shared with each other! .. method:: draw_line - | :sl:`Draws a line.` + | :sl:`Draw a line` | :sg:`draw_line(p1, p2) -> None` + :param p1: The line start point. + :param p2: The line end point. + .. method:: draw_point - | :sl:`Draws a point.` + | :sl:`Draw a point` | :sg:`draw_point(point) -> None` + :param point: The point's coordinate. + .. method:: draw_rect - | :sl:`Draws a rectangle.` + | :sl:`Draw a rectangle outline` | :sg:`draw_rect(rect)-> None` + :param rect: The :class:`pygame.Rect`-like rectangle to draw. + .. method:: fill_rect - | :sl:`Fills a rectangle.` + | :sl:`Draw a filled rectangle` | :sg:`fill_rect(rect)-> None` - .. method:: to_surface - - | :sl:`Read pixels from current render target and create a pygame.Surface. WARNING: Slow operation, use sparingly.` - | :sg:`to_surface(surface=None, area=None)-> Surface` + :param rect: The :class:`pygame.Rect`-like rectangle to draw. .. method:: draw_triangle - | :sl:`Draws a triangle.` + | :sl:`Draw a triangle outline` | :sg:`draw_triangle(p1, p2, p3) -> None` + + :param p1: The first triangle point. + :param p2: The second triangle point. + :param p2: The third triangle point. .. method:: fill_triangle - | :sl:`Fills a triangle.` + | :sl:`Draw a filled triangle` | :sg:`fill_triangle(p1, p2, p3) -> None` + :param p1: The first triangle point. + :param p2: The second triangle point. + :param p2: The third triangle point. + .. method:: draw_quad - | :sl:`Draws a quad.` + | :sl:`Draw a quad outline` | :sg:`draw_quad(p1, p2, p3, p4) -> None` + :param p1: The first quad point. + :param p2: The second quad point. + :param p2: The third quad point. + :param p2: The fourth quad point. + .. method:: fill_quad - | :sl:`Fills a quad.` - | :sg:`fill_quad(p1, p2, p3, p4) -> None` \ No newline at end of file + | :sl:`Draw a filled quad` + | :sg:`fill_quad(p1, p2, p3, p4) -> None` + + :param p1: The first quad point. + :param p2: The second quad point. + :param p2: The third quad point. + :param p2: The fourth quad point. + + .. method:: to_surface + + | :sl:`Read pixels from current rendering target and create a Surface (slow operation, use sparingly)` + | :sg:`to_surface(surface=None, area=None)-> Surface` + + Read pixel data from the current rendering target and return a + :class:`pygame.Surface` containing it. + + :param Surface surface: A :class:`pygame.Surface` object to read the pixel + data into. It must be large enough to fit the area, otherwise + ``ValueError`` is raised. + If set to ``None``, a new surface will be created. + :param area: The area of the screen to read pixels from. The area is + clipped to fit inside the viewport. + If ``None``, the entire viewport is used. + + .. note:: + This is a very slow operation, due to the overhead of the VRAM to RAM + data transfer and the cost of creating a potentially large + :class:`pygame.Surface`. It should not be used frequently. + + .. method:: compose_custom_blend_mode + + | :sl:`Compose a custom blend mode` + | :sg:`compose_custom_blend_mode(color_mode, alpha_mode) -> int` + + Compose a custom blend mode. + See https://wiki.libsdl.org/SDL2/SDL_ComposeCustomBlendMode for more information. + + :param color_mode: A tuple ``(srcColorFactor, dstColorFactor, colorOperation)`` + :param alpha_mode: A tuple ``(srcAlphaFactor, dstAlphaFactor, alphaOperation)`` + + :return: A blend mode to be used with :meth:`Renderer.set_draw_blend_mode` and :meth:`Texture.set_blend_mode`. \ No newline at end of file diff --git a/docs/reST/ref/transform.rst b/docs/reST/ref/transform.rst index 210e7e65ac..832a47c02d 100644 --- a/docs/reST/ref/transform.rst +++ b/docs/reST/ref/transform.rst @@ -238,6 +238,9 @@ Instead, always begin with the original image and scale to the desired size.) .. versionadded:: 2.2.0 + .. versionchanged:: 2.3.0 + Passing the calling surface as destination surface raises a ``ValueError`` + .. ## pygame.transform.box_blur ## .. function:: gaussian_blur @@ -257,6 +260,9 @@ Instead, always begin with the original image and scale to the desired size.) .. versionadded:: 2.2.0 + .. versionchanged:: 2.3.0 + Passing the calling surface as destination surface raises a ``ValueError`` + .. ## pygame.transform.gaussian_blur ## .. function:: average_surfaces diff --git a/docs/reST/themes/classic/elements.html b/docs/reST/themes/classic/elements.html index 300f4124bd..1dfa0bee5f 100644 --- a/docs/reST/themes/classic/elements.html +++ b/docs/reST/themes/classic/elements.html @@ -17,14 +17,22 @@
pygame-ce documentation