function [ds_, attributes_, batchMethods_] = dXdots(num_objects)
% function [ds_, attributes_, batchMethods_] = dXdots(num_objects)
%
% Constructor method for class dots
% Input:
%   num_objects    ... number of objects to create
%
% Output:
%   ds_            ... array of created dots
%   attributes_    ... default object attributes
%   batchMethods_  ... methods that can be run in a batch (e.g., draw)

% Copyright 2004 by Joshua I. Gold
%   University of Pennsylvania

% get screen values
[wn, sr, ppd, fr] = rGraphicsGetScreenAttributes;

% default object attributes
attributes = { ...
    % name              type		values	default
    'coherence',        'scalar',	[],		51.2;	... % pct
    'direction',        'scalar',	[],		0;		... % deg
    'speed',            'scalar',	[],		8.0;    ... % deg/sec
    'seed',             'array',	[],		[];		... % [base coh*dir]
    'size',             'scalar',	[],		3;		... % pixels
    'color',            'array',    [],		[1 1 1]*255;... % [r,g,b]
    'bgColor',          'array',    [],		[0 0 0];... % [r,g,b] for aperture
    'maxPerFrame',      'scalar',	[],		9999;	... % number of dots
    'loops',            'scalar',   [],     3;      ... % interleaved dots
    'duration',         'scalar',   [],     0;      ... % ms (used if preCompute)
    'density',          'scalar',   [],     16.7;   ... % 16.7 dots per sq.deg/sec
    'x',                'scalar',	[],		0;		... % deg visual angle
    'y',                'scalar',	[],		0;		... % deg visual angle
    'diameter',         'scalar',	[],		10.0;   ... % deg visual angle
    'apScale',          'scalar',   [],     1.1;    ... % >1 for bdotsigger field than aperture
    'userData',         'array',	[],		[];		... %
    'smooth',           'scalar',   [],     0.0;    ... % if set = 1, be sure to set dXscreen "blending" to true
    'preCompute',       'scalar',   [],     0;      ... % -1='auto'; 0=no; 1+=#trials
    'groupMotion',      'boolean',  [],     false;  ... % move all dots together, or individually?
    'deltaDir',         'scalar',   [],     0;      ...
    'dirDomain',        'array',    [],     [];     ... % arbitrary directions
    'dirCDF',           'array',    [],     [];     ... % arbitrary directions distribution
    'flickerMode',      'string',   {'random', 'move'},  'random'; ... % displacement of non-coh dots
    'wrapMode',         'string',   {'random', 'wrap'},  'wrap'; ... % dots behavior at edge of aperture
    'lifetimeMode',     'string',   {'random', 'limit'}, 'limit'; ... % force limited lifetime of dots
    'visible',          'boolean',	[],		0;		...
    'tag',              'scalar',	[],		0;      ... % ignored for now
    'debugSavePts',     'boolean',  [],     0;      ... % save all points data for debugging (SLOW!!!!)
    'windowNumber',     'auto',     [],     wn;     ...
    'screenRect',       'auto',     [],     sr;     ...
    'pixelsPerDegree',  'auto',     [],     ppd;    ...
    'frameRate',        'auto',     [],     fr;     ...
    'drawRect',         'auto',     [],     []; ... % where dots are drawn
    'drawSize',         'auto',     [],     []; ... % draw rect width (deg)
    'drawSizePix',      'auto',     [],     []; ... % draw rect width (pix)
    'dirCDFInv',        'auto',     [],     []; ... % arbitrary directions distribution
    'nP',               'auto',     [],     1e2; ... % size of CDFInv domain
    'dxdyDomain',       'auto',     [],     []; ... % components of direction distribution
    'maskColor',        'auto',     [],     [0 0 0]; ... % background color
    'maskRect',         'auto',     [],     []; ... % mask screen location
    'maskSource',       'auto',     [],     []; ... % mask extent in pix
    'maskImage',        'auto',     [],     []; ... % mask RGBA image
    'maskTexindex',     'auto',     [],     []; ... % pointer to GL texture
    'apRect',           'auto',     [],     []; ... % viewable extent in mask
    'dotCoh',           'auto',     [],     []; ...
    'nDots',            'auto',     [],     []; ...
    'jumpSize',         'auto',     [],     []; ...
    'dxdy',             'auto',     [],     []; ...
    'loopIndex',        'auto',     [],     []; ...
    'pts',              'auto',     [],     []; ...
    'Lpts',             'auto',     [],     []; ...
    'ptsHistory',       'auto',     [],     []; ... % ugly, growing log of xy data for debugging
    'sourceRect',       'auto',     [],     []; ... % unimplemented
    'textures',         'auto',     [],     []; ...
    'textureIndex',     'auto',     [],     1};        % see set & recur

% make an array of objects from structs made from the attributes
d = cell2struct(attributes(:,4), attributes(:,1), 1);
for i = 1:num_objects
    ds_(i) = class(d, 'dXdots');
end

% return the attributes, if necessary
if nargout > 1
    attributes_ = attributes;
end

% return list of batch methods
if nargout > 2
    batchMethods_ = {'draw', 'blank'};
end