shadertoy_api

A Shadertoy client API definition for Dart

Pub Package Build Status Coverage Status Package Documentation GitHub License

Introduction

Provides a definition of the contracts and entities needed to create a Shadertoy dart client.

Three main types of contracts are defined in this library:

  • A Client API, for the REST interfaces defined in the Shadertoy howto that allow the user to browse shaders available with public+api privacy settings. Note that the number of operations available with this API are limited albeit enough for simple browsing usage. To start using this type of client a API key should be obtained for a properly registered user on the apps page and the client implementation should support providing it at the time of the construction
  • Extended Client API, provides access to the same methods as the previous API but adds methods namely users, playlists, shader comments and website media. Note that the shaders returned by this API should not be constrained by the public+api privacy settings.
  • Store API, defines contracts supporting the creation of data stores thus providing a way to work offline with the downloaded shaders instead of hitting the client or extended client APIs. It supports all the methods as the previous API plus the storage primitives.

Capabilities

This package provides a number of operations through two types of clients:

Client API

  • Find shader by id
  • Find shaders by a list of id's
  • Query shaders by term, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters
  • Find all shader ids
  • Query shader ids by term, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters

Extended Client API

All the client API features plus the following available on a extended API:

  • Find user by id
  • Query shaders by user id, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters
  • Query shaders by user id, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters
  • Find all shader ids by user id
  • Find comments by shader id
  • Find playlist by id.
  • Query shaders by playlist id. All the query results are paginated through the from and num parameters
  • Query shader ids by playlist id. All the query results are paginated through the from and num parameters

Store API

All the base and extended client API features plus the following:

  • Save user
  • Save users
  • Save shader
  • Save shaders
  • Save shader comments
  • Save playlist
  • Save playlist shaders

Getting Started

Add this to your pubspec.yaml (or create it):

dependencies:
    shadertoy_api: ^1.0.9

Run the following command to install dependencies:

pub get

Finally, to start developing import the library:

import 'package:shadertoy_api/shadertoy_api.dart';

The following client and storage API implementations are available

PluginsStatusDescription
shadertoy_clientPubHTTP client to the Shadertoy REST and Site API
shadertoy_moorPubA Moor storage implementation using the moor package

Usage

Instantiate a ShadertoyClient implementation, for example the one provided by the package shadertoy_client, to access the client API:

final ws = newShadertoyWSClient('xx');

and execute one of the methods provided, for example to obtain a shader by id execute findShaderById providing the id of the shader as parameter:

var fsr = await ws.findShaderById('...');
if (fsr.ok) {
    print(fsr?.shader);
} else {
    print('Error: ${fsr.error.message}')
}

In alternative instantiate a ShadertoyExtendedClient implementation, for example the one provided by the package shadertoy_client, to access the Site API:

final site = newShadertoySiteClient();

and execute one of the methods provided, for example to obtain the shader comments by shader id execute findCommentsByShaderId providing the id of the shader as parameter:

final fsr = await site.findCommentsByShaderId('...');
if (fsr.ok) {
    fsr.comments.forEach((c)=> print(c.text));
} else {
    print('Error: ${fsr.error.message}')
}

To create a database providing the same set of read operations as the previous contracts but also the ability to save shaders as well as other entities a ShadertoyStore contract is also provided. The user should instantiate a ShadertoyStore providing the appropriate configurations for the implementation:

ShadertoyStore store = ...

and execute persistent operations, for example storing the definition of a shader in the store with:

var shader = Shader(...);
var ssr = await store.saveShader(shader);
if (ssr.ok) {
    print('Shader stored');
} else {
    print('Error: ${response.error.message}')
}

Model

Shadertoy API Model

Contributing

This a unofficial Shadertoy client library API. It is developed by best effort, in the motto of "Scratch your own itch!", meaning APIs that are meaningful for the author use cases.

If you would like to contribute with other parts of the API, feel free to make a Github pull request as I'm always looking for contributions for:

  • Tests
  • Documentation
  • New APIs

Features and Bugs

Please file feature requests and bugs at the issue tracker.

License

This project is licensed under the MIT License - see the LICENSE file for details

Libraries

shadertoy_api
A library defining the contracts and entities used to create clients and persistent stores based on the Shadertoy data model
shadertoy_util
A library defining a number of utilities to use with the shadertoy data model