{"id":13344434,"url":"https://github.com/stefanbylund/zxnext_sprite","last_synced_at":"2025-03-12T07:33:17.078Z","repository":{"id":230231755,"uuid":"96028874","full_name":"stefanbylund/zxnext_sprite","owner":"stefanbylund","description":"C hardware sprite API for Spectrum Next","archived":false,"fork":false,"pushed_at":"2022-06-06T19:31:13.000Z","size":136,"stargazers_count":22,"open_issues_count":0,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-07-30T21:10:07.085Z","etag":null,"topics":["c","sinclair","sprites","zx-spectrum"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefanbylund.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-07-02T14:34:39.000Z","updated_at":"2024-06-06T12:19:26.000Z","dependencies_parsed_at":"2024-03-28T15:17:25.902Z","dependency_job_id":"887f3a5c-d252-4243-b7be-af1f3356eed0","html_url":"https://github.com/stefanbylund/zxnext_sprite","commit_stats":null,"previous_names":["stefanbylund/zxnext_sprite"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanbylund%2Fzxnext_sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefanbylund","download_url":"https://codeload.github.com/stefanbylund/zxnext_sprite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221279969,"owners_count":16790562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","sinclair","sprites","zx-spectrum"],"created_at":"2024-07-29T19:33:09.111Z","updated_at":"2024-10-24T05:30:38.012Z","avatar_url":"https://github.com/stefanbylund.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C Hardware Sprite API for Spectrum Next\n\nThe **zxnext_sprite** project provides a C API for using the hardware sprites of\nZX Spectrum Next as specified at https://www.specnext.com/sprites/. This API is\na thin C wrapper on top of the I/O port interface of the hardware sprite system.\n\nThe [demo](demo) folder contains a simple example program demonstrating how to\nuse this API.\n\n**Note:** This project still works but is a bit out-of-date. It will be updated\nsomeday when I have the time ;)\n\n## Download\n\nThe latest version of this API can be downloaded here:\n\n* [zxnext_sprite.zip](build/zxnext_sprite.zip)\n* [zxnext_sprite_z88dk.zip](build/zxnext_sprite_z88dk.zip)\n\nThe zxnext_sprite.zip archive contains the following header file and libraries:\n\n* zxnext_sprite/include/zxnext_sprite.h\n* zxnext_sprite/lib/sccz80/zxnext_sprite.lib\n* zxnext_sprite/lib/sdcc_ix/zxnext_sprite.lib\n* zxnext_sprite/lib/sdcc_iy/zxnext_sprite.lib\n\nThe zxnext_sprite_z88dk.zip archive contains a packaging of zxnext_sprite that\ncan be installed directly into your z88dk installation for convenience, see the\ntip below.\n\nIf you want to build the zxnext_sprite libraries yourself, see the \"How to Build\"\nsection below.\n\n## API Documentation\n\nThe zxnext_sprite API is documented in the following header file:\n\n* [zxnext_sprite.h](include/zxnext_sprite.h)\n\n## How to Use\n\n1. Download [zxnext_sprite.zip](build/zxnext_sprite.zip) and unpack it in a\nsuitable place. It contains the files listed in the \"Download\" section above.\nFor convenience, you can instead download\n[zxnext_sprite_z88dk.zip](build/zxnext_sprite_z88dk.zip) and install it into\nyour z88dk installation, see the tip below.\n\n2. Install the latest version of [z88dk](https://github.com/z88dk/z88dk) and\nthe [ZEsarUX](https://github.com/chernandezba/zesarux) or\n[CSpect](https://dailly.blogspot.se/) emulator.\n\n4. Read about how hardware sprites work in the \"Hardware Sprites\" section below\nor in the official specification at http://www.specnext.com/sprites/.\n\n5. Familiarize yourself with the zxnext_sprite.h API.\n\n6. Include zxnext_sprite.h in your program and start creating sprites.\n\n7. Compile your program with z88dk and link it with the appropriate version of\nzxnext_sprite.lib.\n\n8. Run your program in the ZEsarUX or CSpect emulator.\n\n**Tip:** See the [demo](demo) folder for a simple example of how to use\nzxnext_sprite.h and link with zxnext_sprite.lib.\n\n**Tip:** You can install zxnext_sprite into your z88dk installation by using\nits third-party library installer z88dk-lib. Unpack the zxnext_sprite_z88dk.zip\narchive in a temporary directory, go to this directory (where the unpacked\nzxnext_sprite subdirectory is located) and enter the following command:\n\n\u003e z88dk-lib +zxn -f zxnext_sprite\n\nThe -f option will make z88dk-lib overwrite any existing files without\nconfirmation (e.g. if you update zxnext_sprite it will replace the older version).\nRun z88dk-lib without any arguments to see a list of all its options.\n\nThe z88dk compiler will now automatically find the zxnext_sprite header file and\nlibrary without the need for setting up any include and library paths. The\nzxnext_sprite.h header file is now included with **#include \u003clib/zxn/zxnext_sprite.h\u003e**\nand the zxnext_sprite.lib library is linked against using **-llib/zxn/zxnext_sprite**.\n\n**Tip:** To start the ZEsarUX emulator directly in Spectrum Next mode, start it\nwith the following options:\n\n\u003e zesarux --noconfigfile --machine tbblue --enabletimexvideo --tbblue-fast-boot-mode\n  --quickexit --enable-esxdos-handler --esxdos-root-dir \u003cvirtual_mmc_root_folder\u003e\n  \u003cmy_program\u003e.nex\n\n**Tip:** To start the CSpect emulator directly in Spectrum Next mode, start it\nwith the following options:\n\n\u003e CSpect -w2 -tv -zxnext -mmc=\u003cvirtual_mmc_root_folder\u003e/ \u003cmy_program\u003e.nex\n\n## How to Build\n\nIf you want to build the zxnext_sprite libraries yourself, follow the steps below:\n\n1. On Windows, you need [MinGW](http://www.mingw.org/),\n[UnxUtils](https://sourceforge.net/projects/unxutils/) or\n[Cygwin](https://www.cygwin.com/) for the basic Unix commands. Add the chosen\nset of Unix commands to your path.\n\n2. Install the latest version of [z88dk](https://github.com/z88dk/z88dk) and add\nit to your path.\n\n3. Download the zxnext_sprite repository either as a ZIP archive using the\n\"Clone or download\" button at the top of this page or with Git using the\nfollowing command:\n\n\u003e git clone https://github.com/stefanbylund/zxnext_sprite.git\n\n4. Go to the zxnext_sprite repository and enter the following command:\n\n\u003e make all\n\n## Hardware Sprites\n\nThe Spectrum Next provides 64 hardware sprites numbered from 0 to 63.\nEach sprite is 16 * 16 pixels where each pixel is an 8-bit index between\n0 and 255 into a 256-colour sprite palette. The sprite pixels are laid out\nlinearly from left to right and top to bottom.\n\nThe sprite palette consists of 256 9-bit RGB333 colour values, i.e. the total\nnumber of colours is 512. There are actually two sprite palettes, which one\nis currently used for diplaying the sprites can be selected at runtime. The\ncolour encoding of the sprite palette is the same as for the palette of the\nULA and layer 2 screens.\n\nAt reset, the sprite palette is initialized with the RGB332 colours 0 to 255\nusing a one-to-one mapping between palette indexes and palette colours, i.e.\npalette index 0 contains colour 0, palette index 1 contains colour 1, ...,\npalette index 255 contains colour 255. The effective palette colours will be\n9-bit RGB333 colours where the lower blue bit is an OR between bit 1 and bit\n0 in the 8-bit RGB332 colours.\n\nOne colour is defined as the global transparency colour. This colour is an\n8-bit RGB332 colour value so the transparency is compared only with the 8\nmost significant bits of the 9-bit RGB333 colours in the sprite palette. This\nmeans that two of the 512 possible RGB333 colours will be transparent. By\ndefault, the global transparency colour is set to the pink colour 0xE3 (227).\n\nTip: If you're drawing your sprites in a general-purpose paint program, it's\ngood to know that the default global transparency colour 0xE3 corresponds to\nthe 24-bit RGB colour 0xE000C0 (224, 0, 192).\n\nSprites can optionally be rendered on the border of the screen. The coordinate\nsystem of the sprites therefore includes the border, which is 32 pixels, and\nthe total sprite resolution is thus 320 * 256 pixels. The standard screen\nresolution is 256 * 192 pixels. This means that if sprites is not rendered on\nthe border, the sprite coordinates range from (32, 32) to (287, 223).\n\nFor convenience, there is an extended version of the set_sprite_attributes()\nfunction, for setting the sprite position, called set_sprite_attributes_ext(),\nwhich accepts screen-based coordinates (256 * 192 pixels) and internally\nconverts them to border-based coordinates (320 * 256 pixels). This function\nis convenient if you prefer to work in screen coordinates and don't want to\nrender the sprites on the border area.\n\nWhen using the sprites there is a differentiation between the actual sprites\nand the sprite pattern (i.e. the sprite bitmap) used by the sprites. There\nare 64 sprites and 64 sprite patterns. The sprite patterns are defined\nindependently of the sprites and are referenced by the sprites. This means\nthat multiple sprites can share the same sprite pattern.\n\nThe sprite pattern is set for the currently selected sprite pattern slot\n(0 - 63). The attributes of a sprite is set for the currently selected sprite\nslot (0 - 63). The sprite attributes determine which sprite pattern the sprite\nshould use, the x and y position of the sprite, an optional sprite palette\noffset, a bit-mask of flags for sprite mirroring and rotation, and whether or\nnot the sprite should be visible.\n\nIf the optional sprite palette offset (0 - 15) is used when setting the\nattributes of a sprite, it is added to the 4 most significant bits of each\n8-bit palette index in the sprite pattern of the sprite. In this way, the\n256-colour sprite palette is effectively divided into 16 sub-palettes\nnumbered from 0 to 15 where each sub-palette contains 16 colours indexed from\n0 to 15. The palette offset then controls which of the 16 sub-palettes should\nbe used. For example, if a pixel in a sprite pattern contains the palette\nindex 0x14, which denotes the colour at index 4 in sub-palette 1, and the\npalette offset is 2, the actual palette index used for that pixel will be\n0x34, which denotes the colour at index 4 in sub-palette 3 (sub-palette 1 +\npalette offset 2). When the palette offset is added to a sub-palette number,\nthe addition is actually done in modulo 16. For example, adding palette\noffset 5 to sub-palette number 13 gives sub-palette number 2. If used, the\npalette offset is an efficient way of displaying the same sprite pattern in\ndifferent colours.\n\nThe priority between the sprites is determined by the sprite slot number.\nSprite 0 has the lowest priority and sprite 63 has the highest priority.\nA sprite with a higher priority is drawn over a sprite with lower priority.\nThe layer priority between the sprites and the layer 2 and ULA screens is\nconfigurable, the default priority is sprites over layer 2 screen over ULA\nscreen.\n\nThe sprite system provides collision detection of the sprites. A collision of\ntwo or more sprites happen if a non-transparent pixel of the sprites are drawn\nin the same position on the screen. The sprite system only informs whether a\nsprite collision has occurred or not, which sprites has actually collided must\nbe determined in software.\n\n## Known Problems\n\nNone.\n\n## License\n\nThis software is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanbylund%2Fzxnext_sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanbylund%2Fzxnext_sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanbylund%2Fzxnext_sprite/lists"}