shadertoy_api 1.0.0-dev.7

  • Readme
  • Changelog
  • Example
  • Installing
  • 49

shadertoy_api #

A Shadertoy client API definition for Dart compatible with all platforms

Pub Package Build Status Coverage Status Package Documentation GitHub License

Introduction #

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

The contracts defined in this library allow the creation of clients to the:

  • Shadertoy REST API, wich as presented in the howto, provides a number of operations that allow the user to browse the shaders currently 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
  • Shadertoy Site API, provides access to the same methods as the previous API but adds more data namely users, playlists, shader comments and website media. Not that The shaders returned by this API should are not constrained by the public+api privacy settings. With that said, the client implementation should support the usage of a suitable user and password providing sign in and out methods or, in alternative, anonymous access.

Finally, this library defines contracts supporting the creation of data stores thus providing a way to work offline with the donwloaded shaders instead of hitting the REST or Site APIs

Capabilties #

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

REST API

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

Site API

All the REST API features plus the following:

  • Login
  • Logout
  • Find user by id
  • Find shaders by user id
  • Query shaders by user id, tags and sort them by name, likes, views, neweness and by hotness (proportional to popularity and inversly propotional to lifetime). All the query results are paginated as well.
  • Find comments by shader id
  • Find playlist by id.
  • Query shaders by playlist id. All the query results are paginated.
  • Query shader ids by playlist id. All the query results are paginated.
  • Download preview, i.e. the the shader thumbnails
  • Download media, any other media provided by the Shadertoy website

Store API

All the REST and Site API features except login, logout, download preview and download media plus the following:

  • Save user
  • Find account by id
  • Query account by name, type and system
  • Save account
  • Save shader
  • Save shader comments
  • Save playlist

Getting Started #

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

dependencies:
    shadertoy_api: ^1.0.0-dev.7

Run the following command to install dependencies:

pub install

Optionally use the following command to run the tests:

pub run test

Finaly, to start developing import the library:

import 'package:shadertoy_api/shadertoy_api.dart';

Usage #

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

ShadertoyWS ws = ...

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 ShadertoySite implementation, for example the one provided by the package shadertoy_client, to access the Site API:

ShadertoySite site = ...

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:

var 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 apropiate configurations for the implementation:

ShadertoyStore store = ...

and execute persitent 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

1.0.0-dev.7 #

  • Updated documentation
  • Improved test coverage
  • Pluralized CommentsResponse field names
  • Added embeded URLs construction method in the Context class

1.0.0-dev.6 #

  • Updated documentation

1.0.0-dev.5 #

  • Updated badges
  • Update minimum sdk to 2.7
  • Added model tests
  • Updated dependencies

1.0.0-dev.4 #

  • Finished the CI process

1.0.0-dev.3 #

  • Several changes in the github repo configuration
  • Github actions for this repo now publish the file to pub
  • README.md now has again the model image since the plantuml proxy does not support https

1.0.0-dev.2 #

  • Added generated files to github
  • Added missing documentation

1.0.0-dev.1 #

  • Initial version

example/example.dart

import 'dart:convert';

import 'package:shadertoy_api/shadertoy_api.dart';

void main() {
  var encoder = JsonEncoder.withIndent('  ');

  // Create a user
  var user = User(
      id: 'userid',
      about: 'About this user',
      memberSince: DateTime.now(),
      shaders: 1,
      comments: 1);
  print(encoder.convert(user));

  // Creates a anonymous site account
  var anonymousSiteAccount =
      Account.anonymous(displayName: 'Anonymous site user');
  print(encoder.convert(anonymousSiteAccount));

  // Creates a registered site account
  var registeredSiteAccount = Account.registered(
      name: 'userId',
      displayName: 'Registered site account',
      password: 'password');
  print(encoder.convert(registeredSiteAccount));

  // Creates a api account
  var apiAccount = Account.api(displayName: 'API account', apiKey: 'apikey');
  print(encoder.convert(apiAccount));

  // Creates a Shader with two render passes
  var shader = Shader(
      version: '0.1',
      info: Info(
          id: 'ZzZ0Zz',
          date: DateTime.fromMillisecondsSinceEpoch(1360495251),
          views: 131083,
          name: 'Example',
          userId: 'example',
          description: 'A shader example',
          likes: 570,
          publishStatus: PublishStatus.public_api,
          flags: 32,
          tags: [
            'procedural',
            '3d',
            'raymarching',
            'distancefield',
            'terrain',
            'motionblur',
            'vr'
          ],
          hasLiked: false),
      renderPasses: [
        RenderPass(
            name: 'Image',
            type: RenderPassType.image,
            description: '',
            code: 'code 0',
            inputs: [
              Input(
                  id: '257',
                  src: '/media/previz/buffer00.png',
                  type: InputType.texture,
                  channel: 0,
                  sampler: Sampler(
                      filter: FilterType.linear,
                      wrap: WrapType.clamp,
                      vflip: true,
                      srgb: true,
                      internal: 'byte'),
                  published: 1)
            ],
            outputs: [
              Output(id: '37', channel: 0)
            ]),
        RenderPass(
            name: 'Buffer A',
            type: RenderPassType.buffer,
            description: '',
            code: 'code 1',
            inputs: [
              Input(
                  id: '17',
                  src: '/media/a/zs098rere0323u85534ukj4.png',
                  type: InputType.texture,
                  channel: 0,
                  sampler: Sampler(
                      filter: FilterType.mipmap,
                      wrap: WrapType.repeat,
                      vflip: false,
                      srgb: false,
                      internal: 'byte'),
                  published: 1)
            ],
            outputs: [
              Output(id: '257', channel: 0)
            ])
      ]);
  print(encoder.convert(shader));

  // Creates a shader comment
  var comment = Comment(
      shaderId: 'AaA0Aa',
      userId: 'userId',
      date: DateTime.now(),
      text: 'Great shader!');
  print(encoder.convert(comment));

  // Creates a playlist
  var playlist =
      Playlist(id: 'ZzZ0Zz', name: 'Playlist', count: 1, shaders: ['ZzZ0Zz']);
  print(encoder.convert(playlist));
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  shadertoy_api: ^1.0.0-dev.7

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:shadertoy_api/shadertoy_api.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
95
Overall:
Weighted score of the above. [more]
49
Learn more about scoring.

We analyzed this package on Apr 7, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6

Maintenance suggestions

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
equatable ^1.0.1 1.1.1
json_annotation ^3.0.0 3.0.1
meta ^1.1.8 1.1.8
Transitive dependencies
collection 1.14.12
Dev dependencies
build_runner ^1.7.2
build_verify ^1.1.1
json_serializable ^3.2.3
pedantic ^1.9.0
test ^1.9.4
test_coverage ^0.4.0